如何编写 Skills

1

Skill 基本介绍

先建立共同语言：Skill 解决什么问题，最小结构是什么，文件如何构成，加载原理是什么，它和 prompt、tool、MCP、subagent 的边界在哪里。

1.1

为什么需要 Skills

Skill 解决的是同一类工作每次都要重新解释、重新纠错、重新找资料的问题。当一个工作流反复出现、容易漏步骤、需要固定资源或脚本时，就值得沉淀成 skill。

判断标准：如果你已经第三次写同一段长 prompt，通常该考虑 skill。

适合写

重复出现的工作流

例如每周报告、固定文件转换、CI 失败排查、设计实现检查。

适合写

有私有上下文的任务

例如内部 schema、团队规范、模板、常用脚本和验收标准。

不必写

一次性简单请求

如果模型本来就能稳定完成，普通 prompt 更轻。

一句话：Skill 是给 agent 的可复用操作手册和工具包，用来减少重复解释、重复纠错和重复找资料。

1.2

Skill 的最小可运行模型 / 文件构成

先看最小可运行形态，再看文件如何分层。最小 skill 只需要一个文件夹和一个 `SKILL.md`；成熟 skill 会把每次都要读的核心说明和特定分支才要读的资源拆开。

先把最小文件写对，再决定是否增加资源目录。

SKILL.md最小示例

---
name: roll-dice
description: Roll dice using a random number generator.
  Use when asked to roll a die, roll dice, or generate
  a random dice roll.
---

To roll a die, generate a random number from 1 to the
requested number of sides.

读这个示例时看三件事

`name` 使用小写和连字符，短且可识别。
`description` 同时写“做什么”和“什么时候用”。
正文只写触发后才需要知道的执行方法。

如果 `description` 写得模糊，skill 再强也可能不会被正确触发。

文件构成：四类文件各司其职

无论是复用别人的 skill，还是让 AI 生成自己的 skill，都要看懂它的文件结构。把所有信息塞进一个 `SKILL.md` 会污染上下文；好的 skill 会把“每次都要看”和“特定分支才要看”的内容分层。

分层的目标是减少上下文占用，同时让 agent 知道每个资源在什么时候有用。

正文适合放什么

必须遵守的流程和安全边界。
选择路径的决策树。
短模板、短示例、关键 gotchas。

资源目录适合放什么

长文档、API 细节、schema、参考表。
重复写错的脚本和验证器。
最终输出要复用的模板和素材。

1.3

加载原理

Skill 的关键设计是渐进披露：先暴露最小索引，任务匹配后再逐层加载，避免一开始把所有资料塞进上下文。

OpenAI 文档说明 Codex 初始 skills 列表有上下文预算，skill 多时会优先缩短 description。

这个原则也适用于安装范围：每多装一个无关 skill，就多一份初始索引和触发候选。多 skill 仓库应只安装和真实工作流匹配的功能。

1.4

Skill 和 Prompt、Tool、MCP、Subagent 的区别

这些概念经常被混在一起。最简单的判断：skill 是“如何完成一类任务”的可复用知识和流程，tool/MCP 是“能调用什么”，subagent 是“谁来做”。

概念

主要用途

是否可复用

是否携带文件

典型例子

Prompt

一次性指令

低，复制粘贴为主

否

“帮我写一个提交信息”

AGENTS.md

项目/全局工作契约

高，但偏长期规则

通常否

代码风格、权限、沟通规则

Skill

任务能力包

高，可触发、可迭代

是

PDF、CI 修复、安全威胁建模

Tool / MCP

实际外部能力接口

高，偏操作能力

不负责教学流程

GitHub、Playwright、数据库

Subagent

独立上下文执行者

按任务临时使用

由任务决定

并行调研、独立验证、对抗审查

Skill 教 agent 如何可靠地使用工具，工具负责提供实际能力。

1.5

常见 Skills 类型

最适合做 skill 的对象是会反复出现、容易出错、带固定验收标准的工作流。

文件类

PDF / DOCX / PPTX / XLSX

适合封装工具选择、格式坑、渲染检查和模板复用。

工程类

CI / 安全 / 部署

适合封装日志读取顺序、审批边界、验证命令和停止条件。

研究类

搜索 / 引用 / 证据

适合封装来源优先级、过滤标准、引用格式和不确定性标注。

前端类

