目录
文章目录
- 目录
- [Skills 的编写实践](#Skills 的编写实践)
- [The Complete Guide to Building Skills for Claude](#The Complete Guide to Building Skills for Claude)
- [Good Skills vs Bad Skills](#Good Skills vs Bad Skills)
- [Good Skill 原则](#Good Skill 原则)
- [Skills 的质量测试](#Skills 的质量测试)
- [让 Claude 来引导你编写自定义的 Skills](#让 Claude 来引导你编写自定义的 Skills)
Skills 的编写实践
参考文档：https://mp.weixin.qq.com/s/PEisnE_CzFbexPZMSgmgJA
The Complete Guide to Building Skills for Claude
The Complete Guide to Building Skills for Claude（构建 Claude Skills 终极指南）》是 Anthropic 发布了一份 32 页的官方指南，把手教你怎么把自己的工作流程、领域知识封装成 AI 能自动执行的技能包。
Anthropic 总结了三大典型应用场景：
- 文档类型的工作，比如生成前端设计、PPT、合同模板、数据分析报告。
- 工作流自动化，多步骤流程，需要一致的方法论。
- MCP 增强，你已经有 MCP 提供工具访问，Skill 负责封装 "怎么用好这些工具" 的知识。不只是调用 MCP 工具，而是封装了一整套工作流程。
Anthropic 强调 "先测试，再封装"，不要一上来就写 Skill。正确流程：
- 先在对话中反复测试一个具体任务。
- 找到最有效的提示方式。
- 记录 Claude 的成功输出。
- 把这个成功经验提取成 Skill。
这样做的好处：利用 Claude 的上下文学习能力，快速找到最优解，而不是盲目写一堆规则。
Anthropic 在指南中总结了五种经过验证的工作流模式。这些模式可以直接套用到你的场景中。
- 顺序工作流编排：适用于有明确先后顺序的多步骤流程。关键技巧：明确步骤依赖、每步验证、失败时回滚。
bash
# 示例：客户入职流程
Step 1: 创建账户（调用 create_customer）
Step 2: 设置支付方式（等待验证）
Step 3: 创建订阅（使用 Step 1 的 customer_id）
Step 4: 发送欢迎邮件- 多 MCP 协调：一个工作流跨越多个服务。关键技巧：清晰划分阶段、数据在服务间传递、每阶段验证后再进入下一阶段。
bash
# 示例：设计到开发的交接流程。
Phase 1: Figma MCP → 导出设计资源和规格
Phase 2: Drive MCP → 存储资源并生成分享链接
Phase 3: Linear MCP → 创建开发任务并附加资源链接
Phase 4: Slack MCP → 在 #engineering 频道通知团队- 迭代优化：输出质量可以通过多轮迭代提升的场景。关键技巧：明确质量标准、写脚本自动检查、设定停止条件（不能无限迭代）。
bash
# 示例：报告生成。
1. 生成初稿
2. 运行验证脚本，检查问题（缺失章节、格式不一致、数据错误）
3. 针对问题进行修正
4. 重新验证
5. 重复直到质量达标- 上下文感知工具选择：同样的目标，但根据不同上下文选择不同工具。关键技巧：清晰的决策标准、备选方案、向用户解释为什么选择这个工具。
bash
# 示例：智能文件存储
根据文件类型和大小决策：
- >10MB：云存储 MCP
- 协作文档：Notion/Docs MCP
- 代码文件：GitHub MCP
- 临时文件：本地存储- 领域专用智能：在工具调用之外，嵌入领域专业知识。关键技巧：把领域规则编码进 Skill、合规检查先于行动、完整的审计日志。
bash
# 示例：金融合规检查
调用支付 MCP 之前：
1. 检查制裁名单
2. 验证管辖区域是否允许
3. 评估风险等级
4. 记录合规决策
通过后：执行支付
拒绝后：标记审核、创建合规案例Good Skills vs Bad Skills
| 维度 | Good | Bad |
|---|---|---|
| 单一职责原则 | 每个 Skill 只做一件事，且把它做好。例如，可以分解为三个独立的 Skill：query_data、generate_chart、send_email。 | 一个 Skill 试图做太多事，比如"既负责数据查询，又负责图表生成，还负责邮件发送"。 |
| 描述清晰度 | 使用自然语言，描述清晰、具体。明确说明输入、输出和核心功能。例如："根据用户提供的城市名和日期范围，查询并返回该城市的天气数据。" | 描述模糊，充满技术术语，智能体难以理解。例如："一个用于数据处理的工具。" |
| 参数设计 | 参数精简、命名语义化（如 city_name， date_range），并为每个参数提供清晰的描述和示例。明确使用 Skill 需要的参数如何获取，以及参数如何使用。 | 参数过多、命名不规范（如 arg1， p2），缺少详细的注释说明。 |
| 可组合性 | 设计时就考虑到了可组合性，其输出可以作为其他 Skill 的输入，方便构建更复杂的任务流（Workflow），可以尝试通过单一职责完成原子 Skill 的开发，并通过某项具体任务 SOP Skill 完成协调。 | 设计上是"一锤子买卖"，难以与其他 Skill 联动。 |
Good Skill 原则
一个成熟的 Skill 通常具备 3 类特征：
- 声明式触发：通过 name + description 让 Agent 能"路由"到正确能力，而不是靠猜。
- 分层加载：先加载少量元信息，确认需要时再注入详细指令和外部资源，避免上下文爆炸。
- 输出可验收：输出不是一段自由文本，而是符合 spec 的结构化结果，可检查、可回归、可自动化。
一个成熟的 SKILL.md 通常具备以下元素：
- Overview（问题定义）：这个 Skill 解决什么问题？适用什么场景？不适用什么场景？
- Inputs（输入规范）：必填字段是什么？格式是什么？缺失怎么处理？
- Workflow（分步流程）：明确步骤、分支条件、依赖工具，最好能让人类也照着执行一遍。
- Output Spec（输出验收标准）：Output Spec（输出验收标准）
- Guardrails（边界与异常处理）：明确禁止事项、合规要求、遇到冲突信息如何处理、无法完成时如何降级。
- Examples（I/O 示例）：至少给 2-3 个典型样例，覆盖正常、边界、异常。
- Resources（外置依赖）：模板文件、脚本、规则库、引用材料的路径与调用方式。
一个成熟的 Skill 的内容组织应该具备以下特点：
- L1 描述要精准：Skill 的 description 写得太泛，会造成多个技能路由混乱，结果随机。
- L2 要控制指令长度：不是越长越好，考虑 LLM 的注意力机制。L2 只保留流程与规范，而把长期稳定的东西放到 L3 资源里，用工具读取。
- L3 执行要有反馈：例如明确 Script 的输入和输出。
最近 Anthropic 发布了文档《The Complete Guide to Building Skills for Claude（构建 Claude Skills 终极指南）》详细定义了 Agent Skills 的标准格式和最佳实践。
- Micro-skills（微技能）：将大任务拆解为小而专的 Skills。坚持单一职责，让每个 Skill 都像一块积木，小而美，专注于解决一个具体问题，便于日后的复用和组合。
- Naming is Routing（命名即路由）：SKILL.md YAML Frontmatter 就是用来路由的，name 应该要见名知意，而 description 描述中必须包含 WHAT（做什么）和 WHEN（什么时候用）。
- 定边界："别在 X 场景调用我，这时候用 Y Skill"，可以让 Skill 选用更准确。
- 给例子（Few-Shot Prompting）：这是最关键的一点，与其费尽口舌解释，不如直接给出几个清晰的输入输出示例。榜样的力量是无穷的，模型能通过具体例子，秒懂你想要的格式、风格和行为。
- 立规矩（Structured Instructions） ：
- 定角色：给它一个明确的专家人设，比如 "你现在是一个资深的市场分析师"。
- 拆步骤：把任务流程拆解成一步步的具体指令，引导它 "思考"。
- 画红线：明确告诉它 "不能做什么"，防止它天马行空地 "幻觉"。
- 给它 "自我纠错（Self-Correction）" 的能力：在最后结束之前，明确要求 Verify（验证）自己的执行结果，符合要求之后再输出。
- 造接口（Interface Design）：像设计软件 API 一样，明确定义 Skill 的输入参数和输出格式（比如固定输出 JSON 或 Markdown）。这让你的 Skill 可以被其他程序稳定调用和集成。
- 固定输出模板（Output Template）：定义具体的 Markdown 表格格式，或 JSON Schema。
- 用 domain_secrets 管理凭证：不要把密钥写进 Skill 的指令中，用 domain_secrets，LLM 看到的是占位符（如 $API_KEY），实际值由 sidecar 在请求发出前注入。LLM 永远看不到明文。
- 渐进式暴露：SKILL.md 控制在 500 行以内，超过的部分一律拆到 references/ 里。
- 勤复盘（Iterative Refinement）：把 Skills 当作一个产品来迭代。在实际使用中留心那些不尽如人意的 "Bad Case"，然后把它们变成新的规则或反例，补充到你的 Skills 定义里，让它持续进化，越来越聪明、越来越靠谱。
Skills 的质量测试
准备针对性的挑战库和挑战智能体。尤其是面向生产的 Skill，建议维护一套"黑帽子测试用例"（信息不全、诱导、冲突数据、极端输入），每次改动都跑一遍。
让 Claude 来引导你编写自定义的 Skills
这种自定义 Skills 的过程，符合 Spec Coding "先思考后行动" 的思想，即：先详细定义可以执行的需求规范（Specification），然后再推动 AI 进行开发。它的流程包含 "需求分析、技术设计、任务拆解" 的文档编写过程，最后让 AI 根据规范来完成编码。这种一步步的工作流程能保证每一步都有依据，实现从需求到代码的准确转化。
只要你安装了 skill-creator skill 之后，就可以和 Claude Code 聊天让它引导你创建一个自定义的 Skill 了。当然了，一个好用的、符合预期的 Skill 需要反复的打磨。好在你可以使用自然语言让 Claude Code 帮你不断优化。