# 技能与工具

> 技能（SKILL.md）的格式与写法、导入导出、团队与个人的归属、试运行调试，以及 agent 可调用的工具。

来源：https://www.scirouter.cn/docs/skills · 更新于 2026-10-23

技能是写给模型的方法指南，记录用户或团队完成某一类工作的步骤、口径与检查项。技能写一次后，Chat、论文研读、百宝箱与课题中的 agent 在需要时自行读取。

## 技能格式

一张技能是一份 `SKILL.md`，采用 [Agent Skills](https://agentskills.io) 的通用格式：顶部为 frontmatter，其后为 Markdown 正文。

| 部分 | 字段 | 规则 |
|---|---|---|
| frontmatter | `name` | 技能名：小写字母与数字，以单个连字符分隔，2–47 位；创建后不能修改 |
| frontmatter | `description` | 一句话写明「做什么、什么时候用」，不超过 1024 字 |
| frontmatter | `license`、`compatibility`、`allowed-tools`、`metadata` | 可选 |
| 正文 | 无 | Markdown，不超过 20000 字，面向第一次做这件事的人 |

### 读取方式

模型不在每次执行时读取技能全文。每次执行开始时，模型得到一份目录，每张技能占一行：名字、标题与 `description`（目录中只给这一句的前 120 字）。

模型按这一行判断技能与当前任务是否相符：相符时用 `skill` 动作按名字读取全文，不相符时不读取。因此 `description` 是技能中最关键的一句。

读到的全文作为做事方法的参考资料交给模型，不作为指令；与本次任务的要求冲突时，以任务要求为准。

### 不适用的内容

以下三类内容不写成技能：

- 每次都必须照做的常驻偏好：模型只在任务相符时才读取技能。
- 需要模型复述的资料：资料放入附件或网盘。
- 可执行的程序：导入时附带的脚本，平台只保存，不运行。

## 使用范围

读取技能的 agent：

- Chat 的每一轮（含论文研读中的问答与 AI 助手）。每一轮开始时读取目录，技能修改后下一轮即使用新版本。
- 论文研读的概述与逐段精读。
- 百宝箱的写作类任务。
- 课题的席位：按角色预设带入团队技能与平台方法卡，开跑时钉住版本；运行中修改技能不影响进行中的课题。

### 归属

| 归属 | 编写者 | 使用者 |
|---|---|---|
| 平台方法卡 | 随平台发布，只读 | 课题的规划与席位（见[课题](https://www.scirouter.cn/docs/campaigns)「方法卡」） |
| 团队技能 | 团队负责人 / 管理员 | 团队成员，在团队工作区中使用 |
| 个人技能（界面显示为「我的技能」） | 本人 | 仅本人可见，在本人的所有工作区中均可使用 |

- 团队方法卡即团队技能，在团队技能页维护；课题中的「方法卡」页只读。平台方法卡只供课题使用，不进入 Chat 的目录。
- 在团队工作区中，个人技能的内容对他人不可见，团队负责人与管理后台均看不到；团队中可见的只有每一轮调用的模型与花费。

### 入口

控制台导航中的「技能」（`/console/skills`）。个人工作区显示「我的技能」列表；团队工作区另有「团队技能」标签。带团队 id 的团队技能页为 `/console/teams/<团队>/skills`。

### 存储位置

技能的正本保存在网盘系统目录「技能」下，每张技能一个文件夹 `<name>/`，其中为 `SKILL.md`。导入压缩包时附带的 `scripts/`、`references/`、`assets/` 一并放入该文件夹。

- 在网盘中直接修改 `SKILL.md` 后，无需重新导入：下次打开该技能或模型读取它时，自动同步为新版本。名字不变，修改 `name` 不生效。
- 附带文件只随技能存放，平台不执行。模型读取技能时可看到有哪些附带文件；需要运行代码时，由模型使用沙箱。
- 用其他工具（Claude Code、Codex、Cursor、Copilot）编写的技能，打包为 `.zip` / `.skill` 放入网盘后，从网盘导入，见[导入与导出](#导入与导出)。

## 编写技能

### 设计要点

| 要点 | 说明 |
|---|---|
| 做什么 | 一类工作，一次性任务不写成技能。「润色英文论文的摘要与引言」是技能；「润色我这篇稿子」是一次提问 |
| 什么时候用 | 用户会如何描述这件事。模型在目录中只看到 `description` 这一句，须能凭这一句识别任务 |
| 如何检查 | 完成后如何判断结果正确。写在正文末尾，模型按此自查 |

### 完整示例

以下是一张虚构的「论文润色」技能，包含全部字段，可作为模板修改：

```markdown
---
name: paper-polish
description: 润色英文科研论文的摘要、引言与讨论：改语法与用词、统一术语、压缩冗长句，不改数据与结论。用户要求「润色」「改英文」「让摘要更像母语写的」「投稿前检查语言」时用；只翻译或只查拼写时不用。
license: CC-BY-4.0
metadata:
  title: "论文润色"
  applies: "摘要, 引言, 讨论, 投稿前检查"
  version: "3"
  source: "SciRouter"
---

# 论文润色

## 目标

把一段英文科研文字改到能直接投稿的语言水平，同时**一个数据、一个结论都不改**。

## 步骤

1. 先通读一遍，列出这段文字的研究对象、主要结果与结论，润色时拿它核对。
2. 按句处理：
   - 语法与时态：方法用过去时，已确立的事实用现在时；
   - 主语要是具体的对象，少用 "It is shown that…"；
   - 一句超过 35 个词就拆；
   - 同一个概念全文一个说法（先看引言里怎么叫）。
3. 术语与缩写：第一次出现写全称加缩写，之后只用缩写。
4. 不碰的内容：数字、单位、置信区间、物种名与基因名的大小写、引用编号。拿不准的地方加「[请作者确认]」，不要替作者改意思。
5. 交付两份：改好的全文，以及一张「改动清单」（原句 → 新句 → 为什么）。

## 怎么检查

- 改动清单里的每一条都能对回原文；
- 用第 1 步列的结果与结论逐条对照改后的文字，没有被改掉或改弱的；
- 全文术语一个说法，缩写都先定义过；
- 没有一个数字、单位与引用编号与原文不同。
```

### description 的写法

- 用第三人称写明「做什么」与「什么时候用」，两项缺一不可：「润色英文论文……用户要求润色、改英文时用」。
- 包含用户会使用的词。用户说「改英文」「投稿前检查语言」时，描述中有这些词，模型才能识别。
- 写一句不适用的情况。目录中有多张相近的技能时，这一句帮助模型区分。
- 在前 120 字内写完最关键的内容，目录中只给这一段。
- 不写口号（「高质量的学术写作助手」）。模型需要的是判断依据，形容词不提供依据。

### 正文的写法

- 结构为目标、步骤、检查。步骤按执行顺序编号，每一步写明输入、动作与输出。
- 面向第一次做这件事的人，不省略「大家都知道」的口径；模型即是第一次做的人。
- 篇幅控制在几千字以内。目录只占一行，但读取全文会占用本轮的上下文；篇幅较长的参考资料放在网盘中，正文写明读取位置。
- 不写「每次都必须照做」的常驻偏好，也不在正文中要求模型忽略任务或平台的要求。技能作为资料读取，这类句子不生效，导入时也会被标出。
- 不从不可信的来源导入技能：技能原文会进入模型的上下文。

## 导入与导出

导入支持三种来源：

| 来源 | 操作 |
|---|---|
| 粘贴 | 将 `SKILL.md` 全文（或仅正文）粘贴到输入框 |
| 本地 `.md` 文件 | 选择文件，由浏览器读取为文字 |
| `.zip` / `.skill` 压缩包 | 从网盘中选择。包内须有一个顶层文件夹与一个 `SKILL.md`，其余文件按相对路径放入技能文件夹 |

导入时先显示预览，确认后才保存。预览中标出以下情况：

| 情况 | 处理 |
|---|---|
| 名字不合规 | 给出修改后的建议值，修改后才能保存 |
| 与已有技能同名（含停用的） | 标出 |
| 描述超过上限 | 截断在最后一个句号处，全文移入正文开头的「什么时候用」一节 |
| 正文超长 | 标出 |
| 正文中的网址与「忽略以上指令」一类句式 | 只提醒，不拦截 |
| 不识别的 frontmatter 字段 | 列出，不导入 |

导出即下载当前版本（或在历史中选中的版本）的 `SKILL.md`。文件按通用格式生成，`metadata` 中带 `title`、`applies`、`version` 与 `source: "SciRouter"`，可直接用于 Claude Code、Codex、Cursor、Copilot 等工具。

## 团队与个人

### 目录的组成

每次执行的目录最多放入平台设定的张数（运行参数「技能 → 技能目录最多几张」，预设 30）：

- 个人工作区：个人技能。
- 团队工作区：团队技能与个人技能。先为个人技能保留若干位置（预设 10），其余给团队技能，仍有空位时再补入个人技能。
- 均按最近修改时间优先；停用的个人技能与归档的团队技能不进入目录。
- 同名时团队技能优先，同名的个人技能本次不进入目录。

### 复制

复制均为快照并记录来源；复制后两份各自修改，不同步。

| 方向 | 操作者 | 名字 |
|---|---|---|
| 团队技能 → 个人技能 | 团队的任何成员 | 可沿用原名 |
| 个人技能 → 团队技能 | 团队负责人 / 管理员 | 可沿用原名 |
| 平台方法卡 → 个人技能 | 任何人 | 必须改名，默认 `my-<原名>`（技能不能与平台方法卡同名） |

### 版本

每次保存生成一个新版本。旧版本可查看，也可「用这一版另存」，即将该版作为新版本保存，历史不变。只改变停用 / 归档状态不生成新版本。

### 停用、删除与归档

| 操作 | 适用对象 | 效果 |
|---|---|---|
| 停用 | 个人技能 | 不进入目录，保留，可恢复 |
| 删除 | 个人技能 | 删除全部版本，网盘文件夹移入回收站。已读取过该技能的对话中，读到的内容仍保留在这些对话中 |
| 归档 | 团队技能 | 团队技能只能归档，不能删除：课题钉住的版本须始终可读 |

新建、导入或复制时与停用的技能同名，不会自动恢复该技能，需改名或先恢复该技能。

### 上限

每人的技能张数（含停用的）、每张保留的版本数、正文合计容量均有上限，技能页显示当前值与已用量。团队技能的张数另行计算。

## 试运行

技能写完后最常见的问题是：模型在应读取时没有读取，或在不应读取时读取了。两种情况都源于 `description` 这一句，试运行用于检查这一句。

在技能卡片上点击「试运行」，输入一句任务（写法与平时提问相同）。平台发起一次真实的单步运行：目录中只有该技能，动作只有读技能与计算，按实际用量消耗本人（团队技能为团队）的配额，与平时提问相同。页面轮询显示：

| 内容 | 说明 |
|---|---|
| 交给模型的目录 | 目录中这一行的实际内容 |
| 是否读取 | 模型是否调用 `skill` 读取该技能，以及首次读取的时间 |
| 轨迹 | 执行的动作：读技能、计算、重试等 |
| 输出 | 运行中为实时写出的内容，结束后为最终产出 |
| 花费 | 本次使用的配额与输入、输出的 token 数 |

模型最后另起一段「【试运行说明】」，写明是否读取、读取或不读取的原因，以及读取后哪些做法来自技能。

### 调试步骤

1. 用一句应当使用该技能的任务试运行。未读取时，说明 `description` 不够清楚，补上用户会使用的词。
2. 用一句不应使用该技能的任务试运行。读取了时，说明 `description` 范围过宽，加一句「……时不用」。
3. 读取了但结果不对时，修改正文的步骤与检查项，再次试运行对比。

模型始终不读取某张技能时，先用试运行确认目录中那一行的内容。常见原因是 `description` 未包含提问时使用的词，或前 120 字未写到「什么时候用」。目录已满（张数达到上限）时按最近修改优先，长期未修改的技能可能不在目录中。

试运行可中途停止，花费计到停止时为止。平台可在运行参数中关闭试运行，关闭后卡片上不显示该按钮。

团队外部工具的调试不在此处进行：在团队的「扩展」页登记 MCP 服务器后点击「测试」，服务端逐步显示连通、列出工具、用样例参数调用一个工具的结果。

## agent 可用的工具

模型在一次执行中可调用的动作，由平台按工作区、团队的「外部检索」档位与本轮的开关决定是否提供。轨迹中显示的名称即下表中的动作名：

| 动作 | 用途 | 提供条件 |
|---|---|---|
| `search` | 查文献：在 arXiv、CrossRef、Semantic Scholar 中检索论文 | 部署接入了文献检索；团队工作区需「核对 + 相似性」档 |
| `web_search` | 搜索网页 | 部署接入了搜索；团队工作区需「核对 + 相似性」档 |
| `fetch` | 读取网页（含 PDF）正文，只读取对话中出现过的链接 | 本轮开启联网；团队工作区需「核对 + 相似性」档 |
| `precedents` | 找先例：按登录号 / 基因 / 化合物查找关联文献 | 团队工作区需「核对 + 相似性」档 |
| `read_record` | 读原始记录：一条序列记录中的一段原文及其中的特征 | 团队工作区需「只核对」档及以上 |
| `calc` | 计算：求一个算式的值，不访问网络 | 始终提供 |
| `run_code` | 在平台沙箱中运行代码（见[网页 Chat](https://www.scirouter.cn/docs/chat-web)「运行代码」） | 部署开启沙箱 |
| `skill` | 读技能：按名字读取目录中一张技能的全文 | 目录中有技能时 |
| `mcp__<服务器>__<工具>` | 团队外部工具：团队在「扩展」页登记的 MCP 服务器上启用的工具 | 只提供给课题的席位，以及团队工作区中开启联网的 Chat |

- 「外部检索」档位是团队设置，分三档：核对 + 相似性、只核对、全部关闭；平台设置的上限会压低该档位。会把检索词发到平台外的动作需要最高档；只发送标识符的动作在「只核对」档即可使用。个人工作区不受该约束。
- 调用团队外部工具时，参数发送到对应的服务器；工具的说明与返回内容作为资料交给模型，不作为指令。团队外部工具不出现在 `/v1` 托管工具与 MCP 服务端中，平台不将团队的工具转给团队以外的人。
- 技能的 `allowed-tools` 字段原样保存与导出，平台不按它限制动作；动作的提供规则以上表为准。
- 模型调用按用量计费；联网搜索按次、读到的网页 PDF 按页、运行代码按 CPU 秒另行计费，单价见[定价页](https://www.scirouter.cn/pricing)；其余工具不计费。

## 相关

- Chat 中运行代码、断开后继续写完回答：[网页 Chat](https://www.scirouter.cn/docs/chat-web)
- 课题的方法卡、席位与角色预设：[课题](https://www.scirouter.cn/docs/campaigns)、[课题：多模型协作](https://www.scirouter.cn/docs/campaigns-collab)
- 用 API Key 接入平台的工具与方法卡：[MCP 与托管工具](https://www.scirouter.cn/docs/mcp)