Skill Creator

---
name: skill-creator
description: 当学生说"我想做一个自己的技能"、"每次都要重复交代同样的要求"、"能不能把这套流程固定下来"、"帮我改一下我那个技能"时使用。先判断他手上已经有什么（一句想法 / 一段聊过的流程 / 一份写坏的草稿），从当前对话里能抠出来的答案就不要再问，查清运行时可声明的能力后直接写出一版完整可跑的 SKILL.md，只把剩下的关键分歧用一张选择题卡问完，改定后出确认卡存进技能库。
category: skill-authoring
version: 0.3.2
status: draft
priority: P0
compatible_agents:
  - claude-code
  - nestudy
  - generic-llm-agent
display_name: 做一个自己的技能
capabilities:
  - list_capabilities
  - propose_skill
optional_capabilities:
  - read_skill
  - ask_user
outputs:
  - chat
max_rounds: 20
suggest_hint: 有什么流程你反复交代过好几次？用「做一个自己的技能」把它固定下来
---

# 做一个自己的技能 / Skill Creator

把学生反复用到的一套做法，变成一份能真正跑起来的 `SKILL.md`。

技能不是"给 AI 的一段说明"，是**一份可执行的规格**：它决定 agent 在什么时候被唤起、
能碰哪些数据、按什么步骤走、哪些事不许做。

## 先定位，别从头走流程

学生来的时候手上已经有东西了，位置不同，起点就不同：

| 他手上有 | 从哪一步开始 |
|---|---|
| 一句想法（"想做个错题整理的技能"） | 第 1 步，走完整流程 |
| **刚才这段对话本身**（"把你刚才那套做法存下来"） | **直接进第 2 步写草稿**——流程就在上面，别再问一遍 |
| 一份自己写的草稿 | 跳到第 3 步，指出问题并改，不要推倒重写 |
| 一个已存在的技能要改 | `read_skill` 读回来，只改他要改的部分，`version` 照「字段怎么定」升一级 |

**最费时间的错误是不管他在哪一步，都从"你想做个什么技能"开始问。**

尤其是第二种：学生说"把刚才那套存下来"时，触发场景、流程、边界基本都在上文里——
他纠正过你哪几次、你读了什么、他嫌你多做了什么，这些就是这个技能要写的东西。
**先把这些抠出来，只补真正空着的格子。**

## 何时使用 / When to use

- 学生发现自己反复在交代同一套要求（"每次都要提醒你先看我的课表"）
- 刚聊完一段他满意的流程，想固定下来
- 他有一套自己的方法想固定（错题整理的流程、面试准备的清单）
- 他想改自己之前做的某个技能

**不适用于** / Not for：

- 只是想让 AI 这一次按某种方式回答 —— 直接说就行，不必做成技能
- 想要的能力运行时根本没有（比如收发邮件）—— 技能只能调用已有能力，
  做不出新能力。这种情况如实说，别写一个跑不起来的壳

## 流程 / Process

### 1. 查能力 + 抠现成答案

调 `list_capabilities`，记住有哪些读能力、哪些提案能力、哪些提问能力。
**这一步在动笔之前，不能省**——能力名是运行时定的，凭印象写会声明出一个不存在的名字，
那个技能装上去就是坏的。没有这个工具时也不要凭印象补，按下文「没有这些工具时（降级）」不声明能力。

同时把上文里已有的答案抠出来：他说过的原话、走过的步骤、纠正过你的地方。

学生说"我想要个类似 X 的"、或者已有技能与他要的重叠时，用 `read_skill` 读 X 当范本。
**读参考技能不会把你切走**——本 skill 声明了 `read_skill`，运行时据此把这类读取当查资料处理：
能力面不变，`propose_skill` / `ask_user` / `list_capabilities` 都还在，读完继续走下面的流程。
不要因为看到了别的 skill 的正文就改按它的流程走。
（学生如果是真想**改用**那个技能，让他点输入框上那张卡右侧的 ✕ 退出本技能，再重新说一次。）

### 2. 直接写出完整第一版

按下面的骨架写一份**完整**的 SKILL.md 贴给他看。拿不准的按最保守的选项定并标出来：

- 拿不准要不要写库 → **不声明 capabilities**（缺省即只读，最安全）
- 拿不准触发场景 → 用他自己的措辞写 `description`，标注"这句最关键"
- 拿不准边界 → 先写三条通用的（不代写、不编造、不替他做决定），标注待确认

不要贴填空模板让他填。**贴一份能跑的完整草稿。**

### 3. 同一轮把剩下的分歧一次问完

调 `ask_user`，最多 4 问，**只问上文里没有、而且会改变技能形状**的：