设计 / 截图 / 响应式

适合封装 UI 标准、浏览器验证、截图检查和常见布局风险。

团队类

Runbook / 评审 / 文档

适合封装团队偏好、输出格式、角色分工和历史教训。

内容类

日报 / PPT / 长文

适合封装选题、素材整理、风格统一、发布前检查。

选题原则：高频、易错、有固定资源、有验收标准，四个条件满足得越多，越值得做成 skill。

2

如何使用 Skill

再进入使用流程：先发现可复用来源，再按需选择、审计和定制，最后看一个真实的 COMPASS 安装示例。

2.1

发现来源 / 按需安装

如果要使用别人提供的 skill，先从 GitHub、Skills.sh 和 SkillsMP 这三个来源找到候选，再进入范围选择、审计和本地定制。发现和安装是一条连续决策链。

来源 1

GitHub

适合找官方仓库、一手仓库和社区集合。重点看目录结构、最近更新、issue、README、安装方式和每个 skill 的 `description`，star 只作为发现线索。

来源 2

Skills.sh

适合按名称、用途和仓库来源发现可安装 skills。安装前先列出仓库包含哪些 skills，再决定是否只安装其中一部分。

来源 3

SkillsMP

适合作为第三方 skill 目录使用。目录只解决发现问题，真正进入本地之前仍要完整审计目标 skill 的说明、脚本、依赖和权限边界。

这些来源只负责发现候选，下一步是按需安装：选定具体 skill，审计相关文件；工作流边界不一致时，先改成本地版本。

按需安装、审计与本地定制

使用别人提供的 skill，第一步是选清范围。多 skill 仓库先确认哪些功能匹配自己的工作流，再完整审计相关文件；边界不合适时，先改成本地版本再安装。

如何判断一个已有 skill 或 skill 集合值不值得安装？ Star 只作线索

候选来源

1GitHub：找官方仓库、一手仓库和社区集合。

2Skills.sh：按名称、用途和仓库来源发现可安装 skills。

3SkillsMP：作为第三方目录发现更多候选。

选定范围再审计

A按真实任务、description 和目录只选需要的 skills；多 skill 仓库不要把 `*` 当默认选项。

B完整阅读目标 skill 的 `SKILL.md`、相关 references、scripts、assets 和依赖说明。

C检查硬编码密钥、私有路径、上传日志、外部回传，以及删除文件、改全局配置、联网、读凭据等风险。

D确认触发条件、停止条件、示例和验证方式没有明显错误；边界不合适就先改再装。

处理结果

装审计通过，任务匹配，只安装需要的 skill，先在低风险环境试用。

改结构好但边界不同，先删除风险内容、收窄触发范围或替换本地规则，再安装自己的版本。

弃功能不匹配、触发模糊、脚本不可审、隐私或安全边界不清。

这张图把“找高质量 skill”拆成来源、按需筛选、安装前审计和处理结果：没有选清、读完和审完，不要安装。

先找

三个发现来源

从 GitHub、Skills.sh 和 SkillsMP 找候选；优先看官方仓库、一手仓库和最近仍维护的 skill 集合。Star 只作线索。

先审

先选范围再审计

多 skill 仓库先看 description 和目录，只保留当前工作需要的功能；安装前审计相关说明、脚本、依赖、网络访问和隐私风险。

再试

低风险环境试跑

不要直接上真实项目。先用样例或临时目录试跑，观察是否触发准确、步骤完整、输出稳定。

再改

基于成熟模式定制

保留好结构，替换业务规则、私有资源、验收标准和语言偏好，避免无意义重写；没有必要原封不动安装。

能复用也要先选清和审计。自己写或改 skill 的价值，不只是复用结构，更是把上下文负担、隐私、安全、触发边界和验收标准控制在自己能负责的范围内。

2.2

司南 COMPASS Skill 系统

COMPASS 提供四类本地 skills：用户画像、任务图谱、AI 对话续接和需求对齐。它把长任务、跨 session 协作和多 agent 工作从聊天记录里移到可查、可更新的本地结构中。

这四个 skills 互相配合：`$user-profile-keeper` 让 agent 知道“你是谁、怎么协作”，`$task-forest` 让 agent 知道“任务在哪里、做到哪里、为什么做”，`$session-handoff-prompt` 把当前任务状态整理成可复制给新 AI 对话的续接提示词，`$task-clarifier` 让 agent 在行动前确认“用户的需求到底是什么”。它们都围绕本地文件工作，不上传用户数据，也不读取 credential、浏览器 cookie 或远程会话。

