构建 Claude Skill 标准操作手册（SOP）

一、核心心智模型

1.1 Prompt 与 Skill 的本质区别

核心洞察：Skill 的本质是将"人在每次对话中重复解释的知识"固化为一套可被机器自动检索、加载和执行的指令包。

1.2 三层 Progressive Disclosure（渐进式信息披露）机制

这是整个 Skill 系统的核心架构——三级加载系统：

┌─────────────────────────────────────────────────────┐│  Level 1: YAML 前置元数据                              ││  • 始终驻留在 Claude 的 System Prompt 中                ││  • 仅提供"做什么 + 何时触发"的概要信息                    ││  • 让 Claude 知道何时该用，但不消耗大量上下文              ││  • description 字段上限 1024 字符                      │├─────────────────────────────────────────────────────┤│  Level 2: SKILL.md 正文                               ││  • 当 Claude 判定该 Skill 与当前任务相关时才加载          ││  • 包含完整指令、步骤、示例、故障排除                      ││  • 建议控制在 5,000 词以下                             │├─────────────────────────────────────────────────────┤│  Level 3: 关联文件（references/ 等）                    ││  • Claude 按需自行导航和发现                            ││  • 存放详细文档、API 参考、补充示例                       ││  • 仅在 Claude 认为必要时才读取                         │└─────────────────────────────────────────────────────┘

设计意图：最小化 Token 消耗的同时保持专业化能力。

Claude 判定 Skill "与任务相关"的具体匹配逻辑未公开。在实践中这意味着 description 字段需要反复调试。Debug 方法：直接问 Claude “When would you use the [skill name] skill?”，它会引用 description 回复，据此判断缺失了什么。

1.3 MCP 与 Skill 的分层关系

厨房类比：MCP 提供专业厨房（工具、食材、设备的访问权限），Skill 提供食谱（如何创造有价值成果的分步说明）。

如果你已经有一个可工作的 MCP 服务器，硬件部分就完成了。Skill 是叠加在其上的知识层——捕捉你已知的工作流和最佳实践，让 Claude 持续应用它们。

MCP + Skill 结合前后的效果对比：

1.4 Problem-First vs. Tool-First 的设计取向

类比：像去 Home Depot——带着问题进去（“我需要修橱柜”），店员引导你找到工具；或者挑一把新电钻，问怎么用它。

• Problem-First（问题优先）：用户说"我需要设置一个项目工作区" → Skill 编排正确的 MCP 调用序列。用户描述结果，Skill 处理工具。
• Tool-First（工具优先）：用户说"我已连接 Notion MCP" → Skill 教会 Claude 最佳工作流和实践。用户拥有访问权，Skill 提供专业知识。

大多数 Skill 偏向一个方向。明确哪种框架适合你的用例，有助于选择正确的工作流模式。

二、标准化构建工作流（SOP）

需求定义 ──→ 结构设计 ──→ 编写 SKILL.md ──→ 测试验证 ──→ 分发部署  (Step 1)    (Step 2)     (Step 3)         (Step 4)      (Step 5)

Step 1: 需求定义

在写任何代码之前，先确定 2-3 个具体用例。

用例定义模板：

用例：[名称]触发条件：用户说出 [具体短语]步骤：  1. [第一步]  2. [第二步]  ...结果：[可验证的最终产出]

示例——项目 Sprint 规划：

用例：Project Sprint Planning触发条件：用户说 "help me plan this sprint" 或 "create sprint tasks"步骤：  1. 从 Linear（通过 MCP）获取当前项目状态  2. 分析团队速度和容量  3. 建议任务优先级排序  4. 在 Linear 中创建带有适当标签和估算的任务结果：完整的 sprint 规划及已创建的任务

自我审查清单：

• 用户想要完成什么？
• 这需要哪些多步骤工作流？
• 需要哪些工具（内置能力 或 MCP）？
• 应该嵌入哪些领域知识或最佳实践？

输出标准：

• [ ] 确定了 2-3 个明确用例
• [ ] 每个用例有可验证的触发条件和预期结果
• [ ] 工具需求已明确分类（内置能力 / MCP）
• [ ] 用例已归属类别

三大用例类别

Step 2: 结构设计

标准文件夹结构：

your-skill-name/          # kebab-case 命名├── SKILL.md              # 必需 —— 主 Skill 文件├── scripts/              # 可选 —— 可执行代码├── references/           # 可选 —— 按需加载的文档└── assets/               # 可选 —— 模板、字体、图标等

内容分配原则： SKILL.md 聚焦核心指令，详细文档放 references/ 并链接引用（遵循 Progressive Disclosure）。

命名规则：

Skill 文件夹内部禁止放 README.md（所有文档在 SKILL.md 或 references/ 中）。通过 GitHub 分发时，仓库级别需要 README 面向人类访客。

输出标准：