| 问什么 | 为什么值得占一问 | 选项举例 |
|---|---|---|
| 什么时候该自动派上用场 | `description` 是 agent 判断触发的唯一依据，写空了这技能永远不会被想起来 | 我说要用才用 / 每周固定时候 / 遇到某类情况自动 |
| 要不要能改你的数据 | 决定 capabilities 的形状，也决定用户看到多大的授权面 | 只看不改 / 可以帮我加事项 / 可以帮我存文档 |
| 绝对不许做什么 | 好技能与坏技能的差别多半在边界上，而作者一开始想不到写边界 | 不替我做决定 / 不编造我没说过的 / 不代写文书 / 都要 |

上文里已经有答案的就别问。三问全有答案就直接跳到第 4 步。
**不要问"这样可以吗""要不要我写出来"**——草稿已经在他眼前了。

### 4. 改定并出卡

按答案调整，然后调 `propose_skill`。卡片会显示解析结果与授权范围，
解析不过会列出错误——**照着错误改，再提一次**。
不要在出卡前再问一句"确认要保存吗"，卡片本身就是那次确认。

## 怎么写 description —— 这一段决定技能有没有用

`description` 是 agent 唯一的触发依据。写不好，技能存进去也永远不会被想起来。

**已知的失败方向是"不触发"，不是"乱触发"。** 所以要写得**主动一点**：
不只写它做什么，还要写**学生会说的哪些话应该唤起它**，把原话直接塞进去。

```
弱：整理错题
强：当学生说"这次考试错了好几道"、"帮我看看错题"、"这题我又错了"时使用。
    把错题按知识点归类，标出重复错的那几个点，产出一份可存档的错题整理。
    只整理他给出的题，不编题也不代解。
```

写完自查一遍：**说三句他真会说的话，对着 description 看会不会命中。**
命不中就把那三句的措辞加进去。

## 正文怎么写

- **用祈使句**："先读事项" 而不是 "应该先读一下事项"
- **解释为什么**，别堆全大写的 MUST。模型有判断力，告诉它这条规则在防什么，
  它能处理你没写到的情况；只给一条硬命令，它在边界上就只会照字面办。
  写着写着出现"绝对必须""严禁"时停一下，多半可以换成一句"因为……"
- **边界要具体**："不代写文书" 比 "保持诚信" 有用一百倍
- **先写完再回头看**。写完通读一遍，删掉那些不出力的句子——
  正文越长模型越容易抓错重点

## SKILL.md 骨架 / Skeleton

```markdown
---
name: <kebab-case，和技能同名>
description: <当学生说"…"、"…"时使用。做什么、不做什么。写满信息，这是 agent 的判断依据>
category: <大类，如 study-planning>
version: 0.1.0
status: draft
priority: P0
compatible_agents:
  - claude-code
  - nestudy
  - generic-llm-agent
display_name: <中文名，界面上显示的>
capabilities:          # 不写 = 只读。要写库才列，且只列真正用到的
  - <来自 list_capabilities>
outputs:
  - <chat / document / canvas / event>
max_rounds: <1-100>
suggest_hint: <一句话，运行时主动建议时说的>
---

# <中文名 / English name>

<一两句话说清楚它做什么。>

## 何时使用
- <具体场景>

**不适用于**：
- <边界外的场景，指向别的技能>

## 流程
1. <步骤，写清楚每步读什么、产出什么。默认先做出东西再问>

## 输出格式
<给个模板>

## 边界
- **不…**：<理由>
```

## 字段怎么定 / Fields

- 只读的流程**别声明 capabilities**——不写就是只读，这是最安全的默认值
- 要写库才声明，且只声明真正用到的。多声明不会更强，只会让用户看到不必要的授权
- `outputs` 要和 capabilities 对上：`document` 要有 `propose_artifact`，
  `canvas` 要 `propose_canvas`，`event` 要 `propose_events`
- `max_rounds` 给够但别虚高：一次问完再产出的流程 20 上下够用，
  一问一答的访谈类要到 50 以上。给 100 不会更强，只会让它有机会绕远路
- 这个技能自己要不要问用户？要就声明 `ask_user`，并在正文里写清楚"先做出东西再问"
- **改已有技能要升 `version`**：不升的话，覆盖前后两版的版本号一样，出了问题分不清是哪一版。
  新增步骤、能力或输出段升 minor（`0.1.0 → 0.2.0`，末位归零）；只改措辞、例子或边界升 patch（`0.1.0 → 0.1.1`）。
  原技能末尾有变更记录表的，在表格最上方加一行写明这次改了什么；没有就不必新建

## 输出格式 / Output

第一版草稿（与问题卡同一轮发出）：

````markdown
先按你说的写了一版，你看着改：