GitHub 仓库： dongshuyan/compass-skills

一键安装Codex + Claude Code

npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code

这条命令安装 COMPASS 的四个核心 skills。安装其他多 skill 仓库时，先查看可选 skills，再用 `--skill ` 只安装需要的功能；边界不同时，可以先改成本地版本再安装。

知人

$user-profile-keeper

在本地保存可审计、可纠错、可撤回的协作画像。画像只记录用户确认或低敏的协作信号；secret、token、密码、私钥和验证码不进入画像。

知事

$task-forest

把当前 session 分解成任务森林 / DAG，并记录每个任务的目标、进度、偏差、依赖、待办和决策。确认 proposal 后生成树视图、DAG 视图、任务详情卡和推荐队列。

知续

$session-handoff-prompt

把当前 AI 对话里需要延续的目标、进展、约束、已验证事实、风险和下一步压缩成可直接复制给新 AI 对话的提示词。它面向续接，不回放完整 transcript，也不修改任务图。

知向

$task-clarifier

当需求模糊、成本高或有安全风险时，把想法整理成可执行需求：目标、范围、证据、验收标准和风险边界都写清楚。它先识别必须由用户决定的关键分叉，可查事实由 agent 自己从材料中补足。

用户能说清自己的目标和约束。

agent 知道任务位置、进度和依赖。

新 AI 对话能接上目标、约束和下一步。

用户能确认 agent 的理解没有偏离。

司南 COMPASS 技能生态 DAG — 四个 skills 的关系：先理解人，再维护事，再交接续接信息，最后在行动前对齐方向。

task-forest 导出的任务关系树和 session 更新流程 — `$task-forest` 导出的任务关系树和 session 更新流程。

task-forest live DAG 关系视图 — DAG 关系视图：展示任务、依赖和当前推进位置。

task-forest 任务详情、目的、要求、证据和调度建议 — 任务详情、目的、要求、证据和调度建议。

用户画像与需求对齐的协作方式。

3

如何自己开发 Skill

最后进入开发流程：先从真实链路提炼，再用 AI 起草，并用质量门槛、路由规则和迭代方法把 skill 变稳定。

3.1

真实链路 / AI 生成

可靠的 skill 先来自真实跑通过的链路，再用 AI 起草可审核的结构。素材不是空想流程，而是工作过的线程、runbook、测试命令、评审规则和失败修复记录。

把个人经验校准成可教学规则 经验可用，但必须标注证据级别

AI 生成草稿 官方文档支持用 `$skill-creator` 起步；但草稿不等于可用 skill，后面必须审核和验证。

复用已有 skill 官方和一手仓库可作为高置信参考；GitHub star 只能作为发现线索，不能当作质量证明。

真实链路提炼 “把工作过的线程、runbook、测试命令转成 skill”有官方支持；中文 workflow 审核是适合中文团队的实践。

迭代但不过拟合 官方 eval 建议用真实 prompt、trace 和检查项防回归；单个失败不要直接写成狭窄特判。

教程后续会把“经验”写成经过来源校准的推荐流程：能被官方或一手实践支持的强化，缺少标准依据的加限定。

从一次真实执行提炼 skill：不要跳过中间审核层 真实轨迹 → 可审核框架 → Skill 草稿

1. 真实跑通 让 AI 在真实文件、真实环境、真实目标下完整完成一次任务。

2. 抽取轨迹 记录输入假设、工具顺序、失败恢复、验证命令和输出格式。

3. 可审核框架 先让 AI 提炼 workflow 框架。中文团队可先用中文，方便检查逻辑是否完整。

4. 生成 skill 审核通过后再生成 `description`、正文、references 和 scripts。

5. 规范化核心 核心规则要短、明确、可触发。英文化是可选实践。

这张图把“从经验到 skill”的中间层画出来：先审核 workflow，再进入完整 skill 生成；中文框架和英文化只是可选语言策略。

真实任务比抽象“最佳实践”更能暴露 skill 需要处理的边界。

压缩复杂度

