anthropics-skills | 09 - 从模板开始写第一个 Skill 从模板开始写第一个 Skill系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第九篇。前八篇已经讲完了 Skill 的基础概念、触发机制、渐进式加载、资源组织、脚本协作和参考资料设计。现在我们回到动手实践从一个空目录开始写出第一个可用的 Skill。1. 为什么现在才开始写第一个 Skill如果你从第一篇一路读到这里可能会有一个疑问为什么不一开始就直接写 Skill原因很简单Skill 看起来只是一个SKILL.md文件但真正决定它能不能稳定工作的不只是文件内容。你需要先理解它解决的是什么问题。它什么时候应该触发。它和普通提示词有什么区别。它的正文应该放什么。什么内容应该拆到references/。什么工作应该交给scripts/。如何避免上下文成本失控。现在再动手就不是“写一段提示词”而是在设计一个小型工作流。这也是本文的目标用一个足够小、足够稳定的任务把前面讲过的内容串起来。2. 第一个 Skill 应该选什么任务第一个 Skill 不应该太大。很多人第一次写 Skill 时会想做一个“全能助手”能写文档。能改代码。能做评审。能生成测试。能发版总结。能处理各种异常。这很容易失控。第一个 Skill 更适合选择小任务。一个好任务通常有几个特点判断项说明高频你经常会做这个任务稳定流程和输出格式比较固定边界清楚知道什么时候该用什么时候不该用可检查输出好坏可以被判断低风险不会直接修改生产数据或执行危险操作所以本文选择的任务是生成中文 Git 提交说明。它很适合做第一个 Skill。原因是使用频率高。输出格式稳定。输入可以来自git diff、git status或用户描述。好坏容易判断。不需要复杂脚本也能先跑起来。后续可以自然扩展测试 prompt 和 description 优化。3. 先定义任务不要先写文件写 Skill 前先回答几个问题。这一步很像写函数前先定义函数职责。3.1 这个 Skill 要做什么目标根据用户提供的代码变更、git diff、git status、提交前说明或变更摘要生成中文提交说明。输出需要包含一个简洁的变更主题。一个有序列表形式的变更内容。可选的验证情况。这个目标足够具体。它不是“帮我处理 Git”也不是“帮我写所有项目文档”而是聚焦在提交说明。3.2 什么时候应该使用典型触发表达包括“帮我写提交说明”。“总结这次改动”。“根据 diff 生成 commit message”。“生成中文变更主题和变更内容”。“我准备提交帮我整理一下改动点”。“根据这些文件变更写一段提交内容”。这些表达都指向同一个任务意图把变更整理成可提交、可沟通的说明。3.3 什么时候不应该使用边界也要写清楚。不适用场景包括用户要做代码审查。用户要生成多版本发布说明。用户要设计 Git 分支策略。用户要解决 merge conflict。用户要重写提交历史。用户要执行真实提交命令。为什么要写不适用场景因为这些任务都和 Git 有关但不是“生成中文提交说明”。如果边界不清Skill 可能误触发。3.4 输入是什么输入可以有几种用户直接描述改动。用户贴出git diff。用户贴出git status。Agent 读取本地变更后总结。用户提供若干文件路径或变更片段。但第一版不用覆盖所有复杂情况。我们先支持最常见的三类变更描述。diff 摘要。文件变更列表。3.5 输出是什么输出格式要稳定。本文采用这个格式变更主题新增中文提交说明生成 Skill 变更内容 1. 新增用于生成中文 Git 提交说明的 Skill。 2. 规范输出格式为变更主题、变更内容和验证情况。 3. 补充触发场景、输入要求和质量标准。 验证情况未运行测试仅根据提供的变更内容生成说明。这个格式和本系列前面几篇的结尾风格一致也符合“中文主题 有序变更列表”的用户习惯。4. 从空目录开始一个最小 Skill 只需要一个目录和一个SKILL.md。目录可以叫chinese-git-change-summary/ └── SKILL.md为什么不用更宽泛的名字比如git-helper因为第一个 Skill 要小。git-helper听起来会覆盖提交、分支、冲突、rebase、tag、release 等一堆任务。这样的名字会把边界拉得太大。chinese-git-change-summary更聚焦Chinese输出语言是中文。Git任务来源是 Git 变更。Change Summary目标是总结变更。名字本身就在表达边界。5. 从模板开始本仓库的template/SKILL.md是最小模板--- name: template-skill description: Replace with description of the skill and when Claude should use it. --- # Insert instructions below这个模板只有两部分YAML frontmatter。Markdown 正文。frontmatter 中最关键的是nameSkill 名称。description触发描述。正文中写任务流程、输出格式、质量标准、示例和边界说明。第一版不需要scripts/、references/、assets/。先让一个最小 Skill 跑起来比一开始设计复杂目录更重要。6. 先写namename应该稳定、可读、可维护。推荐name:chinese-git-change-summary这个名字满足几个要求使用小写英文。用连字符分隔。表达任务对象。不试图覆盖过大范围。不推荐name:git-helper太宽。也不推荐name:commit太短语义不清。更不推荐name:my-skill这个名字对 Agent 和维护者都没有信息量。7. 再写descriptiondescription决定 Skill 是否有机会被加载。第一个版本可以先这样写description:Generate Chinese Git change summaries from code changes,git diff,git status,or user-described modifications. Use this skill when the user asks to write a Chinese commit message,summarize local changes,generate a change subject,or produce an ordered list of change items for a commit.这段 description 包含四类信息能力Generate Chinese Git change summaries。输入code changes、git diff、git status、user-described modifications。触发场景write a Chinese commit message、summarize local changes。输出change subject、ordered list of change items。这比下面这种写法更好description:Helps with Git.因为“Helps with Git”太宽泛既容易误触发也不能告诉 Agent 具体能力是什么。也比下面这种更好description:Generate commit messages.它虽然简洁但缺少语言、输入来源和输出形态。第十篇会专门讲如何进一步优化 description。第九篇先写一个可用版本。8. 正文应该包含哪些部分第一版SKILL.md不需要很复杂。建议包含Scope。Inputs。Workflow。Output Format。Quality Bar。Examples。Boundaries。这些部分覆盖了一个 Skill 的基本工作流。8.1 ScopeScope 说明这个 Skill 负责什么。例如## Scope Use this skill to turn Git-related code changes into a concise Chinese commit summary.Scope 不需要写太长。它是正文层面的边界确认。8.2 InputsInputs 说明 Agent 可以从哪里获取信息。例如## Inputs The input may include: 1. User-described changes. 2. git diff output. 3. git status output. 4. A list of changed files. 5. Notes about verification commands.输入写清楚后Agent 更容易知道缺少什么。如果用户只说“帮我写提交说明”但没有提供任何变更信息Agent 可以先读取本地变更或者请求用户补充。8.3 WorkflowWorkflow 是核心。它应该描述执行步骤而不是堆规则。例如## Workflow 1. Identify the changed areas from the provided diff, status, file list, or user description. 2. Group related changes together instead of listing every file mechanically. 3. Write one concise Chinese subject that starts with a verb. 4. Write an ordered list of concrete change items. 5. Mention verification status when available.这段流程里有几个关键点先识别变更区域。再合并相关变更。再写主题。再写列表。最后说明验证。这比“请写得专业一点”更可执行。8.4 Output Format输出格式越稳定用户越容易直接使用。例如## Output Format Use this format: 变更主题[一句简洁中文主题] 变更内容 1. [变更项 1] 2. [变更项 2] 3. [变更项 3] 验证情况[测试、构建、检查或未验证说明]注意这里要求有序列表。这和用户的偏好一致也方便提交前快速检查。8.5 Quality BarQuality Bar 说明什么是好输出。例如## Quality Bar - Keep the subject concise and action-oriented. - Avoid vague items such as optimized code unless the concrete behavior is clear. - Merge trivial file-level edits into meaningful change groups. - Do not invent tests or verification commands that were not run or mentioned. - Use Chinese for the final output.这几条很实用。尤其是“不要编造测试结果”。提交说明里最常见的问题之一就是把没有运行过的测试写成“已通过”。8.6 Examples示例能让输出更稳定。但第一版不要放太多示例。2 到 3 个就够了。示例应该覆盖不同输入用户描述。文件列表。diff 摘要。例如## Examples Input: Added validation for the login form and displayed inline error messages. Output: 变更主题完善登录表单校验 变更内容 1. 新增登录表单字段校验逻辑。 2. 补充表单内联错误提示提升用户填写反馈。 验证情况未提供验证信息。8.7 BoundariesBoundaries 说明不该做什么。例如## Boundaries - Do not perform code review unless the user explicitly asks for review. - Do not execute git commit unless the user explicitly asks and confirms. - Do not claim tests passed unless test output is provided or tests were actually run. - Do not include unrelated speculation about files that are not part of the change.边界不是为了限制能力而是为了让输出更可信。9. 第一版完整SKILL.md把上面的内容合在一起就得到一个可用的第一版。--- name: chinese-git-change-summary description: Generate Chinese Git change summaries from code changes, git diff, git status, or user-described modifications. Use this skill when the user asks to write a Chinese commit message, summarize local changes, generate a change subject, or produce an ordered list of change items for a commit. --- # Chinese Git Change Summary ## Scope Use this skill to turn Git-related code changes into a concise Chinese commit summary. ## Inputs The input may include: 1. User-described changes. 2. git diff output. 3. git status output. 4. A list of changed files. 5. Notes about verification commands. If no change information is available, inspect local changes when tool access is available. If local changes cannot be inspected, ask the user for the diff, changed files, or a short description. ## Workflow 1. Identify the changed areas from the provided diff, status, file list, or user description. 2. Group related changes together instead of listing every file mechanically. 3. Write one concise Chinese subject that starts with a verb. 4. Write an ordered list of concrete change items. 5. Mention verification status when available. ## Output Format Use this format: 变更主题[一句简洁中文主题] 变更内容 1. [变更项 1] 2. [变更项 2] 3. [变更项 3] 验证情况[测试、构建、检查或未验证说明] ## Quality Bar - Keep the subject concise and action-oriented. - Avoid vague items such as 优化代码 unless the concrete behavior is clear. - Merge trivial file-level edits into meaningful change groups. - Do not invent tests or verification commands that were not run or mentioned. - Use Chinese for the final output. ## Examples Input: Added validation for the login form and displayed inline error messages. Output: 变更主题完善登录表单校验 变更内容 1. 新增登录表单字段校验逻辑。 2. 补充表单内联错误提示提升用户填写反馈。 验证情况未提供验证信息。 ## Boundaries - Do not perform code review unless the user explicitly asks for review. - Do not execute git commit unless the user explicitly asks and confirms. - Do not claim tests passed unless test output is provided or tests were actually run. - Do not include unrelated speculation about files that are not part of the change.这个 Skill 还不完美但已经具备了最小可用形态。它不是一句提示词而是一个小工作流。10. 为什么第一版不加scripts/你可能会问第七篇刚讲完脚本为什么这里不加脚本因为第一版不需要。第一个 Skill 的目标是验证任务是否适合 Skill 化而不是把所有工程能力一次性加满。“生成中文 Git 提交说明”这个任务第一版主要靠 Agent 的语义归纳能力。脚本可以后续再加例如自动读取git diff --stat。自动提取变更文件列表。检查输出是否包含变更主题和有序列表。根据 Conventional Commits 生成英文 commit header。校验主题长度。但这些都不是第一版必须项。第一版应该先回答这个 Skill 会不会正确触发输出是否稳定格式是否符合用户预期是否会编造验证信息是否会误做代码审查或真实提交等这些问题稳定后再考虑脚本化。11. 为什么第一版不加references/同理第一版也不一定需要references/。如果后续要支持更多规范可以再拆参考资料。例如chinese-git-change-summary/ ├── SKILL.md └── references/ ├── commit-style-guide.md ├── conventional-commits.md └── examples.md但现在不需要。原因是任务范围小。输出格式简单。示例数量不多。没有复杂领域知识。过早拆分会增加维护成本。记住渐进式加载不是一开始就多目录而是在复杂度出现时有地方可去。12. 为什么第一版不加assets/这个 Skill 也不需要assets/。assets/适合放模板、示例文件、图片、字体等静态资源。本任务的输出模板很短直接放在SKILL.md中就够了。如果未来出现多个团队模板可以再加assets/ ├── default-template.md ├── frontend-team-template.md └── backend-team-template.md但第一版不要急。13. 添加 2 到 3 个示例前面的完整SKILL.md只放了一个示例。真实 Skill 中可以增加到 2 到 3 个。示例不需要多但要覆盖不同输入形态。13.1 示例一用户描述Input: 新增博客第九篇介绍如何从模板开始写第一个 Skill并补充完整 SKILL.md 示例。 Output: 变更主题新增 Skill 系列第九篇正文 变更内容 1. 新增从模板创建第一个 Skill 的完整教程。 2. 以中文 Git 提交说明为案例演示 SKILL.md 的最小结构。 3. 补充触发条件、执行流程、输出格式和质量标准示例。 验证情况未运行自动化测试仅完成文档内容编写。13.2 示例二文件列表Input: Changed files: - src/login/Form.tsx - src/login/validation.ts - tests/login-validation.test.ts Output: 变更主题完善登录表单校验 变更内容 1. 更新登录表单组件接入字段校验逻辑。 2. 新增登录字段校验规则覆盖必填和格式校验。 3. 补充登录校验相关测试用例。 验证情况根据文件列表推断存在测试变更未提供测试运行结果。这个示例有一个细节它没有说“测试已通过”只说“存在测试变更未提供测试运行结果”。这就是质量标准的体现。13.3 示例三diff 摘要Input: git diff --stat shows: README.md | 20 scripts/build.py | 15 -- Output: 变更主题更新项目说明与构建脚本 变更内容 1. 扩展 README 内容补充项目使用说明。 2. 调整构建脚本逻辑优化构建流程处理。 验证情况未提供构建或测试运行信息。这个示例没有机械地列文件而是把文件变化归纳成有意义的变更点。14. 用真实 prompt 试跑Skill 写完后不要只看文件。要用真实 prompt 试跑。第一版可以设计 3 条 prompt。14.1 常规输入帮我根据下面的变更写一个中文提交说明 - 新增文章第九篇 - 讲解从模板开始写第一个 Skill - 补充中文 Git 提交说明 Skill 示例期望输出有变更主题。有变更内容。变更内容使用有序列表。不编造测试。14.2 模糊输入总结下这次改动按中文提交说明格式输出如果 Agent 有工具权限应该先查看本地变更。如果没有工具权限应该请求用户提供变更信息。不应该凭空生成。14.3 边界输入帮我 review 一下这次 git diff然后写提交说明这个 prompt 包含两个任务code review。提交说明。第一版 Skill 中写了“不要执行 code review除非用户明确要求”。这里用户确实明确要求 review所以 Agent 应该意识到这可能不是单纯提交说明任务。如果系统中还有代码审查 Skill应该优先使用代码审查能力如果没有也应该先做 review再生成提交说明而不是只套用提交说明格式。这类测试能帮助你发现 Skill 边界是否清楚。15. 记录试跑问题第一次试跑时输出通常不会完美。不要急着大改。建议用一张表记录问题。Prompt观察到的问题可能原因调整位置常规输入输出主题太泛Quality Bar 不够明确正文模糊输入直接编造变更缺少信息处理规则不够强Inputs 或 Workflow边界输入忽略 review 需求Boundaries 不够清楚Boundaries 或 description这个表很重要。它能帮你避免“凭感觉修改”。Skill 迭代最好一次只改一个变量触发不对先改 description。步骤漏了改 Workflow。输出不稳改 Output Format 或 Examples。质量不佳改 Quality Bar。资料太长再考虑 references。重复检查不稳再考虑 scripts。这也是第十二篇会展开的迭代方法。16. 常见错误16.1 错误一第一个 Skill 做得太大不推荐一开始就做git-assistant/ └── SKILL.md它同时支持写提交说明。做代码审查。解决冲突。生成 release notes。修改分支策略。自动提交代码。这会导致触发条件混乱正文也会很快变长。第一版应该聚焦。16.2 错误二只有提示词没有流程不推荐请根据用户的 Git 变更写一个专业、清晰、准确的中文提交说明。这句话像提示词不像 Skill。它没有输入说明、没有执行步骤、没有输出格式、没有质量标准也没有边界。Skill 的价值在于把经验拆成流程。16.3 错误三description 太弱不推荐description:Write commit messages.这个描述缺少语言、输入、输出和触发场景。更好的写法至少要说明中文输出。Git 变更来源。用户常见表达。输出是主题和变更列表。16.4 错误四示例太多太散第一个 Skill 不需要 20 个示例。示例太多会让SKILL.md变重也会让 Agent 过度模仿某个示例。先放 2 到 3 个典型示例即可。16.5 错误五编造验证情况提交说明很容易写成验证情况测试通过。但如果没有运行测试就不能这么写。正确做法是验证情况未提供测试运行信息。或者验证情况已运行 npm test测试通过。前提是确实有测试输出。16.6 错误六一开始就上复杂目录不要为了看起来完整就创建chinese-git-change-summary/ ├── SKILL.md ├── references/ ├── scripts/ ├── assets/ ├── examples/ └── evals/如果这些目录暂时没有内容就先不要建。目录应该随着需求增长。17. 第一个 Skill 的自查清单写完第一版后可以用这张表检查。检查项问题任务是否只解决一个清晰任务名称name是否具体、稳定、不过宽触发description是否包含能力、输入、触发表达和输出边界是否说明不适用场景输入是否说明可以接受哪些输入缺失信息输入不足时是否知道该怎么处理流程是否有明确步骤而不是一句提示词输出是否有稳定格式质量是否说明好输出和坏输出的区别示例是否有 2 到 3 个典型示例诚实性是否禁止编造测试或验证结果复杂度是否避免过早引入脚本和参考资料测试是否准备了真实 prompt 试跑如果这张表大部分都能回答清楚第一个 Skill 就已经不错了。18. 从第一版到第二版第一版跑起来后不要马上追求完美。可以根据试跑结果决定下一步。18.1 如果经常不触发优先改description。例如加入更多用户表达Use this skill when the user says 帮我写提交说明, 总结这次改动, 生成变更主题, 写 commit message, or asks for Chinese commit content from local changes.第十篇会专门展开这个问题。18.2 如果输出格式不稳定改Output Format。可以加一句Always use the exact labels 变更主题、变更内容、验证情况.18.3 如果输出太空泛改Quality Bar和示例。例如补充Prefer behavior-level summaries over file-level summaries.意思是不要写“修改了Form.tsx”而是写“完善登录表单校验”。18.4 如果经常编造测试加强边界If tests were not provided or run, write 验证情况未提供验证信息 instead of assuming success.18.5 如果用户开始要求多种格式这时可以考虑扩展 Output Format。例如支持简短版。详细版。Conventional Commits 版。发布说明版。但要谨慎。如果“发布说明版”变得很复杂也许应该拆成另一个 Skill。19. 一个更完整的第二版目录当第一版稳定后可以逐步演进。例如chinese-git-change-summary/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ └── examples.md └── scripts/ └── validate_output.py但注意这是第二阶段不是第一阶段。可能的拆分文件作用SKILL.md主流程、触发后说明、输出格式和资源路由references/style-guide.md团队提交说明风格指南references/examples.md更多好例子和反例scripts/validate_output.py检查输出是否包含固定字段和有序列表SKILL.md中可以增加## Resource Routing - Read references/style-guide.md when the user asks to follow team-specific commit style. - Read references/examples.md when the requested style is unclear. - Run python scripts/validate_output.py --help before validating a generated commit summary file.这就是前面几篇讲过的渐进式加载。20. 小结这一篇讲的是如何从模板开始写第一个 Skill。可以记住三句话第一个 Skill 要选择小而稳定的任务不要一开始就做全能助手。最小 Skill 只需要SKILL.md但它必须包含触发、输入、流程、输出、质量标准、示例和边界。先让第一版跑起来再根据真实 prompt 逐步补 description、examples、references 和 scripts。如果第八篇讲的是“如何设计大型参考资料”那第九篇就是回到最小实践从一个模板开始把一个具体经验封装成可复用能力。下一篇我们会继续优化这个 Skill 的入口如何写一个更容易触发的 description让 Agent 在用户表达模糊时也能正确识别应该使用它。21. 实践任务请创建一个“生成中文 Git 提交说明”的 Skill要求输出主题和有序变更列表。可以按下面步骤做创建目录chinese-git-change-summary/。在目录中创建SKILL.md。写入name和description。补充 Scope、Inputs、Workflow、Output Format、Quality Bar、Examples 和 Boundaries。准备 3 条真实 prompt 试跑。记录试跑问题。只根据明确问题做小步修改。最小目录chinese-git-change-summary/ └── SKILL.md最小 frontmatter---name:chinese-git-change-summarydescription:Generate Chinese Git change summaries from code changes,git diff,git status,or user-described modifications. Use this skill when the user asks to write a Chinese commit message,summarize local changes,generate a change subject,or produce an ordered list of change items for a commit.---输出格式模板变更主题[一句简洁中文主题] 变更内容 1. [变更项 1] 2. [变更项 2] 3. [变更项 3] 验证情况[测试、构建、检查或未验证说明]测试 prompt帮我根据下面的改动生成中文提交说明 - 新增用户资料编辑页面 - 接入头像上传 - 补充表单保存失败提示期望输出主题应该类似“新增用户资料编辑能力”。变更内容应该用有序列表。不应该写“测试通过”除非输入里提供了测试结果。完成这个练习后你就拥有了第一个真正可用的 Skill 雏形。它很小但已经体现了 Skill 的核心思想把重复经验整理成可触发、可执行、可验证的能力包。