```markdown
<完整的 SKILL.md 原文>
```

**我拿不准、替你定了的：**
- <标注 1，下面问你>
- <标注 2>
````

## 没有这些工具时（降级） / Without these tools (degraded mode)

上面的流程按 nestudy 的工具写。在 Claude Code 或其他没有这些工具的环境里，流程和边界不变，只把工具换成下表的做法，
并在草稿上方写明「降级：没有 nestudy 工具，能力名没有核对，这份 SKILL.md 没有经过运行时校验」。

| 工具 | 没有时怎么做 |
|---|---|
| `list_capabilities` | 查不到能力清单，就不声明 `capabilities` 和 `optional_capabilities`（缺省只读），`outputs` 只写 `chat`；原本要写库的步骤改成"输出一张 Markdown 卡片请使用者自己保存"。学生贴出了他那个运行时的能力清单，才可以从清单里挑名字 |
| `read_skill` | 请学生把要改的那份 SKILL.md 原文贴进来；拿不到原文就不动手，不凭记忆重写 |
| `ask_user` | 在对话里直接问：同样最多 4 问、每问给选项，一次问完，然后停下等他回答 |
| `propose_skill` | 把定稿的完整 SKILL.md 放进一个代码块交给学生，请他自己保存或导入他用的运行时，并写明这个技能能不能改他的数据；不说"已保存" |

交出之前，把 `propose_skill` 平时替你查的几项自己核一遍：frontmatter 用 `---` 包住，每行是「键: 值」或「- 列表项」；
`name` 是小写 kebab-case；`description` 只占一行；`version` 是三段数字；`category`、`status`（新建写 `draft`）、
`priority`、`compatible_agents` 都在；正文不为空；`outputs` 与 `capabilities` 对得上（见「字段怎么定」）。

## 边界 / Boundaries

- **不编造能力名**：`capabilities` 里的每一个都必须来自 `list_capabilities` 的返回。
  拿不准就再查一次。写错了那个技能装上去就是坏的。
- **不替学生想需求**：草稿是让他改的靶子，不是替他决定。
  每一处你自己拿的主意都要**标出来**，别混在正文里假装是他的意思。
- **不重问上文已经答过的**：他刚说过的话再问一遍，比不问更让人烦。
- **不省略边界那一问**：没有边界的技能等于没有约束的 agent。
- **不夸大**：技能只能调用已有能力。学生要的做不到就直说，不要写一份看起来能跑、
  实际调不到工具的规格。
- **不代替确认**：写完必须走 `propose_skill` 出卡（没有这个工具就交 Markdown 卡片，由他自己保存），由学生自己看过授权范围再存。
- **写自己的边界也要老实**：生成的技能会写库时，在草稿里明确告诉他"这个技能能改你的数据"。
- **不写会伤人的技能**：诱导学生造假申请材料、伪装成他本人对外发言、绕过学校规定的，
  一律拒绝并说明理由。"扮演某个角色陪我练面试"这类没问题。

## Token 控制 / Token discipline

- `list_capabilities` 一次调完，不要每写一个字段查一次
- 草稿只贴完整的这一次；改定后只贴改动的那几行 + 最后 `propose_skill` 那一份
- 问题一次问完。运行时对连续追问有硬上限，一次一问会在写完之前就把额度用光

## 变更记录 / Changelog

| 版本 | 日期 | 变更 | 类型 |
|---|---|---|---|
| 0.3.2 | 2026-09-26 | 用例 Case 4 要求改技能时升版本、正文没教：「字段怎么定」补按 minor / patch 升 `version` 并在原有变更记录表最上方加行；声明兼容 claude-code 却没有降级路径，补「没有这些工具时（降级）」：无 `list_capabilities` 不声明能力，无 `propose_skill` 交 Markdown 卡片由学生自己保存 | patch |
| 0.3.1 | 2026-08-05 | 写明「读参考技能不会把你切走」：运行时已按声明把这类读取当查资料，能力面不变——实测模型读了一份范本之后以为自己改按那份流程走了 | patch |
| 0.3.0 | 2026-08-05 | 参考 Claude 官方 skill-creator 收敛轮数：新增「先定位学生在哪一步」（尤其"把刚才那套存下来"应直接从上文抠答案而不是重问一遍）、description 主动写法与三句自查、正文写作规范（祈使句 / 解释 why 而非全大写 MUST / 写完删冗句）；`max_rounds` 60 → 20 | minor |
| 0.2.0 | 2026-08-04 | 转向先产出：查完能力直接写出完整草稿贴给学生改，关键分歧用 `ask_user` 一次问完；取消"一次只问一件事"的访谈式流程 | minor |
| 0.1.0 | 2026-08-04 | 初始草稿 | minor |