真实链路进入 skill 前要先压缩。完整执行里可能有很多步骤，正文只保留会改变执行路径的判断。
长 pipeline 会把每个判断点都变成新的失败点；一次误判进入错误分支，后面的步骤会继续放大偏差。
只有触发边界、权限风险、证据来源、工具选择、输出格式和停止条件这类关键分支，才值得写成路由。
能靠上下文自然判断的细节，放进示例、reference 或脚本；不要把它们堆成连续路由。

语言策略

官方资料强调清晰、具体、可触发，没有把英文写成硬性标准。
给模型读的流程、触发条件、停止条件可以英文，也可以用团队更容易审核的语言。
面向用户的交互、输出格式、报告语言要单独明确，例如“默认中文输出”。

AI 生成：让 AI 起草可审核的 Skill

很多场景下，skill 不必从空白文件手写，可以先用 `skill-creator` 这类 creator skill 生成结构化草稿。注意：AI 生成只解决“起草成本”，不证明 skill 准确、可用或符合要求；人的工作重点是提供真实输入、审核逻辑、控制边界并验证效果。

用 `skill-creator` 时，人和 AI 分别负责什么？ 可审核地生成

你负责决策

任务边界：什么请求应该触发，什么不该触发。
真实素材：任务记录、输入样例、失败案例、已有脚本。
验收标准：成功输出长什么样，必须验证什么。
风险边界：哪些动作必须先问，哪些不能做。

你给的是“真实工作流和判断标准”。

AI 负责生成

把流程整理成 `SKILL.md` 的可执行步骤。
把长资料拆到 `references/`，把重复操作建议脚本化。
生成触发描述、不触发条件、停止条件和输出模板。
根据审核和验证结果持续重写，保留可审查的迭代过程。

AI 产出的是“可审查的 skill 草稿”。

这张图强调职责分工：人给真实边界和验收，AI 做结构化生成，最后仍由人审核和测试逻辑是否成立。

1. 给目标说明这个 skill 要解决哪类重复任务，什么时候应该触发，什么时候不应该触发。

2. 给素材提供真实任务记录、示例输入、输出样例、失败案例、已有脚本或模板。

3. 让 AI 生成用 `$skill-creator` 或同类 creator skill 生成目录、`SKILL.md`、references、scripts 建议。

4. 人来审核和验证重点看触发边界、执行顺序、安全停止条件、是否过度宽泛，并用真实 prompt 跑一次。

推荐请求方式给 skill-creator

$skill-creator
请根据下面这类真实任务，先提炼 workflow，再生成一个可安装的 skill。
要求：
1. 先输出中文 workflow 框架让我审核。
2. 审核通过后再生成完整 skill 内容。
3. 如果团队认为更利于模型理解，可把给模型读取的核心说明转成英文。
4. 无论 skill 内部说明用什么语言，与用户交互和最终输出默认保持中文。
5. 标出触发条件、不触发条件、安全停止条件和验证方式。
6. 生成后先用 2-3 个真实 prompt 手工试跑；准备分享前再扩展到 10-20 个测试 prompt。

AI 生成承担 Markdown 草稿整理；workflow 成立性、验证结果和风险边界由人审核。

3.2

质量门槛 / 路由稳定

稳定 skill 同时依赖两件事：能证明它值得使用的质量门槛，以及少、强、可验证的路由规则。它应该来自真实反复任务，触发边界准确，核心路径连续，并用正例、反例、工具验证和 with/without 对照证明稳定性。

按优先级检查

先看 P0：选题、真实链路、触发边界和路由判断。P0 站不住，后面的结构优化和测试设计都无法稳定发挥作用。

