做一个自己的技能 / 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

---
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
<完整的 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