anthropics-skills | 03 - 一个 Skill 的最小结构：`SKILL.md`、frontmatter 与正文说明

系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第三篇。前两篇分别解释了 Skill 是什么以及为什么 Skill 的核心价值是把隐性经验变成显性流程。从这一篇开始我们进入文件结构本身一个最小可用的 Skill 到底长什么样1. 从任务卡片到文件上一篇我们把一个希望 Skill 化的任务拆成了九个模块模块关注点任务名称这个任务叫什么触发方式用户通常会怎么提出需求输入信息完成任务必须知道什么背景规则有哪些默认规则不能丢执行流程Agent 应该先做什么再做什么工具资源是否需要脚本、文档、模板或外部工具输出格式最终结果应该长什么样校验标准怎样判断任务真的完成边界条件哪些情况不应该使用这套流程这些信息还是“设计材料”还不是 Skill。要把它变成一个真正可以被 Agent 加载的能力包至少需要一个目录和一个SKILL.md文件。也就是说Skill 的最小形态是my-skill/ └── SKILL.md这个结构非常轻但已经足够表达一类任务的核心上下文。当任务变复杂时Skill 可以继续扩展my-skill/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/不过这一篇我们先克制一点重点只讲最小结构。因为很多 Skill 的第一版并不需要脚本、参考资料和资源文件。先把SKILL.md写清楚往往比一开始就设计复杂目录更重要。2.SKILL.md是 Skill 的入口SKILL.md是一个 Skill 最重要的文件。它通常包含两部分YAML frontmatter写在文件开头用来声明 Skill 的元信息。Markdown 正文写在 frontmatter 后面用来描述执行流程、约束、示例和输出要求。一个最小模板如下--- name: my-skill-name description: A clear description of what this skill does and when to use it. --- # My Skill Name Add instructions here.这个模板里真正必需的是两个字段nameSkill 的稳定标识。description说明 Skill 做什么以及什么时候应该使用。正文虽然没有固定格式但它决定了 Agent 加载 Skill 后具体怎么做。可以把SKILL.md理解成两层部分主要读者作用frontmatterSkill 选择机制和 Agent帮助判断是否加载这个 SkillMarkdown 正文已经加载 Skill 的 Agent指导 Agent 如何完成任务这个区分很重要。很多初学者会把大量触发条件写在正文里却忽略了description。问题是如果 description 没写好Agent 可能根本不会加载正文。3.name稳定、简短、可识别name是 Skill 的唯一标识。它不是展示标题而是一个适合机器识别和目录管理的名字。通常建议使用小写英文。用连字符连接单词。避免空格、中文、特殊符号。保持稳定不要频繁改名。能表达领域或任务不要过度抽象。例如name:tech-writing-outline这个名字能看出它和技术写作大纲有关。再看几个例子任务较好的 name不推荐的 name中文提交说明生成chinese-commit-summarysummary技术文章大纲生成tech-writing-outlinewriterAPI 兼容性检查api-compatibility-reviewcheck页面自动化测试webapp-testingtest-tool不推荐的名字通常有几个问题太泛无法看出具体能力。和其他 Skill 容易冲突。后续维护时不知道它到底负责什么。name一旦被别人引用或安装修改成本就会上升。所以第一版可以不用追求完美但要避免明显过宽或过窄。4.description一句话里写清能力和触发条件description是 Skill 是否会被正确使用的关键入口。它至少要回答两个问题这个 Skill 能做什么用户在什么场景下应该使用它一个太弱的 description 可能是description:Help with writing.问题在于它太泛了。写什么文章、周报、代码注释、PRD、邮件什么时候用用户说“优化这段文字”时用还是“生成技术博客大纲”时用更好的写法是description:Generate structured outlines for Chinese technical articles. Use when the user wants to turn a technical topic,rough notes,or source material into a blog outline,article structure,or writing plan for engineering readers.这段 description 同时说明了能力生成中文技术文章结构化大纲。输入场景技术主题、粗略笔记、素材。输出目标博客大纲、文章结构、写作计划。读者定位工程师读者。如果任务有明显排除条件也可以写进去description:Generate structured outlines for Chinese technical articles. Use when the user wants a blog outline,article structure,or writing plan for engineering readers. Do not use for final long-form drafting,copywriting,or non-technical marketing content.不过 description 的写法值得单独展开。下一篇会专门讨论为什么 description 比正文更影响 Skill 的实际触发效果。这一篇先记住一个原则description 不是口号而是 Skill 的召回说明。它要同时描述能力、触发场景和必要边界。5. 正文Agent 加载后应该怎么做frontmatter 解决“是否加载”的问题正文解决“加载后怎么做”的问题。SKILL.md正文没有强制模板但一个可用的正文通常应该包含这些部分任务目标。适用范围。输入要求。执行流程。输出格式。质量标准。异常处理。示例。不一定每个 Skill 都要完整写满这些标题。最小版本可以很短但不能缺少关键执行信息。下面逐个拆开。6. 任务目标先说这个 Skill 要完成什么正文开头应该让 Agent 明确目标。例如# Tech Writing Outline Use this skill to turn technical topics, rough notes, or source material into a structured Chinese technical article outline for engineering readers.这一段不需要很长但要明确。它和 description 的区别在于description 面向触发阶段尽量短而清晰。正文目标面向执行阶段可以更具体一点。不要在开头写太虚的目标例如Help users write better content.这句话听起来没问题但没有执行指导价值。更好的写法是Help users convert technical material into a problem-oriented article outline with clear audience, core questions, section structure, and a concrete practice task.它直接告诉 Agent输出里要有读者、核心问题、章节结构和实践任务。7. 适用范围说明什么时候用什么时候不用适用范围可以帮助 Agent 减少误用。例如## Scope Use this skill when the user asks for: 1. A Chinese technical article outline. 2. A blog structure based on rough technical notes. 3. A series outline for an engineering topic. 4. A writing plan for developer-facing content. Do not use this skill for: 1. Final long-form article drafting. 2. Non-technical marketing copy. 3. Academic paper writing. 4. Translation-only tasks.你可能会觉得这些内容不是已经写在 description 里了吗确实有重叠。但二者目的不同description 负责让 Agent 知道“要不要加载”。正文里的 Scope 负责让 Agent 加载后进一步确认“这个任务是不是属于我”。当 Skill 较复杂、边界容易混淆时正文里写 Scope 很有帮助。8. 输入要求缺什么信息要知道Skill 不应该默认用户一次性提供了所有信息。如果任务需要关键信息正文里要写清楚。例如技术文章大纲生成至少需要主题。目标读者。写作目标。已有素材。输出粒度。可以这样写## Required Inputs Before drafting the outline, identify whether these inputs are available: 1. Topic. 2. Target audience. 3. Writing goal. 4. Source material or key points. 5. Expected depth or article length. If topic is missing, ask the user for it. If audience or writing goal is missing, make a reasonable assumption and state it briefly before drafting.这里有一个关键点不仅要列出需要什么还要说明缺失时怎么处理。否则 Agent 可能会在信息不完整时一直追问也可能会在应该追问时直接编。一个好的 Skill 应该区分哪些信息缺失时必须询问。哪些信息可以合理假设。哪些假设需要在输出里标注。9. 执行流程把经验变成步骤执行流程是正文里最关键的部分。它应该告诉 Agent 先做什么再做什么。例如## Workflow 1. Identify the topic, audience, and writing goal. 2. Extract the core problem the article should answer. 3. Decide whether the topic should be a single article or a series. 4. Draft a Markdown outline with clear section headings. 5. Add a short explanation for each section. 6. Add one concrete practice task at the end. 7. Review the outline for vague claims, marketing tone, and missing reader value.这个流程看起来简单但它比“帮用户写好大纲”有用得多。流程设计有几个原则。9.1 每一步只做一类事情例如“识别主题、读者和目标”可以是一组因为它们都属于任务理解。但“生成大纲并检查质量”最好拆开。先生成再检查Agent 更容易执行。9.2 步骤顺序要符合真实工作流不要先写标题再反推读者不要先生成结论再找问题。Skill 要沉淀的是有效流程而不是随意罗列要求。9.3 明确关键判断点如果流程里存在分支要写清楚。例如If the topic is too broad for one article, propose a short series plan before drafting the outline.这类判断点通常就是隐性经验最有价值的地方。10. 输出格式让结果稳定可用输出格式决定用户拿到结果后能不能直接使用。一个明确的输出格式可以这样写## Output Format Use Markdown and include: 1. Title suggestion. 2. Target audience. 3. Core question. 4. Article positioning. 5. Section outline. 6. Practice task. 7. Notes or assumptions, if any.如果格式要求很严格可以给出模板## Output Format markdown # [文章标题] ## 目标读者 [说明读者是谁以及他们大概知道什么] ## 核心问题 [这篇文章要回答的一个核心问题] ## 文章定位 [说明文章边界和读者收益] ## 大纲 ### 1. [章节标题] [本节要讲什么] ### 2. [章节标题] [本节要讲什么] ## 实践任务 [一个读者可以立刻执行的小任务] 这里要注意 Markdown 嵌套代码块的问题。如果你在真实SKILL.md里需要展示 Markdown 模板可以使用四个反引号包裹外层代码块避免格式错乱。例如## Output Format markdown # [文章标题] ## 目标读者 [说明读者是谁] 格式越稳定后续测试和评估也越容易。11. 质量标准告诉 Agent 什么叫好只规定格式还不够。格式正确不代表质量合格。例如一个文章大纲可能包含所有标题但每个标题都很空1. 背景介绍 2. 原理分析 3. 实践应用 4. 总结展望这类大纲看起来完整但没有信息密度。所以 Skill 里应该写质量标准## Quality Bar The outline should: 1. Be problem-oriented rather than feature-oriented. 2. Use concrete section headings instead of generic headings. 3. Make the reader value clear in each section. 4. Avoid marketing tone and vague claims. 5. Include a practice task that can be completed independently.质量标准最好可观察、可检查。像“要高级”“要深刻”“要专业”这类表达太抽象。可以改成“先给结论再解释依据。”“每个风险项必须包含影响和缓解方式。”“章节标题要表达具体问题而不是只写‘背景’或‘总结’。”“如果做了假设要在输出末尾列出。”12. 异常处理不要只写顺利路径真实任务经常不完整。用户可能只给一句话也可能给一大段混乱素材还可能要求一个不适合 Skill 的任务。因此正文里需要写异常处理。例如## Handling Missing or Ambiguous Information 1. If the topic is missing, ask one concise question. 2. If the audience is unclear, assume engineering readers and state the assumption. 3. If the user asks for a final full article, provide an outline first and ask whether to continue drafting. 4. If the source material is too broad, propose a series structure.异常处理写清楚后Agent 就不容易在信息不足时乱猜也不容易为了完成任务而扩大范围。这里也有一个平衡不要每缺一个小信息都停下来问用户体验会很差。对会明显影响结果的信息要么询问要么明确假设。对高风险操作要先确认。13. 示例帮助 Agent 对齐风格示例不是必需的但很有帮助。尤其是写作类、设计类、代码审查类 Skill抽象规则往往不够。一个好的示例能让 Agent 更快理解输出风格。例如## Example Input: 用户想写一篇文章主题是“为什么 Agent 需要 Skill”。 Output: # 为什么 Agent 需要 Skill从临时提示词到可复用工作流 ## 目标读者 已经使用 Agent 工具但经常需要重复解释背景和规则的工程师。 ## 核心问题 为什么普通提示词难以支撑稳定、可复用的复杂任务 ## 大纲 ### 1. 临时提示词的局限 说明提示词容易散落、难以复用、缺少工具和评估机制。 ### 2. Skill 的基本形态 介绍 SKILL.md、脚本、参考资料和资源文件。 ## 实践任务 挑一个最近重复使用的提示词写出它的触发方式、输入、输出和重复规则。示例不需要太多。第一版 Skill 放 1 到 2 个高质量示例通常就够了。如果示例越来越多建议后续拆到references/或examples/不要让主文件变得臃肿。14. 可选字段和可选目录最小 Skill 只需要name、description和正文说明。但在真实项目里你可能会看到一些可选字段或目录。14.1 可选字段有些 Skill 会在 frontmatter 里加入额外字段例如---name:docxdescription:Use this skill whenever the user wants to create,read,edit,or manipulate Word documents.license:Proprietary. LICENSE.txt has complete terms---license不是最小必需字段但在开源、内部共享或第三方分发时很有用。一些环境也可能支持compatibility等字段用来声明依赖工具或运行条件。是否需要这些字段要看具体平台和团队约定。对新手来说第一版先写好name和description比急着补很多元信息更重要。14.2 可选目录当 Skill 变复杂时可以增加这些目录my-skill/ ├── SKILL.md ├── scripts/ │ └── check_output.py ├── references/ │ └── style-guide.md └── assets/ └── template.md目录职责可以先这样理解目录适合存放不适合存放scripts/稳定、重复、可验证的程序逻辑大段自然语言规范references/长文档、规范、API 说明、案例每次都必须读的短流程assets/模板、字体、图片、示例文件需要频繁编辑的流程说明不过这些内容会在后续文章展开。第三篇的重点仍然是先让一个 Skill 的最小版本跑起来。15. 一个完整的最小 Skill 示例现在我们把第二篇的“技术文章大纲生成”任务卡片转换成一个最小SKILL.md。目录结构tech-writing-outline/ └── SKILL.mdSKILL.md内容--- name: tech-writing-outline description: Generate structured outlines for Chinese technical articles. Use when the user wants to turn a technical topic, rough notes, or source material into a blog outline, article structure, or writing plan for engineering readers. Do not use for final long-form drafting or non-technical marketing copy. --- # Tech Writing Outline Use this skill to turn technical topics, rough notes, or source material into a structured Chinese technical article outline for engineering readers. ## Scope Use this skill when the user asks for: 1. A Chinese technical article outline. 2. A blog structure based on rough technical notes. 3. A series outline for an engineering topic. 4. A writing plan for developer-facing content. Do not use this skill for: 1. Final long-form article drafting. 2. Non-technical marketing copy. 3. Translation-only tasks. ## Required Inputs Before drafting, identify whether these inputs are available: 1. Topic. 2. Target audience. 3. Writing goal. 4. Source material or key points. 5. Expected depth or article length. If the topic is missing, ask the user for it. If the audience is unclear, assume engineering readers and state the assumption briefly. ## Workflow 1. Identify the topic, audience, and writing goal. 2. Extract the core problem the article should answer. 3. Decide whether the topic should be a single article or a series. 4. Draft a Markdown outline with clear section headings. 5. Add a short explanation for each section. 6. Add one concrete practice task at the end. 7. Review the outline for vague claims, marketing tone, and missing reader value. ## Output Format Use Markdown and include: 1. Title suggestion. 2. Target audience. 3. Core question. 4. Article positioning. 5. Section outline. 6. Practice task. 7. Notes or assumptions, if any. ## Quality Bar The outline should: 1. Be problem-oriented rather than feature-oriented. 2. Use concrete section headings instead of generic headings. 3. Make the reader value clear in each section. 4. Avoid marketing tone and vague claims. 5. Include a practice task that can be completed independently.这个示例已经具备一个最小 Skill 的关键要素name清楚。description覆盖能力、触发场景和排除条件。正文说明目标、范围、输入、流程、输出和质量标准。没有引入暂时不需要的目录和脚本。它还不是一个“完善”的 Skill但已经是一个可以开始测试和迭代的版本。16.SKILL.md里不应该写什么最小结构不等于把所有内容都写进一个文件。下面几类内容要谨慎。16.1 不要写密钥和敏感信息任何 token、密码、私钥、内部账号、生产环境地址都不应该出现在 Skill 中。如果 Skill 需要访问外部服务应通过环境变量、权限系统或 MCP 工具完成而不是把敏感信息写进文档。16.2 不要堆大段完整资料如果资料很长例如完整 API 文档、几十个示例、上千行风格指南不要全部放进SKILL.md。第一版可以只保留主流程和关键约束。长资料后续再拆到references/。16.3 不要写无法执行的抽象口号例如输出要高级。内容要专业。分析要深入。代码要优雅。这些话没有明确行为。更好的写法是先给结论再说明依据。每个风险项包含影响、概率和缓解方式。章节标题要表达具体问题。如果存在假设在输出末尾列出。16.4 不要让一个 Skill 覆盖太多任务一个 Skill 如果同时负责写文章、做代码审查、跑测试、生成发布说明就很难写清楚触发条件和流程。最小 Skill 应该先解决一个清晰任务。以后发现多个任务之间确实共享大量流程再考虑组合或抽象。16.5 不要依赖个人机器路径如果正文里写死类似/Users/alice/scripts/run.sh的路径团队其他人很难复用。更好的方式是使用 Skill 目录内的相对路径或者说明脚本应放在scripts/下。17. 最小 Skill 的自查清单写完第一版SKILL.md后可以用下面这张清单自查。检查项问题名称name是否简短、稳定、能表达任务触发description是否说明了能力和使用场景边界是否写清了不适用的场景输入是否说明缺少关键信息时怎么办流程是否有明确步骤而不是只有原则输出是否给出稳定的输出格式质量是否说明什么叫“好结果”异常是否覆盖缺失信息、歧义或范围过大的情况安全是否避免写入密钥、危险命令和敏感信息维护是否避免把大量参考资料堆进主文件如果这些问题大多能回答清楚这个 Skill 就具备了进入测试阶段的基础。18. 常见错误18.1name太泛例如assistant、helper、writer、review。这些名字看起来简洁但无法表达具体能力。后续 Skill 变多时维护者很难判断它们负责什么。18.2description太像宣传语例如description:A powerful skill for creating amazing content.这类描述没有告诉 Agent 什么时候该用。description 应该更像触发说明而不是产品口号。18.3 正文只有要求没有步骤例如请输出高质量技术文章大纲结构清晰内容专业。这不是流程。Agent 仍然不知道先判断读者还是先列标题什么时候拆成系列怎么检查营销腔。18.4 输出格式不稳定如果正文只写“整理成清晰格式”每次输出可能都不一样。对于团队复用场景最好明确 Markdown 结构、标题层级、列表要求和必要字段。18.5 第一版就过度设计有些人一开始就创建很多目录、脚本、评估文件和复杂规范但真正的主流程还没写清楚。更稳妥的方式是先写最小SKILL.md。用真实任务试跑。发现重复逻辑后再加脚本。发现资料太长后再拆参考文件。发现输出不稳定后再加测试和评估。小步迭代比一次性设计大而全更可靠。19. 小结一个 Skill 的最小结构非常简单my-skill/ └── SKILL.md而SKILL.md的最小核心是--- name: my-skill-name description: What this skill does and when to use it. --- # Skill Instructions Instructions for how the Agent should complete the task.但简单不代表随便写。name要稳定可识别description要说明能力、触发场景和边界正文要写清目标、输入、流程、输出、质量标准和异常处理。可以记住这句话最小 Skill 的目标不是覆盖所有情况而是让一类高频任务第一次拥有清晰、可复用、可迭代的执行说明。下一篇我们会继续深入description。因为在真实使用中一个 Skill 写得再好如果 description 没有让它在正确场景下被加载它的正文就没有机会发挥作用。20. 实践任务请把上一篇实践任务中填写的表格转换成一个最小SKILL.md。可以使用下面这个模板--- name: your-skill-name description: Describe what this skill does, when to use it, and when not to use it. --- # Your Skill Name Use this skill to [说明任务目标]. ## Scope Use this skill when: 1. [适用场景 1] 2. [适用场景 2] Do not use this skill when: 1. [不适用场景 1] 2. [不适用场景 2] ## Required Inputs Before starting, identify whether these inputs are available: 1. [输入 1] 2. [输入 2] 3. [输入 3] If [关键信息] is missing, ask the user. If [可假设信息] is missing, make a reasonable assumption and state it. ## Workflow 1. [步骤 1] 2. [步骤 2] 3. [步骤 3] 4. [自查步骤] ## Output Format Use Markdown and include: 1. [输出部分 1] 2. [输出部分 2] 3. [输出部分 3] ## Quality Bar The output should: 1. [质量标准 1] 2. [质量标准 2] 3. [质量标准 3]写完后不要急着加脚本或参考资料。先用 2 到 3 个真实任务试跑看看它是否能稳定改变 Agent 的行为。下一篇我们会重点优化其中最关键的一行description。