排序	分类	条件	为什么
P0 · 选题与素材先确认 skill 是否值得做，以及素材是否来自真实链路。
01	P0选题与素材	任务本身高频、易错、有固定资源、有验收标准	skill 的价值来自稳定复用。低频、纯主观、没有验收标准的任务，用普通 prompt 往往更合适。
02	P0选题与素材	从真实跑通过的链路提炼	真实 trace 能暴露工具顺序、失败恢复、验证命令和停止条件；凭空设计容易写成抽象口号。
P0 · 触发边界让 skill 准确触发，并用反例约束误触发。
03	P0触发边界	`description` 同时写清“做什么”和“什么时候用”	`description` 是触发入口，正文只有触发后才会读。触发不准时，正文写得再好也用不上。
04	P0触发边界	有明确不触发条件和反例	反例能防止 skill 过宽，避免关键词相似但任务目标不同的请求误触发。
P0 · 路由与判断保留少数强分支，把判断接到用户、工具或证据。
05	P0路由与判断	路由少，只保留关键分支	每个模型判断都会增加误判概率。只有触发边界、权限风险、证据来源、工具选择、输出格式、停止条件这类分支值得进入热路径。
06	P0路由与判断	路由强，可被验证	弱分支如“看起来风险不高”“上下文似乎足够”不稳；强分支应绑定具体动作、文件、schema、测试、diff、用户确认或外部证据。
07	P0路由与判断	用户拥有的判断交给用户	偏好、预算、成功标准、风险容忍度没有公共真值，模型猜测会放大后续偏差。
08	P0路由与判断	机器能判的交给工具	YAML、schema、lint、测试、diff、文件存在性属于可验证事实，工具检查比主观判断稳定。
P1 · 结构与资源核心路径连续可读，资源按职责边界和读取条件拆分。
09	P1结构与资源	`SKILL.md` 保持短、核心、可执行	每次触发都会读正文；正文越臃肿，越容易稀释关键规则并占用上下文。
10	P1结构与资源	用 progressive disclosure 组织资源	核心流程放 `SKILL.md`；API、schema、长规范放 `references/`；确定性重复动作放 `scripts/`；模板素材放 `assets/`。
11	P1结构与资源	抽象边界清楚，避免微型拆分	核心执行路径要连续可读；只有内容有独立职责边界、独立读取条件、稳定复用价值、机器验证价值，或会显著拖长主流程时，才拆到 `references/`、`scripts/`、`evals/` 或 companion skill。
12	P1结构与资源	重复且易错的操作脚本化	脚本比每次重写代码更稳定，也能被测试和复用。
P1 · 风险与验收明确停止条件、输出契约和基础结构验证。
13	P1风险与验收	有安全停止条件	删除、发布、push、凭据、全局配置、外部副作用等必须显式确认，避免 skill 自动越界。
14	P1风险与验收	有稳定输出格式和验收标准	输出模板、字段、长度、文件路径、测试命令让结果可检查，减少“看起来完成了”的假完成。
15	P1风险与验收	通过基础结构验证	至少跑 `quick_validate.py`，确保 `SKILL.md`、frontmatter、命名、description 基本合法。
P2 · 测试与迭代用真实 prompt、对照和 holdout 防止纸面改进。
16	P2测试与迭代	用真实 prompt 和负例验证触发	好的触发测试要包含 should-trigger 和 should-not-trigger，尤其是近邻负例。
17	P2测试与迭代	做 with/without 或旧版/新版对照	只有对照后才能判断 skill 是否真的提升稳定性；单纯增加说明层不等于质量提升。
18	P2测试与迭代	迭代时提炼共性，避免单例特判	一次失败只能作为线索；进入 skill 的规则应覆盖一类稳定问题，并有反例或 holdout 检查。

稳定 skill 依赖少数关键规则：触发准确、核心路径连续、结果可验证、反例能约束边界。下一节继续展开路由设计：把弱判断从热路径移出，把必要判断接到用户、脚本、测试、schema、diff 或外部证据上。形式底线：`name` 用小写连字符，短且可识别；`description` 准确、具体、不过长；`SKILL.md` 有 YAML frontmatter 和正文；资源目录只放有独立职责边界、读取条件、执行用途或产物用途的内容；`agents/openai.yaml` 承载 UI 元数据、默认 prompt 和工具依赖；skill 的触发设计放在 `description` 和 `SKILL.md`。

路由稳定：少、强、可验证

路由就是让 agent 选择分支。分支本身是正常工程结构，真正的风险来自弱验证和延迟反馈。写 skill 时要减少弱验证分支，把必要分支接到用户确认、脚本、测试、schema、diff 或外部证据。

根本原因

路由的主要风险来自“弱验证 + 延迟反馈”；直接执行更稳，是因为路径已定、动作更局部、结果更容易被外部证据验证。

设计目标

保留能带来真实稳定性的分支，删掉只增加判断负担的分支。能用低风险执行产生证据时，先执行，再让证据决定下一步。