• [ ] 文件夹结构已规划
• [ ] 文件夹名称符合 kebab-case
• [ ] 内容分级策略已确定（Level 1/2/3 各放什么）
• [ ] 如需 MCP，已在设计中考量 MCP 工具调用序列

Step 3: 编写 SKILL.md

这是整个构建流程的核心环节。

3A. 先写 YAML 前置元数据

YAML 前置元数据是 Claude 决定是否加载 Skill 的唯一依据。

最小格式：

---name: your-skill-namedescription: What it does. Use when user asks to [specific phrases].---

description 字段公式：

[做什么] + [何时使用] + [关键能力/触发短语]

description 直接决定了 Level 1 Progressive Disclosure —— 只提供足够信息让 Claude 知道何时该用，而不加载全部上下文。

description 判定标准：

• 同时包含"做什么"和"何时触发"
• 触发短语要具体且可操作（用户实际会说的话）
• 如相关，提及文件类型
• 不超过 1024 字符
• 不包含 XML 标签 < >

好与差的示范：

# ✅ 好 —— 具体且可操作description: Analyzes Figma design files and generates developer handoffdocumentation. Use when user uploads .fig files, asks for "design specs","component documentation", or "design-to-code handoff".# ✅ 好 —— 包含触发短语description: Manages Linear project workflows including sprint planning,task creation, and status tracking. Use when user mentions "sprint","Linear tasks", "project planning", or asks to "create tickets".# ✅ 好 —— 清晰的价值主张description: End-to-end customer onboarding workflow for PayFlow. Handlesaccount creation, payment setup, and subscription management. Use whenuser says "onboard new customer", "set up subscription", or "createPayFlow account".# ❌ 差 —— 太模糊description: Helps with projects.# ❌ 差 —— 缺少触发条件description: Creates sophisticated multi-page documentation systems.# ❌ 差 —— 太技术化，没有用户触发description: Implements the Project entity model with hierarchicalrelationships.

质量自检：

• [ ] 是否太泛泛？（“Helps with projects” 不通过）
• [ ] 是否包含用户实际会说的触发短语？
• [ ] 是否过度技术化而缺少用户语言？

可选字段：

版本号建议使用 version: 1.0.0 格式，但未强制要求 SemVer。

安全红线（不可违反）：

• ❌ 前置元数据中禁止 < > 字符 —— 前置元数据出现在 System Prompt 中，恶意内容可能注入指令
• ❌ Skill 名称禁止含 claude 或 anthropic —— 保留字

3B. 编写主指令正文

标准正文结构：

---name: your-skilldescription: [...]---# Your Skill Name## Instructions### Step 1: [First Major Step]Clear explanation of what happens.Example:```bashpython scripts/fetch_data.py --project-id PROJECT_ID```Expected output: [describe what success looks like](Add more steps as needed)## Examples### Example 1: [common scenario]User says: "Set up a new marketing campaign"Actions:1. Fetch existing campaigns via MCP2. Create new campaign with provided parametersResult: Campaign created with confirmation link(Add more examples as needed)## Troubleshooting### Error: [Common error message]Cause: [Why it happens]Solution: [How to fix](Add more error cases as needed)

指令编写原则：

1. 具体且可操作

   • ✅ Run python scripts/validate.py --input {filename} to check data format. If validation fails, common issues include: - Missing required fields (add them to the CSV) - Invalid date formats (use YYYY-MM-DD)
   • ❌ Validate the data before proceeding.

2. 包含错误处理 —— 对每种可预见的错误，提供：错误消息 → 原因 → 解决方案

3. 显式引用捆绑资源

   • ✅ consult references/api-patterns.md for: - Rate limiting guidance - Pagination patterns - Error codes and handling

4. 关键指令放顶部，用 ## Important 或 ## Critical 标题标注

5. 关键验证优先用脚本而非语言指令 —— 代码是确定性的，语言解释不是。参见 Office skills 的实践模式。

6. SKILL.md 正文控制在 5,000 词以下 —— 超出时应将详细文档移至 references/

关于模型"惰性"：

可添加明确鼓励：

code

## Performance Notes- Take your time to do this thoroughly- Quality is more important than speed- Do not skip validation steps

注意：将此添加到用户提示中比放在 SKILL.md 中更有效。

输出标准：

• [ ] YAML 前置元数据：name kebab-case，description 含 WHAT + WHEN
• [ ] 无 XML 标签，名称不含保留字
• [ ] 正文含 Instructions / Examples / Troubleshooting 三段
• [ ] 指令具体可操作
• [ ] 错误处理已覆盖可预见的常见错误
• [ ] references/ 路径引用清晰
• [ ] SKILL.md 正文 ≤ 5,000 词

Step 4: 测试验证

三种测试方法

选择与 Skill 的质量要求和可见度匹配的方法。小团队内部使用的 Skill 与部署给数千企业用户的 Skill，测试需求不同。

