这是一份来自Anthropic官方的Claude Code Skills编写最佳实践指南。它将教你如何通过精心设计的Skills，把通用编程助手转变为领域专家，大幅提升开发效率。内容从基础原则讲到高级模式，适合想要系统化提升AI编程助手能力的开发者。
智能速览
Skills采用三层加载系统，实现按需加载节省上下文空间
编写Skill时要遵循简洁为王原则，只补充AI不知道的内容
根据任务脆弱程度设置不同自由度：数据库迁移需严格，代码评审可宽松
Skill需在多个模型上测试，确保兼容不同推理能力
通过逐步展开架构管理复杂度，避免信息过载
建立反馈循环验证机制，确保关键任务质量
精华内容
理解Skills的工作原理是编写高效Agent的基础。三层加载系统让Claude能够在不撑爆上下文窗口的前提下，随时访问大量专业知识。
核心原则
简洁为王是编写Skill的黄金法则。你的Skill正在与系统提示、对话历史、其他Skills等争夺有限的上下文空间。在写每一段之前，先问自己：它真的需要这段解释吗？能不能假设AI已经懂了？这段话值不值得花50-100个token？
第二个关键是设置合适的自由度。数据库迁移这类脆弱操作需要严格指令，而代码评审则可以给AI更多思考空间。就像悬崖上的独木桥必须严格走，森林里的小路可以有推荐路线，大草原则可以随意探索。
最后，一定要在计划使用的所有模型上测试。在Opus上表现完美的Skill，可能会把Haiku搞糊涂。找到平衡点，或明确标注适用模型。
结构设计
每个Skill必须以YAML头部开始，包含name和description字段。name推荐使用"动词+ing"形式，如processing-pdfs。description要清晰说明做什么和什么时候用，这是Claude判断是否使用的依据。
目录结构要遵循"只深入一层"原则。SKILL.md是前台，其他文件是阅览室，Claude不应该需要多层跳转才能找到内容。推荐结构是将快速示例放在SKILL.md，复杂内容分门别类放到reference目录下。
超过100行的文件建议添加目录，方便Claude快速定位。这就像给AI一张导航图，让它在需要时能迅速找到目标信息。
逐步展开
逐步展开架构分为两个阶段：发现阶段只加载元数据（约50-100个token），让Claude快速判断哪些Skill可能有用；深度加载阶段只有在需要时才读取完整内容。
常见模式包括快速上手+引用，即SKILL.md提供基础示例，高级功能通过链接引用其他文件。按领域拆分模式适合覆盖多个主题的Skill，如将BigQuery按财务、销售、产品等维度分离。
这种设计让Skill几乎可以无限扩展。你可以有几十个Skills，但真正完整加载的永远只有当前用得上的那几个。
工作流设计
复杂任务应该拆解成清晰的步骤和清单。以PDF表单填写为例，可以分为分析表单、创建字段映射、验证映射、填写表单、验证输出五个步骤，每个步骤都有对应的脚本。
对质量要求高的任务，必须建立验证反馈循环。流程是开始→执行→验证→成功则继续，失败则修复再验证。永远不要跳过验证步骤。
可以提供可执行代码作为工具脚本，明确错误处理，并提供依赖验证命令。这样既节省token，又确保可靠性。
评估迭代
开发Skill的最佳实践是先写评测，再写文档。准备3-5个测试场景，观察Claude会在哪里卡住。
迭代过程可以：手动完成任务→记录重复指令→让Claude写Skill→精简→重新测试。这个过程能帮助你发现真正需要优化的地方。
高级做法是编写一个专门给其他Skills打分的Skill。一开始评分可能不高，但按指南改进后效果会明显提升。
编写高效Agentic Skills本质是在简洁与清晰、约束与自由之间找平衡。最好的Skill就像专家直接传授经验。从小开始，持续迭代，把你的经验编码进去，就能把AI编程助手变成团队的秘密武器。你准备好打造第一个Skill了吗？