方法	差的做法	好的做法	为什么准确率更高
1直接减少不必要分支	`if 当前上下文足够构建画像: 跳过问卷 else: 推荐问卷`	删除这条判断。首次建档固定推荐问卷；用户拒绝就继续当前任务，候选画像进入 proposal。	直接移除“上下文是否足够”这个弱验证分支。牺牲少量灵活性，换来更稳定的主流程。
2弱验证路由改成强验证路由	`if 这个操作看起来风险不高: 直接执行`	`if 操作包含 delete / publish / push / credentials / global config: 显式确认`	“看起来风险不高”依赖感觉；具体动作词和作用域更容易被文件、命令和用户确认验证。
3用执行替换路由	`if 可能影响很多文件: 跑全量测试 else: 跑局部测试`	先执行 `git diff --name-only`、`rg` 引用、检查测试目录，再决定测试范围。	先产生证据，再选择路径。判断对象从“影响大不大”变成“实际改了哪些文件、哪些引用存在”。
4缩短反馈距离	产品推荐里先搜索、筛选、排序，最后才让用户看结果。	先确认用途、预算、购买地区和成功标准，再开始外部研究。	方向错误会更早暴露。反馈越近，后续执行建立在错误目标上的概率越低。
5用户拥有的判断交给用户	`if 我判断用户更重视耐用: 推荐 A`	问用户优先级：耐用、轻便、颜值、价格、保修；给一个推荐答案，等待确认。	用户偏好没有公共真值。让用户确认，比模型根据上下文猜测更可靠。
6机器能判的交给机器	`if 我觉得 YAML 没问题: 结束`	运行 YAML parser、schema check、`git diff --check`、lint 或测试脚本。	格式、schema、语法、测试结果属于可验证事实。工具检查比模型主观判断稳定。
7必要分支收窄，但避免过拟合	`if 用户问行李箱: 永远先问 20 寸还是 24 寸`	`if 购买推荐缺少用途、预算或购买地区: 先问缺失的核心约束`	好分支有通用触发条件和明确反例。它解决一类问题，不把一次失败固化成狭窄特判。

检查一条新分支是否值得写进 skill：它能否被快速验证，是否有明确反例，是否能被用户、脚本或外部证据纠偏，是否解决一类稳定问题。

3.3

使用中迭代：变稳，但不要过拟合

Skill 很难一次做到很好。正确做法是多使用、记录偏差、提炼共性，再用真实 prompt 和执行 trace 验证改动；错误做法是每遇到一个孤立失败就加一条很窄的规则。

迭代 skill 时，什么是过拟合？什么是通用改进？ 先看模式，再改规则

过拟合式修改

只因为一次失败，就写一条很窄的特判。
把某个文件名、某个临时路径、某个异常状态写死。
规则越加越多，但触发范围越来越混乱。

结果：这个案例好了，其他任务更容易坏

通用改进式修改

先比较 2-3 个真实样例，确认失败有共性；分享前扩展到 10-20 个 prompt。
把共性提炼成触发边界、决策树、验证步骤或脚本。
同时补充反例，说明哪些请求不该触发。

结果：一类任务整体更稳定

这张图把“迭代优化”和“过拟合修补”区分开：只有能改善一类任务，并经真实 prompt 或 trace 验证的规则，才适合写进 skill。

迭代时要改对位置：触发问题改 description，稳定操作脚本化，长资料放 reference。

✓多跑真实任务
早期至少保留 2-3 个不同输入；准备复用或分享时扩展到 10-20 个 prompt。

✓记录失败类型
区分触发错误、流程漏步、工具误用、验收不清。

✓优先通用规则
把共性写成原则、决策树或脚本，不写狭窄特判。

✓保留反例
明确哪些请求不应该触发，避免 skill 过宽。

✓with/without 对照
比较有 skill 和没 skill 时输出稳定性是否真的提高。

✓审查副作用
第三方或脚本型 skill 要审查依赖、网络、凭据和写入边界。

避免过拟合的判断：如果一条规则只能解释一次失败，而且会让其他任务更难做，先不要写进 skill；先把它放进待观察记录。

3.4

练习：用 AI 起草第一个最小 Skill

这个练习用 commit message 起草做样例，因为它小、高频、容易验证，也很容易写偏。目标是练习把触发范围、证据来源、副作用边界、输出格式和触发测试写清楚。

练习任务