迭代策略

先在单个高难度任务上迭代直到 Claude 成功，再将成功方案提取为 Skill，最后扩展到多测试用例。这比广泛测试提供更快的反馈信号。

触发测试

量化目标： 在 90% 的相关查询上自动触发。运行 10-20 个应触发的测试查询，追踪自动加载 vs. 需要显式调用的比例。

注意： 这是期望目标而非精确阈值——力求严谨但要接受评估中有感性判断的成分。更稳健的评估工具仍在开发中。

Debug 方法： 问 Claude “When would you use the [skill name] skill?”，据此调整 description。

功能测试

• 有效输出生成
• API 调用成功
• 错误处理正常工作
• 边界情况已覆盖

量化目标： 每次工作流 0 次 API 调用失败。监控 MCP 服务器日志，追踪重试率和错误代码。

性能对比

质性指标：

• 用户不需要提示 Claude 下一步做什么 —— 测试期间记录需要重定向或澄清的频率
• 工作流完成无需用户纠正 —— 同请求运行 3-5 次，比较输出结构一致性
• 跨会话结果一致 —— 新用户能否以最少指导在第一次尝试时完成任务

迭代方向

输出标准：

• [ ] 触发测试通过：明显任务 + 同义表述触发，不相关主题不触发
• [ ] 功能测试通过：核心工作流可无错完成
• [ ] 性能对比：Token 消耗和工具调用次数优于无 Skill 基线
• [ ] 同请求运行 3-5 次，输出结构一致

Step 5: 分发部署

分发路径

API 使用前提：需要 Code Execution Tool Beta 版，它提供了 Skill 运行所需的安全环境。

API vs. Claude.ai 选择：

开放标准： Agent Skills 已作为开放标准发布——同一 Skill 在 Claude 和其他 AI 平台上都应该能正常工作。部分 Skill 设计来利用特定平台的能力，可在 compatibility 字段中注明。

GitHub 分发

1. 托管在 GitHub：公开仓库 + 清晰的 README（面向人类访客）+ 安装说明 + 示例截图
2. 在 MCP 文档中链接 Skill + 解释结合价值 + 提供快速入门指南
3. 提供安装指南：git clone 或下载 ZIP → 上传 Claude → 启用 → 测试

Skill 定位原则

• 聚焦结果而非功能：✅ “The ProjectHub skill enables teams to set up complete project workspaces in seconds” / ❌ “The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions”
• 讲好 MCP + Skill 的故事：“Our MCP server gives Claude access to your Linear projects. Our skills teach Claude your team’s sprint planning workflow. Together, they enable AI-powered project management.”

发布检查清单

三、设计原则与避坑指南

3.1 五条核心原则

原则一：Progressive Disclosure

严格遵循 Level 1 (YAML) → Level 2 (SKILL.md) → Level 3 (references/) 的信息分级。若把所有内容塞进 SKILL.md 会导致上下文膨胀和响应变慢。

原则二：Composability（可组合性）

Skill 不能假设自己是唯一的——必须与其他 Skill 共存。Claude 可同时加载多个 Skill。如果同时启用的 Skill 超过 20-50 个，应考虑选择性启用或使用 Skill “packs” 打包相关能力。多 Skill 同时触发时的优先级机制尚未公开。

原则三：Portability（可移植性）

Skill 要在 Claude.ai、Claude Code、API 三个平台上行为一致。前提是环境需支持 Skill 声明的依赖。由于 Agent Skills 已是开放标准，理论上可跨 AI 平台使用，平台特定依赖在 compatibility 字段中注明。

原则四：前置元数据安全

YAML 前置元数据中禁止 < > 字符——前置元数据会出现在 Claude System Prompt 中，恶意内容可能注入指令。Skill 名称禁止含 claude 或 anthropic。违反会导致上传被拒绝（“Invalid frontmatter” / “Invalid skill name”）。

原则五：SKILL.md 精确命名

文件必须精确命名为 SKILL.md（大小写敏感），不接受任何变体。违反直接报错 “Could not find SKILL.md in uploaded folder”。

3.2 常见错误速查

四、五种工作流模式

这些模式来自早期采用者和内部团队的 Skill 实践经验——是行之有效的常见方法，非规定性模板。

Pattern 1: Sequential Workflow Orchestration（顺序工作流编排）

适用场景： 用户需要按特定顺序执行的多步骤流程。

示例——客户入驻流程： Step 1 创建账户 → Step 2 设置支付 → Step 3 创建订阅（依赖 Step 1 的 customer_id）→ Step 4 发送欢迎邮件

关键技术：

• 显式的步骤排序
• 步骤间的依赖关系
• 每个阶段的验证
• 失败时的回滚说明

Pattern 2: Multi-MCP Coordination（多 MCP 协调）

