为什么需要 Skills
Skill 解决的不是“模型不会写代码”，而是“同一类工作每次都要重新解释、重新纠错、重新找资料”。当一个工作流反复出现、容易漏步骤、需要固定资源或脚本时，就值得沉淀成 skill。
重复出现的工作流
例如每周报告、固定文件转换、CI 失败排查、设计实现检查。
有私有上下文的任务
例如内部 schema、团队规范、模板、常用脚本和验收标准。
一次性简单请求
如果模型本来就能稳定完成，普通 prompt 更轻。
一句话：Skill 是给 agent 的可复用操作手册和工具包，不是把 prompt 写得更长。
Skill 的最小可运行模型
最小 skill 只有一个文件夹和一个 `SKILL.md`。`name` 是身份，`description` 是触发入口，正文是触发后才会读取的操作说明。
---
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 再强也可能不会被正确触发。
先发现和复用高质量 Skills
不必默认从空白文件开始写。更稳的路径是先看官方 skill、一手仓库和维护良好的社区案例；但安装前必须完整审计，确认没有错误、隐私泄露风险或安全风险，再决定安装、改造或放弃。
候选来源
安装前完整审计
处理结果
官方和高质量仓库
优先看官方示例、活跃维护的 repo、star 较高且最近仍有更新的 skill 集合。Star 是线索，不是结论。
完整阅读和安全检查
安装前自己读完，或让 AI 辅助审计所有说明、脚本、依赖、网络访问和隐私风险。
低风险环境试跑
不要直接上真实项目。先用样例或临时目录试跑，观察是否触发准确、步骤完整、输出稳定。
基于成熟模式定制
保留好结构，替换业务规则、私有资源、验收标准和语言偏好，避免无意义重写。
能复用也要先审计。自己写或改 skill 的价值，不只是复用结构，更是把隐私、安全、触发边界和验收标准控制在自己能负责的范围内。
Skill 的构成：四类文件各司其职
无论是复用别人的 skill，还是让 AI 生成自己的 skill，都要看懂它的文件结构。把所有信息塞进一个 `SKILL.md` 会污染上下文；好的 skill 会把“每次都要看”和“特定分支才要看”的内容分层。
正文适合放什么
- 必须遵守的流程和安全边界。
- 选择路径的决策树。
- 短模板、短示例、关键 gotchas。
资源目录适合放什么
- 长文档、API 细节、schema、参考表。
- 重复写错的脚本和验证器。
- 最终输出要复用的模板和素材。
原理：Progressive Disclosure
Skill 的关键设计是渐进披露：不是一开始把所有资料塞进上下文，而是先暴露最小索引，任务匹配后再逐层加载。
Skill 和 Prompt、Tool、MCP、Subagent 的区别
这些概念经常被混在一起。最简单的判断：skill 是“如何完成一类任务”的可复用知识和流程，tool/MCP 是“能调用什么”，subagent 是“谁来做”。
现代写法：让 AI 生成 Skill 草稿
很多场景下，skill 不必从空白文件手写，可以先用 `skill-creator` 这类 creator skill 生成结构化草稿。注意：AI 生成只解决“起草成本”，不证明 skill 准确、可用或符合要求；人的工作重点是提供真实输入、审核逻辑、控制边界并验证效果。
你负责决策
- 任务边界：什么请求应该触发，什么不该触发。
- 真实素材：任务记录、输入样例、失败案例、已有脚本。
- 验收标准：成功输出长什么样，必须验证什么。
- 风险边界：哪些动作必须先问，哪些不能做。
AI 负责生成
- 把流程整理成 `SKILL.md` 的可执行步骤。
- 把长资料拆到 `references/`，把重复操作建议脚本化。
- 生成触发描述、不触发条件、停止条件和输出模板。
- 根据审核和验证结果重写，而不是一次定稿。
$skill-creator
请根据下面这类真实任务，先提炼 workflow，再生成一个可安装的 skill。
要求：
1. 先输出中文 workflow 框架让我审核。
2. 审核通过后再生成完整 skill 内容。
3. 如果团队认为更利于模型理解，可把给模型读取的核心说明转成英文。
4. 无论 skill 内部说明用什么语言，与用户交互和最终输出默认保持中文。
5. 标出触发条件、不触发条件、安全停止条件和验证方式。
6. 生成后先用 2-3 个真实 prompt 手工试跑；准备分享前再扩展到 10-20 个测试 prompt。AI 生成不是跳过设计，也不是质量保证；它只是把“写 Markdown 草稿”的体力活交给 AI，把“这个 workflow 是否真的成立、是否经过验证”的判断留给人。
从真实链路提炼，而不是凭空设计
自己撰写 skill 时，更可靠的素材来自已经跑通过的真实链路：工作过的线程、runbook、测试命令、评审规则、失败修复记录。等任务跑通后，再从真实过程里提炼 skill，而不是一开始就写一份抽象规则。
推荐提炼顺序
- 先让 AI 按你的指导完整完成一次真实任务。
- 让 AI 先提炼可审核的 workflow 框架，而不是直接写最终 skill。
- 你审核框架，补上遗漏边界、失败恢复和验收标准。
- 审核后再生成完整 skill 内容，必要时先保留中文。
- 如果团队认为有必要，再把给 AI 读取的核心说明转成英文；这不是官方强制要求。
语言策略
- 官方资料强调清晰、具体、可触发，没有把英文写成硬性标准。
- 给模型读的流程、触发条件、停止条件可以英文，也可以用团队更容易审核的语言。
- 面向用户的交互、输出格式、报告语言要单独明确，例如“默认中文输出”。
使用中迭代：变稳，但不要过拟合
Skill 很难一次做到很好。正确做法是多使用、记录偏差、提炼共性，再用真实 prompt 和执行 trace 验证改动；错误做法是每遇到一个孤立失败就加一条很窄的规则。
过拟合式修改
- 只因为一次失败，就写一条很窄的特判。
- 把某个文件名、某个临时路径、某个异常状态写死。
- 规则越加越多，但触发范围越来越混乱。
通用改进式修改
- 先比较 2-3 个真实样例，确认失败有共性；分享前扩展到 10-20 个 prompt。
- 把共性提炼成触发边界、决策树、验证步骤或脚本。
- 同时补充反例，说明哪些请求不该触发。
早期至少保留 2-3 个不同输入；准备复用或分享时扩展到 10-20 个 prompt。
区分触发错误、流程漏步、工具误用、验收不清。
把共性写成原则、决策树或脚本，不写狭窄特判。
明确哪些请求不应该触发，避免 skill 过宽。
比较有 skill 和没 skill 时输出稳定性是否真的提高。
第三方或脚本型 skill 要审查依赖、网络、凭据和写入边界。
避免过拟合的判断：如果一条规则只能解释一次失败，而且会让其他任务更难做，先不要写进 skill；先把它放进待观察记录。
常见 Skills 类型
最适合做 skill 的不是“某个知识点”，而是会反复出现、容易出错、带固定验收标准的工作流。
PDF / DOCX / PPTX / XLSX
适合封装工具选择、格式坑、渲染检查和模板复用。
CI / 安全 / 部署
适合封装日志读取顺序、审批边界、验证命令和停止条件。
搜索 / 引用 / 证据
适合封装来源优先级、过滤标准、引用格式和不确定性标注。
设计 / 截图 / 响应式
适合封装 UI 标准、浏览器验证、截图检查和常见布局风险。
Runbook / 评审 / 文档
适合封装团队偏好、输出格式、角色分工和历史教训。
日报 / PPT / 长文
适合封装选题、素材整理、风格统一、发布前检查。
选题原则：高频、易错、有固定资源、有验收标准，四个条件满足得越多，越值得做成 skill。
练习：用 AI 起草第一个最小 Skill
这个练习的目标不是背答案，而是学会把“功能要求、触发边界、输出格式、停止条件和 description”说清楚，再让 `$skill-creator` 起草。
题目要求
- 创建一个 `commit-message-helper` skill。
- 当用户要求“写、润色、选择 commit message”时触发。
- 输入来源必须是当前仓库的 staged git diff。
- 输出 3 个 Conventional Commit 候选。
- 每个 subject 不超过 72 个字符。
- 只有从路径或 diff 能明显看出 scope 时才写 scope。
边界和停止条件
- 如果没有 staged diff，必须说明无法生成，不要编造。
- 不要执行 `git commit`，只生成候选信息。
- 用户只是问 Conventional Commit 规范时，不一定要触发这个 skill。
- `description` 要准确、简洁、具体：说明任务对象、输入来源和触发场景。
---
name: commit-message-helper
description: Draft 3 concise Conventional Commit candidates
from staged git diffs. Use when the user asks to write,
polish, or choose a commit message for staged changes.
Do not use for general Conventional Commit explanations.
---
1. Inspect the staged diff with `git diff --staged`.
2. If no staged changes exist, stop and say no staged diff is available.
3. Identify the primary change type from the diff.
4. Output 3 candidate Conventional Commit messages.
5. Do not run `git commit`.
6. Keep each subject under 72 characters.
7. Mention scope only when it is obvious from changed paths.值得写吗？
怎么生成？
怎么验证？
资料来源和取舍
教程核心事实优先来自官方文档、Agent Skills 规范和一手仓库。社区文章只作为表达参考，不作为规范依据。