创建一个 `commit-message-helper` skill。
只在用户要求为 staged changes 写、润色或选择 commit message 时触发。
唯一输入来源是当前仓库的 staged git diff。
输出 3 个 Conventional Commit 候选。
每个 subject 不超过 72 个字符。
只有路径或 diff 内容能明显支持时才写 scope。

提交前先确认

`description` 写明任务、输入来源和触发场景。
没有 staged diff 时明确停止。
不执行提交、推送、暂存或文件修改。
输出数量、格式、长度规则和可选 scope 规则都可检查。
包含应触发、不应触发、应停止三类测试提示。

先自己写一版，再看参考材料。参考材料默认隐藏，避免提前看到后影响你对触发边界、停止条件和输出契约的判断。

常见错误类型

触发范围过宽：只要用户问 Git 或 Conventional Commit 就触发。
证据来源不明确：没有 staged diff 时从聊天上下文猜改动。
副作用越界：自动执行 `git add`、`git commit` 或 `git push`。
固定规则过拟合：写死路径到 type 的对应关系。
scope 规则不可检查：无论 diff 是否支持都强行添加 scope。
缺少触发测试：没有应触发、不应触发或应停止样例。

错误示例片段不要照抄

---
name: commit-helper
description: 帮用户处理所有 git commit 相关问题。
---

如果用户需要提交，就根据上下文生成 commit message。
必要时运行 git add . 和 git commit。

commit-message-helper/SKILL.md参考答案

---
name: commit-message-helper
description: 根据当前仓库的 staged git diff 起草 3 个 Conventional Commit 候选。
  当用户要求为已暂存改动写、润色或选择 commit message 时使用。
  不用于一般 Git 问题或 Conventional Commit 规范解释。
---

1. 运行 `git diff --staged --stat` 和 `git diff --staged` 查看已暂存改动。
2. 如果没有 staged diff，停止并说明没有可用的 staged diff，不要编造。
3. 只根据 staged diff 判断主要变更类型和可选 scope。
4. 输出且只输出 3 个候选，格式为 `type(optional-scope): subject`。
5. 每个 subject 不超过 72 个字符，不以句号结尾。
6. 只有从路径或 diff 能明显看出 scope 时才写 scope。
7. 不要执行 `git add`、`git commit`、`git push`，不要修改文件。

触发测试：
- 应触发：用户说“帮我给 staged changes 写 3 个 commit message”。
- 不应触发：用户问“Conventional Commit 有哪些 type？”。
- 应停止：`git diff --staged` 为空。

错误示例的问题

description 过宽，会误触发普通 Git 问题。
没有 staged diff 时仍允许从上下文猜测。
会执行 add 和 commit，产生外部副作用。
没有输出契约、停止条件和触发测试。

参考答案满足的标准

触发范围窄：只处理 staged changes 的 commit message 起草。
证据绑定到 `git diff --staged`，避免编造改动。
把 staged diff 为空写成硬停止条件。
明确禁止 `git add`、`git commit`、`git push` 和文件修改。
输出契约可检查：3 个候选、格式、长度和可选 scope 都明确。
包含应触发、不应触发、应停止三类测试。

如何检查你的草稿？ 用触发和停止样例检查

触发边界

1description 写清任务、输入来源和触发场景。

2排除一般 Git 解释和 Conventional Commit 教学。

3包含近邻负例，能防止误触发。

输入和安全

1只把 staged diff 当作证据。

2staged diff 为空时停止，不猜测。

3不执行 `git add`、`git commit`、`git push`，不改文件。

输出和验证

1固定输出 3 个候选。

2长度和 scope 规则可检查。

3有应触发、不应触发、应停止三类测试。

按这张清单检查草稿：触发范围、证据来源、副作用、输出格式和停止条件都必须明确。

S

资料来源和取舍

教程核心事实优先来自官方文档、Agent Skills 规范和一手仓库。社区文章只作为表达参考，不作为规范依据。

OpenAI Developers: Agent Skills - Codex OpenAI Developers: Save workflows as skills OpenAI Developers: Testing Agent Skills Systematically with Evals Agent Skills Specification Agent Skills Best Practices Optimizing Skill Descriptions Evaluating Skills Using Scripts in Skills Anthropic Engineering: Agent Skills Claude Docs: Agent Skills Overview Claude Docs: Skill authoring best practices openai/skills anthropics/skills Skills.sh SkillsMP