适用场景： 工作流跨越多个外部服务。

示例——设计到开发交接： Phase 1 Figma MCP 导出设计资源 → Phase 2 Drive MCP 存储并生成分享链接 → Phase 3 Linear MCP 创建开发任务 → Phase 4 Slack MCP 通知工程团队

关键技术：

• 清晰的阶段分离
• MCP 之间的数据传递
• 进入下一阶段前的验证
• 集中式错误处理

Pattern 3: Iterative Refinement（迭代精炼）

适用场景： 输出质量依赖反复打磨。

示例——报告生成： Initial Draft → Quality Check（运行 scripts/check_report.py 检查缺失章节/格式一致性/数据错误）→ Refinement Loop（逐项修复 → 重新验证 → 循环直到质量达标）→ Finalization

关键技术：

• 明确的质量标准
• 迭代改进
• 验证脚本
• 知道何时停止迭代

Pattern 4: Context-Aware Tool Selection（上下文感知工具选择）

适用场景： 同一目标，不同上下文用不同工具。

示例——智能文件存储决策树： 检查文件类型和大小 → 大文件（>10MB）用云存储 MCP / 协作文档用 Notion MCP / 代码文件用 GitHub MCP / 临时文件用本地存储 → 向用户解释选择原因

关键技术：

• 清晰的决策标准
• 回退选项
• 对选择的透明性

Pattern 5: Domain-Specific Intelligence（领域特定智能）

适用场景： 需要在工具访问之上嵌入专业领域判断逻辑。

示例——金融合规支付处理： 交易前合规检查（制裁名单 → 司法管辖区 → 风险级别）→ 通过则处理并应用欺诈检测 / 不通过则标记审查并创建合规案件 → 生成完整审计追踪

关键技术：

• 领域专业知识嵌入判断逻辑
• 操作前先合规/检查
• 全面文档记录
• 清晰的治理规则

模式速选表

五、可复用模板

5.1 文件夹模板

your-skill-name/               # ← kebab-case├── SKILL.md                   # 必需，大小写敏感├── scripts/                   # 可选，可执行代码（Python, Bash 等）│   ├── process_data.py│   └── validate.sh├── references/                # 可选，按需加载的文档│   ├── api-guide.md│   └── examples/└── assets/                    # 可选，模板、字体、图标等    └── report-template.md

5.2 SKILL.md 内容模板

将 [中括号内容] 替换为你的具体信息：

---name: [your-skill-name]description: >-  [What it does - 1 sentence].  Use when user [trigger conditions - specific phrases users say].  [Key capabilities - optional additional detail].license: [MIT or Apache-2.0, optional]compatibility: [environment requirements, optional]metadata:  author: [Your Name / Company]  version: 1.0.0  mcp-server: [server-name, if applicable]---# [Skill Display Name]## Instructions### Step 1: [First Major Step]Clear explanation of what happens in this step.```bashpython scripts/[script-name].py --param VALUE```Expected output: [describe what success looks like]### Step 2: [Second Major Step][Clear explanation...]<!-- Add more steps as needed -->## Examples### Example 1: [Common Scenario]**User says:** "[actual user phrase]"**Actions:**1. [Action 1 - e.g., Fetch existing data via MCP]2. [Action 2 - e.g., Process and transform]3. [Action 3 - e.g., Create output]**Result:** [Verifiable outcome]### Example 2: [Another Scenario]**User says:** "[actual user phrase]"**Actions:**1. [Action 1]2. [Action 2]**Result:** [Verifiable outcome]<!-- Add more examples as needed -->## Troubleshooting### Error: [Common Error Message]**Cause:** [Why it happens]**Solution:**1. [Step to fix]2. [Step to fix]### Error: [Another Common Error]**Cause:** [Why it happens]**Solution:** [How to fix]<!-- Add more error cases as needed -->

5.3 YAML 前置元数据速查表

# ===== 必需字段 =====---name: skill-name-in-kebab-case   # 必须与文件夹名一致description: >-                  # ≤1024 字符，无 <>，含"做什么+何时用"  [What it does].  Use when user [trigger conditions].---# ===== 全部可选字段 =====---name: skill-namedescription: >-  [required description]license: MIT                     # MIT | Apache-2.0 | ...compatibility: >-                # 1-500 字符  [intended product, required system packages, network access, etc.]allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 限制工具访问metadata:                        # 自定义键值对  author: Company Name  version: 1.0.0  mcp-server: server-name  category: productivity  tags: [project-management, automation]  documentation: https://example.com/docs  support: support@example.com---# ===== 安全红线 =====# 禁止: <> XML 尖括号（出现在 System Prompt 中有注入风险）# 禁止: 名称含 "claude" 或 "anthropic"（保留字）# 允许: 所有标准 YAML 类型（字符串、数字、布尔、列表、对象）