Claude Skill 构建指南总结一、这份指南在讲什么这份《The Complete Guide to Building Skills for Claude》系统讲解了如何为 Claude 设计、实现、测试、分发Skill。文中把 Skill 定义为一种“可打包、可复用的任务能力封装”它不是单次对话里的提示词而是一套长期可复用的指令、流程、参考资料与可执行脚本。它的核心价值是把反复出现的工作流沉淀下来让 Claude 在合适场景下自动调用正确的方法降低每次重新解释背景、规则、步骤的成本让不同用户、不同会话下的执行结果更稳定从适用对象来看这份指南面向三类人希望 Claude 稳定执行特定流程的开发者想把个人方法论固化下来的高频用户希望在团队内统一 AI 工作方式的组织二、什么是 Skill2.1 Skill 的本质指南对 Skill 的定义很明确Skill 是一个文件夹其中包含 Claude 在某类任务中需要遵循的说明和资源。一个标准 Skill 通常由以下内容组成SKILL.md必需主说明文件scripts/可选放可执行脚本references/可选放参考文档assets/可选放模板、字体、图标等资源这意味着 Skill 不是一句 prompt也不是零散文档而是一个结构化能力包。2.2 Skill 解决什么问题如果没有 Skill用户往往需要在每次对话中重复描述要做什么按什么流程做有哪些边界条件失败后怎么处理输出需要符合什么规范有了 Skill 之后这些信息可以一次沉淀、重复复用。Claude 在识别到合适场景时就能自动加载并执行对应能力。2.3 Skill 与普通 Prompt 的区别可以把两者理解为Prompt一次性指令偏即时Skill长期能力资产偏可复用Prompt 更适合临时任务Skill 更适合可重复、可标准化、可沉淀的任务。三、为什么 Skill 很重要3.1 对个人用户的价值对个人来说Skill 的最大意义是把“经验”变成“默认行为”。例如写研究报告时始终按固定分析框架展开生成前端页面时自动遵循既定设计风格调用某类工具时按稳定步骤执行而不是每次临场发挥这样可以显著减少重复沟通和返工。3.2 对团队和组织的价值对团队来说Skill 更像是一种AI 工作规范载体。它可以把团队约定统一固化为 Claude 的执行方式例如文档模板和写作规范研发或运营工作流某类平台的最佳实践特定业务域的专业判断规则这样团队成员即使提示方式不同Claude 也能更一致地输出结果。3.3 对 MCP 场景的价值文中专门强调了 Skill 与 MCP 的配合价值。MCP提供“能做什么”——即对外部系统、服务、数据、工具的访问能力Skill提供“应该怎么做”——即工作流、方法论、最佳实践指南用了一个很形象的比喻MCP 像专业厨房提供设备和食材Skill 像菜谱告诉你如何把这些资源变成有价值的结果因此只有 MCP 没有 Skill常见问题是用户接上能力后不知道下一步该怎么做每次都要重新解释流程工具调用不稳定结果不一致用户把“不会用”误认为“连接器不好用”Skill 的作用就是把这些使用门槛前置消化掉。四、Skill 的核心设计原则文中提出了三个关键原则。4.1 Progressive Disclosure渐进式加载这是整份指南里最核心的设计思想之一。Skill 采用三层加载结构第一层YAML frontmatter始终进入 Claude 的系统提示中用来判断“这个 Skill 什么时候该被用到”。第二层SKILL.md正文只有在 Claude 判断当前任务相关时才加载用于提供完整操作说明。第三层外链资源文件例如references/下的资料只有确实需要时才进一步查看。这样做的好处是节省上下文 token保留专门知识避免把所有细节一股脑塞进主上下文让 Skill 既专业又不臃肿可理解为先让 Claude 知道“何时用”再让它知道“怎么做”最后在必要时补充“细节资料”。4.2 Composability可组合性Claude 可以同时加载多个 Skill因此单个 Skill 不能假设自己是系统中唯一的能力。这意味着设计 Skill 时要注意不要写成与其他 Skill 强冲突说明边界和适用范围让它能与其他能力协同工作好的 Skill 不是封闭的而是可组合的。4.3 Portability可移植性指南强调Skill 应尽量做到“一次构建多处可用”可运行在 Claude.ai、Claude Code 和 API 场景中。这要求作者注意环境依赖要清楚文件结构要标准不要依赖某个特定使用界面才成立的隐含假设如果有额外依赖也应该通过compatibility等字段说明清楚。五、设计 Skill 时应该先想什么5.1 从 Use Case 出发而不是从文件开始指南明确建议不要一上来就写代码或写说明先定义 2~3 个明确的用例。一个好的用例定义通常包括用户想完成什么目标触发语句可能是什么整个工作流分几步需要哪些工具最终结果长什么样文中的示例是“冲刺规划Sprint Planning”结构非常典型触发用户说“帮我规划这个 sprint”步骤拉取当前状态、分析容量、建议优先级、创建任务结果输出完整的 Sprint 规划这个方法背后的本质是Skill 不是写给作者自己看的而是为了让 Claude 在实际用户任务里稳定复现一套目标导向流程。5.2 三类常见 Skill 场景指南总结了三种高频模式。类别一文档与资产生成适合输出标准化成果物例如文档报告演示稿设计稿页面或代码其关键技巧包括内嵌风格规范预设输出模板交付前质量检查清单充分利用 Claude 自带的生成能力类别二工作流自动化适合多步骤流程例如建立项目处理审批生成任务执行跨系统动作关键技巧是明确步骤顺序加入校验门内置迭代优化闭环用模板提升流程稳定性类别三MCP 能力增强适合在已有 MCP 接入基础上进一步加入方法论和业务知识。关键技巧包括按顺序协调多个工具调用将领域知识嵌入流程替用户补齐隐含上下文对常见错误做提前处理六、如何定义一个“好 Skill”的成功标准文中指出Skill 的成功不只是“能运行”而是要看它是否在真实任务中稳定生效。6.1 定量指标建议关注以下指标是否能在大多数相关问题上正确触发完成任务所需工具调用次数是否降低token 消耗是否下降每次工作流中的 API 失败次数是否减少例如可以比较“有 Skill”和“无 Skill”两种情况下需要几轮来回澄清是否出现失败重试总调用成本如何6.2 定性指标还要观察用户是否还需要频繁提醒下一步工作流是否能在较少人工纠正下跑完不同会话下结果是否一致新用户是否能较低门槛上手指南承认这里暂时还存在一定“经验判断”成分但方向很清楚Skill 的目标是提升稳定性、可用性和复用价值。七、Skill 的技术结构要求7.1 文件结构要求标准结构如下your-skill-name/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/其中只有SKILL.md是强制项其余目录按需添加。7.2 命名规范Skill 文件夹和name字段都应使用kebab-case也就是全小写、单词之间用-连接。正确示例notion-project-setup错误示例Notion Project Setupnotion_project_setupNotionProjectSetup7.3SKILL.md必须严格命名文中特别强调必须叫SKILL.md大小写必须准确不能写成skill.md、SKILL.MD等变体7.4 Skill 目录内不要放README.mdSkill 目录是给 Claude 用的不是给人类读者看的。因此面向 Claude 的内容放在SKILL.md或references/如果要开源展示可在仓库根目录写面向人的README.md这个区分很重要Skill 内部强调机器可执行与可判断仓库层面才强调人类理解与安装说明。八、最关键的部分YAML Frontmatter指南明确指出frontmatter 是 Skill 最重要的部分。因为 Claude 是否决定加载某个 Skill首先依赖这里的元信息。8.1 最小可用格式最简结构如下---name:your-skill-namedescription:What it does. Use when user asks to[specific phrases].---起步时只要有这两个字段就可以。8.2name字段要求必填必须使用 kebab-case最好和文件夹名一致不能包含保留词例如claude、anthropic8.3description字段要求这是最重要的字段必须同时说明两件事这个 Skill 做什么什么时候应该使用它还要满足1024 字以内不能有 XML 尖括号 应尽量写出用户真实会说的话如果和文件类型相关要写出文件类型文中给出了很重要的判断逻辑description的任务是让 Claude 在不加载完整 Skill 的情况下也能判断这项能力是否适用。这本质上就是触发机制设计。8.4 可选字段可选字段包括licensecompatibilitymetadata其中metadata可用于放作者版本关联 MCP 服务类别、标签、文档地址等这些信息不会替代主逻辑但对维护、分发、版本管理很有帮助。8.5 安全限制frontmatter 中禁止XML 尖括号 带有claude或anthropic的 Skill 名称原因很直接frontmatter 会进入系统提示若允许注入性内容存在安全风险。九、如何写出有效的 Skill 说明9.1description要写得像“触发器说明”不是简介文中对好坏写法对比得非常清楚。好的写法具有三个特征清楚说明做什么明确列出何时使用包含用户可能会说出的触发词例如当用户上传.fig文件时使用当用户说“design specs”时使用当用户提到“sprint”“create tickets”时使用坏的写法则通常是过于抽象只讲能力不讲触发条件过于技术化但没有用户视角一个实用判断标准是如果只看 descriptionClaude 能否知道“什么时候该调用它”9.2 主说明要足够具体、可执行SKILL.md正文建议包含明确的操作步骤命令或工具调用示例成功结果示例常见场景案例故障排查说明文中推荐的组织结构大致是Skill 名称Instructions分步骤说明示例Troubleshooting9.3 写指令时的最佳实践指南强调几条很实用的原则原则 1具体而不是泛泛而谈好例子明确执行哪个脚本明确输入参数格式明确失败后要检查什么差例子“在继续前先验证一下数据”前者可执行后者仍然要靠 Claude 自己猜。原则 2要有错误处理如果接入了 MCP 或外部系统应该提前写出常见错误是什么可能原因是什么如何恢复或重试原则 3详细资料放到references/不要把所有内容都塞进SKILL.md。更好的方式是在主说明里保留核心流程详细规范、错误码、分页规则等放到references/需要时再查这正是“渐进式加载”的实践体现。十、Skill 的测试与迭代方法指南没有把 Skill 看成“一次写完”的产物而是强调持续迭代。10.1 三类测试方式可以按需求选择不同强度手工测试直接在 Claude.ai 中试脚本化测试在 Claude Code 中批量验证程序化测试通过 Skills API 构建系统性评估不同场景对测试要求不同小团队内部使用可偏快速迭代大规模面向企业用户需要更严格验证10.2 推荐测试框架文中建议至少覆盖三类测试。1触发测试验证 Skill 是否在该触发时触发不该触发时不触发。应测明显表达同义改写无关请求这是验证description是否写对的关键。2功能测试验证 Skill 执行后结果是否正确。应测输出是否有效API 是否成功错误处理是否生效边界情况是否覆盖3效果对比测试比较有 Skill 和无 Skill 的差异例如来回消息数是否更少失败调用是否更少token 是否更省用户是否更少干预10.3 迭代策略先打磨一个难任务这是指南中非常有启发的一点先围绕一个困难但典型的任务反复调到成功再把成功做法提炼成 Skill。也就是说不要一开始就追求覆盖面很广先找到一个代表性任务把流程打磨稳定再逐步扩展。这样获得的反馈最直接迭代速度也更快。10.4 关注三类失败信号触发不足Undertriggering表现为本该触发却没触发用户需要手动开启用户经常问“这个什么时候用”解决思路在description中加入更明确的场景词、专业词、触发语句过度触发Overtriggering表现为不相关任务也触发用户频繁关闭技能边界模糊解决思路加入负向触发条件收窄描述范围明确“不适用于什么”执行问题表现为结果不稳定工具调用容易失败用户需要频繁纠正解决思路精炼说明增加错误处理把关键校验做成脚本而不只靠语言描述十一、Skill 的分发与共享11.1 当前分发方式指南介绍了 Skill 的主流分发方式个人用户可下载 Skill 文件夹后上传到 Claude.ai也可放到 Claude Code 的技能目录中组织管理员可在工作区范围内统一部署这表明 Skill 不只是个人配置也可以成为组织级能力资产。11.2 技能标准是开放的Anthropic 将 Agent Skills 作为开放标准来推动希望 Skill 像 MCP 一样具备跨平台可移植性。这意味着Skill 不应只为某个产品页面而写设计时要尽量遵循标准结构如果有平台特定依赖应明确写在兼容性说明里11.3 API 使用场景对于应用、代理系统、自动化流程等程序化场景可以通过 API 管理和调用 Skill。适合 API 的场景包括生产环境部署自动化流水线自定义智能体系统规模化应用集成而手工开发、调试和临时使用更适合 Claude.ai 或 Claude Code。11.4 推荐的对外发布方式文中建议把 Skill 托管到 GitHub写清 README、安装方法、截图和示例在 MCP 仓库或产品文档里链接这个 Skill给出快速上手指南这里有一个重要区分Skill 文件夹内部不给 README公开仓库根目录应有 README服务于人类用户11.5 对外描述要强调“结果价值”指南特别提醒向外介绍 Skill 时不要只讲技术结构而要讲用户收益。正确表达应聚焦它替用户节省了什么时间它把什么复杂工作自动化了它与 MCP 配合后能实现什么结果也就是讲“成果”不要只讲“机制”。十二、五种常见 Skill 设计模式这一章非常适合实际落地时参考。12.1 顺序式工作流编排适用于必须按固定顺序执行的流程。特点步骤依赖明确每一步有输入输出可在中间设置校验失败时可定义回滚典型场景开户、订阅、通知等严格链式流程。12.2 多 MCP 协同适用于跨多个系统的复合任务。例如从设计平台导出资源存入云盘在任务系统中建单再发通知其重点在于阶段划分清楚数据在不同 MCP 间顺畅传递每阶段切换前先校验统一做错误处理12.3 迭代式优化适用于成果质量需要逐轮提升的场景例如报告生成。典型流程先生成初稿跑校验找问题修复并重生成局部反复迭代直到满足标准关键不是“多做几轮”而是建立明确的质量标准和停止条件。12.4 上下文感知的工具选择适用于同一目标在不同上下文下要选择不同工具的场景。例如文件存储大文件走云存储协作文档走 Docs/Notion代码文件走 GitHub临时文件走本地这种模式的核心是先有清晰决策树再做工具选择最后向用户解释原因12.5 领域智能嵌入适用于 Skill 除了会调用工具还承担专业判断职责的场景。例如金融合规处理先检查制裁名单判断司法辖区评估风险记录合规决策只有通过后才处理交易这类 Skill 的价值不只是“自动化”而是把领域知识直接融入执行逻辑。十三、常见问题与排查思路13.1 技能上传失败常见原因SKILL.md文件名不正确frontmatter YAML 格式错误name字段不符合 kebab-case 规范这是最基础也最常见的问题通常先检查文件名是否完全正确YAML 是否有---包裹是否有未闭合引号或格式错误13.2 技能不触发最常见原因是description写得太泛。检查重点是否明确写了触发短语是否包含用户真实会说的话是否提及相关文件类型是否把任务范围写得足够具体指南还给了一个很实用的调试方法直接问 Claude“什么时候会用这个 Skill”看它是否只复述了模糊描述再针对缺失信息修改description13.3 技能触发过多如果频繁在不相关场景下被拉起解决办法包括加负向触发条件缩小场景范围明确“只适用于什么不适用于什么”13.4 MCP 连接问题如果 Skill 已经触发但工具调用失败排查顺序应是MCP 是否连接成功鉴权是否过期或权限不足不带 Skill 时单独调用 MCP 能否成功Skill 内写的工具名是否正确且大小写匹配也就是说要先区分是“工具连接有问题”还是“Skill 编排有问题”。13.5 指令没有被很好遵循常见原因有说明过长、过散关键规则埋得太深表达含糊只说原则没有给出可执行检查项指南给出的优化方向非常实用把关键要求放到前面使用Critical、Important等显眼标题把模糊要求改写成可核验清单对关键校验尽量用脚本实现而不是只靠自然语言13.6 上下文过大导致效果下降表现为响应变慢结果变差技能内容难以稳定执行对应优化方式缩短SKILL.md把细节移到references/控制同时启用的 Skill 数量对相关能力打包而不是全量开启十四、文末提供的实用清单14.1 Quick Checklist 的价值文末的快速检查清单很适合拿来做发布前自检。它覆盖了四个阶段开始前开发中上传前上传后其中最值得落实的检查点包括是否已明确 2~3 个用例是否确定所需工具文件夹命名是否规范SKILL.md是否存在且命名准确description是否同时写明做什么、何时用是否已测触发与误触发是否完成功能测试上传后是否继续收集反馈并迭代这说明 Skill 不是“写完就完”而是一个持续维护的产品化资产。14.2 Frontmatter 参考价值文末还给了 frontmatter 的完整示例帮助作者理解最小必填结构是什么可选字段怎么扩展什么内容允许写什么内容禁止写对于新手来说这一部分非常适合当模板起点。14.3 示例技能仓库的重要性官方还给出了公开示例技能仓库与合作伙伴目录。它们的意义不只是“给你看例子”更重要的是帮你理解成熟 Skill 的组织方式帮你参考不同场景的写法帮你在真实案例基础上改造而不是从零空想十五、这份指南传达的核心方法论如果把整份 PDF 压缩成一套方法论我认为可以总结为以下几点。15.1 Skill 不是提示词技巧而是能力工程它关注的不是“怎么把一句 prompt 写得更像魔法”而是怎么把知识、流程、资源、脚本组织成可复用资产怎么让 Claude 在正确时机自动使用它怎么通过结构设计降低上下文负担怎么通过测试和迭代不断提高稳定性15.2 好 Skill 的核心不是“内容多”而是“触发准、步骤清、边界明”一个优秀 Skill 往往具备这些特征description让 Claude 知道何时该用SKILL.md让 Claude 知道具体怎么做references/让 Claude 在需要时获取细节scripts/让高风险校验更确定、更稳定15.3 Skill 的设计应从真实工作流逆推最好的起点不是抽象能力名称而是用户到底想完成什么结果为实现这个结果Claude 应按什么步骤做哪些地方需要专业判断哪些地方必须做校验和容错15.4 Skill 与 MCP 结合后AI 才真正接近“可交付工作流”MCP 解决连接问题Skill 解决执行质量问题。只有二者结合Claude 才能从“有工具可用”进一步走向“会正确使用工具完成复杂工作”。十六、面向实践的落地建议如果你准备真正开始做 Skill可以直接按这条路线推进先选一个高频、重复、容易出错的任务不要一开始贪大求全。写出 2~3 个明确用例包括触发语句、步骤、结果。先把description打磨准确它决定触发效果优先级极高。主说明聚焦核心流程详细资料移入references/。高风险校验尽量脚本化尤其是格式检查、参数校验、质量检查。优先做触发测试和功能测试先保证“能在对的时候触发、触发后能跑通”。关注 undertriggering / overtriggering 信号这两类问题几乎是所有 Skill 迭代的主轴。把 Skill 当产品维护而不是一次性交付收集反馈、修描述、补错误处理、更新版本。十七、总结这份指南最有价值的地方不在于告诉你一个“Skill 文件夹该怎么摆”而在于它清楚定义了 Skill 的产品思维它是一个可复用能力单元它以触发机制为入口以结构化说明为核心以渐进式加载控制复杂度以测试和迭代保障质量以分发和共享实现规模化价值如果只用一句话概括Skill 的本质是把零散经验、专业方法和工具使用策略沉淀成 Claude 可以稳定调用的工作能力。对于个人它意味着更少重复说明对于团队它意味着更一致的 AI 协作方式对于 MCP 生态它意味着从“接上能力”升级到“真正把能力用起来”。如果你后续要基于这份指南自己设计 Skill最值得优先记住的三个关键词是触发准确说明具体迭代持续这三点基本决定了一个 Skill 最终是否真正好用。
Claude Skill 构建指南总结
发布时间：2026/5/27 14:52:04
Claude Skill 构建指南总结一、这份指南在讲什么这份《The Complete Guide to Building Skills for Claude》系统讲解了如何为 Claude 设计、实现、测试、分发Skill。文中把 Skill 定义为一种“可打包、可复用的任务能力封装”它不是单次对话里的提示词而是一套长期可复用的指令、流程、参考资料与可执行脚本。它的核心价值是把反复出现的工作流沉淀下来让 Claude 在合适场景下自动调用正确的方法降低每次重新解释背景、规则、步骤的成本让不同用户、不同会话下的执行结果更稳定从适用对象来看这份指南面向三类人希望 Claude 稳定执行特定流程的开发者想把个人方法论固化下来的高频用户希望在团队内统一 AI 工作方式的组织二、什么是 Skill2.1 Skill 的本质指南对 Skill 的定义很明确Skill 是一个文件夹其中包含 Claude 在某类任务中需要遵循的说明和资源。一个标准 Skill 通常由以下内容组成SKILL.md必需主说明文件scripts/可选放可执行脚本references/可选放参考文档assets/可选放模板、字体、图标等资源这意味着 Skill 不是一句 prompt也不是零散文档而是一个结构化能力包。2.2 Skill 解决什么问题如果没有 Skill用户往往需要在每次对话中重复描述要做什么按什么流程做有哪些边界条件失败后怎么处理输出需要符合什么规范有了 Skill 之后这些信息可以一次沉淀、重复复用。Claude 在识别到合适场景时就能自动加载并执行对应能力。2.3 Skill 与普通 Prompt 的区别可以把两者理解为Prompt一次性指令偏即时Skill长期能力资产偏可复用Prompt 更适合临时任务Skill 更适合可重复、可标准化、可沉淀的任务。三、为什么 Skill 很重要3.1 对个人用户的价值对个人来说Skill 的最大意义是把“经验”变成“默认行为”。例如写研究报告时始终按固定分析框架展开生成前端页面时自动遵循既定设计风格调用某类工具时按稳定步骤执行而不是每次临场发挥这样可以显著减少重复沟通和返工。3.2 对团队和组织的价值对团队来说Skill 更像是一种AI 工作规范载体。它可以把团队约定统一固化为 Claude 的执行方式例如文档模板和写作规范研发或运营工作流某类平台的最佳实践特定业务域的专业判断规则这样团队成员即使提示方式不同Claude 也能更一致地输出结果。3.3 对 MCP 场景的价值文中专门强调了 Skill 与 MCP 的配合价值。MCP提供“能做什么”——即对外部系统、服务、数据、工具的访问能力Skill提供“应该怎么做”——即工作流、方法论、最佳实践指南用了一个很形象的比喻MCP 像专业厨房提供设备和食材Skill 像菜谱告诉你如何把这些资源变成有价值的结果因此只有 MCP 没有 Skill常见问题是用户接上能力后不知道下一步该怎么做每次都要重新解释流程工具调用不稳定结果不一致用户把“不会用”误认为“连接器不好用”Skill 的作用就是把这些使用门槛前置消化掉。四、Skill 的核心设计原则文中提出了三个关键原则。4.1 Progressive Disclosure渐进式加载这是整份指南里最核心的设计思想之一。Skill 采用三层加载结构第一层YAML frontmatter始终进入 Claude 的系统提示中用来判断“这个 Skill 什么时候该被用到”。第二层SKILL.md正文只有在 Claude 判断当前任务相关时才加载用于提供完整操作说明。第三层外链资源文件例如references/下的资料只有确实需要时才进一步查看。这样做的好处是节省上下文 token保留专门知识避免把所有细节一股脑塞进主上下文让 Skill 既专业又不臃肿可理解为先让 Claude 知道“何时用”再让它知道“怎么做”最后在必要时补充“细节资料”。4.2 Composability可组合性Claude 可以同时加载多个 Skill因此单个 Skill 不能假设自己是系统中唯一的能力。这意味着设计 Skill 时要注意不要写成与其他 Skill 强冲突说明边界和适用范围让它能与其他能力协同工作好的 Skill 不是封闭的而是可组合的。4.3 Portability可移植性指南强调Skill 应尽量做到“一次构建多处可用”可运行在 Claude.ai、Claude Code 和 API 场景中。这要求作者注意环境依赖要清楚文件结构要标准不要依赖某个特定使用界面才成立的隐含假设如果有额外依赖也应该通过compatibility等字段说明清楚。五、设计 Skill 时应该先想什么5.1 从 Use Case 出发而不是从文件开始指南明确建议不要一上来就写代码或写说明先定义 2~3 个明确的用例。一个好的用例定义通常包括用户想完成什么目标触发语句可能是什么整个工作流分几步需要哪些工具最终结果长什么样文中的示例是“冲刺规划Sprint Planning”结构非常典型触发用户说“帮我规划这个 sprint”步骤拉取当前状态、分析容量、建议优先级、创建任务结果输出完整的 Sprint 规划这个方法背后的本质是Skill 不是写给作者自己看的而是为了让 Claude 在实际用户任务里稳定复现一套目标导向流程。5.2 三类常见 Skill 场景指南总结了三种高频模式。类别一文档与资产生成适合输出标准化成果物例如文档报告演示稿设计稿页面或代码其关键技巧包括内嵌风格规范预设输出模板交付前质量检查清单充分利用 Claude 自带的生成能力类别二工作流自动化适合多步骤流程例如建立项目处理审批生成任务执行跨系统动作关键技巧是明确步骤顺序加入校验门内置迭代优化闭环用模板提升流程稳定性类别三MCP 能力增强适合在已有 MCP 接入基础上进一步加入方法论和业务知识。关键技巧包括按顺序协调多个工具调用将领域知识嵌入流程替用户补齐隐含上下文对常见错误做提前处理六、如何定义一个“好 Skill”的成功标准文中指出Skill 的成功不只是“能运行”而是要看它是否在真实任务中稳定生效。6.1 定量指标建议关注以下指标是否能在大多数相关问题上正确触发完成任务所需工具调用次数是否降低token 消耗是否下降每次工作流中的 API 失败次数是否减少例如可以比较“有 Skill”和“无 Skill”两种情况下需要几轮来回澄清是否出现失败重试总调用成本如何6.2 定性指标还要观察用户是否还需要频繁提醒下一步工作流是否能在较少人工纠正下跑完不同会话下结果是否一致新用户是否能较低门槛上手指南承认这里暂时还存在一定“经验判断”成分但方向很清楚Skill 的目标是提升稳定性、可用性和复用价值。七、Skill 的技术结构要求7.1 文件结构要求标准结构如下your-skill-name/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/其中只有SKILL.md是强制项其余目录按需添加。7.2 命名规范Skill 文件夹和name字段都应使用kebab-case也就是全小写、单词之间用-连接。正确示例notion-project-setup错误示例Notion Project Setupnotion_project_setupNotionProjectSetup7.3SKILL.md必须严格命名文中特别强调必须叫SKILL.md大小写必须准确不能写成skill.md、SKILL.MD等变体7.4 Skill 目录内不要放README.mdSkill 目录是给 Claude 用的不是给人类读者看的。因此面向 Claude 的内容放在SKILL.md或references/如果要开源展示可在仓库根目录写面向人的README.md这个区分很重要Skill 内部强调机器可执行与可判断仓库层面才强调人类理解与安装说明。八、最关键的部分YAML Frontmatter指南明确指出frontmatter 是 Skill 最重要的部分。因为 Claude 是否决定加载某个 Skill首先依赖这里的元信息。8.1 最小可用格式最简结构如下---name:your-skill-namedescription:What it does. Use when user asks to[specific phrases].---起步时只要有这两个字段就可以。8.2name字段要求必填必须使用 kebab-case最好和文件夹名一致不能包含保留词例如claude、anthropic8.3description字段要求这是最重要的字段必须同时说明两件事这个 Skill 做什么什么时候应该使用它还要满足1024 字以内不能有 XML 尖括号 应尽量写出用户真实会说的话如果和文件类型相关要写出文件类型文中给出了很重要的判断逻辑description的任务是让 Claude 在不加载完整 Skill 的情况下也能判断这项能力是否适用。这本质上就是触发机制设计。8.4 可选字段可选字段包括licensecompatibilitymetadata其中metadata可用于放作者版本关联 MCP 服务类别、标签、文档地址等这些信息不会替代主逻辑但对维护、分发、版本管理很有帮助。8.5 安全限制frontmatter 中禁止XML 尖括号 带有claude或anthropic的 Skill 名称原因很直接frontmatter 会进入系统提示若允许注入性内容存在安全风险。九、如何写出有效的 Skill 说明9.1description要写得像“触发器说明”不是简介文中对好坏写法对比得非常清楚。好的写法具有三个特征清楚说明做什么明确列出何时使用包含用户可能会说出的触发词例如当用户上传.fig文件时使用当用户说“design specs”时使用当用户提到“sprint”“create tickets”时使用坏的写法则通常是过于抽象只讲能力不讲触发条件过于技术化但没有用户视角一个实用判断标准是如果只看 descriptionClaude 能否知道“什么时候该调用它”9.2 主说明要足够具体、可执行SKILL.md正文建议包含明确的操作步骤命令或工具调用示例成功结果示例常见场景案例故障排查说明文中推荐的组织结构大致是Skill 名称Instructions分步骤说明示例Troubleshooting9.3 写指令时的最佳实践指南强调几条很实用的原则原则 1具体而不是泛泛而谈好例子明确执行哪个脚本明确输入参数格式明确失败后要检查什么差例子“在继续前先验证一下数据”前者可执行后者仍然要靠 Claude 自己猜。原则 2要有错误处理如果接入了 MCP 或外部系统应该提前写出常见错误是什么可能原因是什么如何恢复或重试原则 3详细资料放到references/不要把所有内容都塞进SKILL.md。更好的方式是在主说明里保留核心流程详细规范、错误码、分页规则等放到references/需要时再查这正是“渐进式加载”的实践体现。十、Skill 的测试与迭代方法指南没有把 Skill 看成“一次写完”的产物而是强调持续迭代。10.1 三类测试方式可以按需求选择不同强度手工测试直接在 Claude.ai 中试脚本化测试在 Claude Code 中批量验证程序化测试通过 Skills API 构建系统性评估不同场景对测试要求不同小团队内部使用可偏快速迭代大规模面向企业用户需要更严格验证10.2 推荐测试框架文中建议至少覆盖三类测试。1触发测试验证 Skill 是否在该触发时触发不该触发时不触发。应测明显表达同义改写无关请求这是验证description是否写对的关键。2功能测试验证 Skill 执行后结果是否正确。应测输出是否有效API 是否成功错误处理是否生效边界情况是否覆盖3效果对比测试比较有 Skill 和无 Skill 的差异例如来回消息数是否更少失败调用是否更少token 是否更省用户是否更少干预10.3 迭代策略先打磨一个难任务这是指南中非常有启发的一点先围绕一个困难但典型的任务反复调到成功再把成功做法提炼成 Skill。也就是说不要一开始就追求覆盖面很广先找到一个代表性任务把流程打磨稳定再逐步扩展。这样获得的反馈最直接迭代速度也更快。10.4 关注三类失败信号触发不足Undertriggering表现为本该触发却没触发用户需要手动开启用户经常问“这个什么时候用”解决思路在description中加入更明确的场景词、专业词、触发语句过度触发Overtriggering表现为不相关任务也触发用户频繁关闭技能边界模糊解决思路加入负向触发条件收窄描述范围明确“不适用于什么”执行问题表现为结果不稳定工具调用容易失败用户需要频繁纠正解决思路精炼说明增加错误处理把关键校验做成脚本而不只靠语言描述十一、Skill 的分发与共享11.1 当前分发方式指南介绍了 Skill 的主流分发方式个人用户可下载 Skill 文件夹后上传到 Claude.ai也可放到 Claude Code 的技能目录中组织管理员可在工作区范围内统一部署这表明 Skill 不只是个人配置也可以成为组织级能力资产。11.2 技能标准是开放的Anthropic 将 Agent Skills 作为开放标准来推动希望 Skill 像 MCP 一样具备跨平台可移植性。这意味着Skill 不应只为某个产品页面而写设计时要尽量遵循标准结构如果有平台特定依赖应明确写在兼容性说明里11.3 API 使用场景对于应用、代理系统、自动化流程等程序化场景可以通过 API 管理和调用 Skill。适合 API 的场景包括生产环境部署自动化流水线自定义智能体系统规模化应用集成而手工开发、调试和临时使用更适合 Claude.ai 或 Claude Code。11.4 推荐的对外发布方式文中建议把 Skill 托管到 GitHub写清 README、安装方法、截图和示例在 MCP 仓库或产品文档里链接这个 Skill给出快速上手指南这里有一个重要区分Skill 文件夹内部不给 README公开仓库根目录应有 README服务于人类用户11.5 对外描述要强调“结果价值”指南特别提醒向外介绍 Skill 时不要只讲技术结构而要讲用户收益。正确表达应聚焦它替用户节省了什么时间它把什么复杂工作自动化了它与 MCP 配合后能实现什么结果也就是讲“成果”不要只讲“机制”。十二、五种常见 Skill 设计模式这一章非常适合实际落地时参考。12.1 顺序式工作流编排适用于必须按固定顺序执行的流程。特点步骤依赖明确每一步有输入输出可在中间设置校验失败时可定义回滚典型场景开户、订阅、通知等严格链式流程。12.2 多 MCP 协同适用于跨多个系统的复合任务。例如从设计平台导出资源存入云盘在任务系统中建单再发通知其重点在于阶段划分清楚数据在不同 MCP 间顺畅传递每阶段切换前先校验统一做错误处理12.3 迭代式优化适用于成果质量需要逐轮提升的场景例如报告生成。典型流程先生成初稿跑校验找问题修复并重生成局部反复迭代直到满足标准关键不是“多做几轮”而是建立明确的质量标准和停止条件。12.4 上下文感知的工具选择适用于同一目标在不同上下文下要选择不同工具的场景。例如文件存储大文件走云存储协作文档走 Docs/Notion代码文件走 GitHub临时文件走本地这种模式的核心是先有清晰决策树再做工具选择最后向用户解释原因12.5 领域智能嵌入适用于 Skill 除了会调用工具还承担专业判断职责的场景。例如金融合规处理先检查制裁名单判断司法辖区评估风险记录合规决策只有通过后才处理交易这类 Skill 的价值不只是“自动化”而是把领域知识直接融入执行逻辑。十三、常见问题与排查思路13.1 技能上传失败常见原因SKILL.md文件名不正确frontmatter YAML 格式错误name字段不符合 kebab-case 规范这是最基础也最常见的问题通常先检查文件名是否完全正确YAML 是否有---包裹是否有未闭合引号或格式错误13.2 技能不触发最常见原因是description写得太泛。检查重点是否明确写了触发短语是否包含用户真实会说的话是否提及相关文件类型是否把任务范围写得足够具体指南还给了一个很实用的调试方法直接问 Claude“什么时候会用这个 Skill”看它是否只复述了模糊描述再针对缺失信息修改description13.3 技能触发过多如果频繁在不相关场景下被拉起解决办法包括加负向触发条件缩小场景范围明确“只适用于什么不适用于什么”13.4 MCP 连接问题如果 Skill 已经触发但工具调用失败排查顺序应是MCP 是否连接成功鉴权是否过期或权限不足不带 Skill 时单独调用 MCP 能否成功Skill 内写的工具名是否正确且大小写匹配也就是说要先区分是“工具连接有问题”还是“Skill 编排有问题”。13.5 指令没有被很好遵循常见原因有说明过长、过散关键规则埋得太深表达含糊只说原则没有给出可执行检查项指南给出的优化方向非常实用把关键要求放到前面使用Critical、Important等显眼标题把模糊要求改写成可核验清单对关键校验尽量用脚本实现而不是只靠自然语言13.6 上下文过大导致效果下降表现为响应变慢结果变差技能内容难以稳定执行对应优化方式缩短SKILL.md把细节移到references/控制同时启用的 Skill 数量对相关能力打包而不是全量开启十四、文末提供的实用清单14.1 Quick Checklist 的价值文末的快速检查清单很适合拿来做发布前自检。它覆盖了四个阶段开始前开发中上传前上传后其中最值得落实的检查点包括是否已明确 2~3 个用例是否确定所需工具文件夹命名是否规范SKILL.md是否存在且命名准确description是否同时写明做什么、何时用是否已测触发与误触发是否完成功能测试上传后是否继续收集反馈并迭代这说明 Skill 不是“写完就完”而是一个持续维护的产品化资产。14.2 Frontmatter 参考价值文末还给了 frontmatter 的完整示例帮助作者理解最小必填结构是什么可选字段怎么扩展什么内容允许写什么内容禁止写对于新手来说这一部分非常适合当模板起点。14.3 示例技能仓库的重要性官方还给出了公开示例技能仓库与合作伙伴目录。它们的意义不只是“给你看例子”更重要的是帮你理解成熟 Skill 的组织方式帮你参考不同场景的写法帮你在真实案例基础上改造而不是从零空想十五、这份指南传达的核心方法论如果把整份 PDF 压缩成一套方法论我认为可以总结为以下几点。15.1 Skill 不是提示词技巧而是能力工程它关注的不是“怎么把一句 prompt 写得更像魔法”而是怎么把知识、流程、资源、脚本组织成可复用资产怎么让 Claude 在正确时机自动使用它怎么通过结构设计降低上下文负担怎么通过测试和迭代不断提高稳定性15.2 好 Skill 的核心不是“内容多”而是“触发准、步骤清、边界明”一个优秀 Skill 往往具备这些特征description让 Claude 知道何时该用SKILL.md让 Claude 知道具体怎么做references/让 Claude 在需要时获取细节scripts/让高风险校验更确定、更稳定15.3 Skill 的设计应从真实工作流逆推最好的起点不是抽象能力名称而是用户到底想完成什么结果为实现这个结果Claude 应按什么步骤做哪些地方需要专业判断哪些地方必须做校验和容错15.4 Skill 与 MCP 结合后AI 才真正接近“可交付工作流”MCP 解决连接问题Skill 解决执行质量问题。只有二者结合Claude 才能从“有工具可用”进一步走向“会正确使用工具完成复杂工作”。十六、面向实践的落地建议如果你准备真正开始做 Skill可以直接按这条路线推进先选一个高频、重复、容易出错的任务不要一开始贪大求全。写出 2~3 个明确用例包括触发语句、步骤、结果。先把description打磨准确它决定触发效果优先级极高。主说明聚焦核心流程详细资料移入references/。高风险校验尽量脚本化尤其是格式检查、参数校验、质量检查。优先做触发测试和功能测试先保证“能在对的时候触发、触发后能跑通”。关注 undertriggering / overtriggering 信号这两类问题几乎是所有 Skill 迭代的主轴。把 Skill 当产品维护而不是一次性交付收集反馈、修描述、补错误处理、更新版本。十七、总结这份指南最有价值的地方不在于告诉你一个“Skill 文件夹该怎么摆”而在于它清楚定义了 Skill 的产品思维它是一个可复用能力单元它以触发机制为入口以结构化说明为核心以渐进式加载控制复杂度以测试和迭代保障质量以分发和共享实现规模化价值如果只用一句话概括Skill 的本质是把零散经验、专业方法和工具使用策略沉淀成 Claude 可以稳定调用的工作能力。对于个人它意味着更少重复说明对于团队它意味着更一致的 AI 协作方式对于 MCP 生态它意味着从“接上能力”升级到“真正把能力用起来”。如果你后续要基于这份指南自己设计 Skill最值得优先记住的三个关键词是触发准确说明具体迭代持续这三点基本决定了一个 Skill 最终是否真正好用。
