为 Claude 构建 Skill · 完全指南

Chapter 1

什么是 Skill？

Skill 是一组打包为文件夹的指令，用于教 Claude 处理特定任务或工作流。教 Claude 一次，之后每次都受益。

三级渐进式披露 / Three-Level Progressive Disclosure

Skill 的核心设计是渐进式披露——在最小化 token 消耗的同时保持专业能力。三个级别都围绕 SKILL.md 文件展开：

YAML Frontmatter

SKILL.md 开头 · 始终加载

→

SKILL.md 正文

三大设计原则 / Three Core Principles

🧩

可组合性 Composability

Claude 可同时加载多个 Skill。你的 Skill 应与其他 Skill 良好协作，而非假设自己是唯一可用的能力。

📦

可移植性 Portability

Skill 在 Claude.ai、Claude Code 和 API 上工作方式完全相同。创建一次，到处使用。

🔬

渐进披露 Progressive Disclosure

三级加载系统最小化 token 消耗，同时保持深度专业能力。仅在需要时才加载详细内容。

Skill vs MCP：厨房类比

MCP（连接性）	Skill（知识）
🔧 提供专业厨房——工具、食材、设备	📖 提供食谱——分步指令，创造有价值的成果
将 Claude 连接到你的服务	教 Claude 如何有效使用你的服务
提供实时数据访问和工具调用	捕获工作流和最佳实践
Claude 能做什么	Claude 应该怎么做

Chapter 2

文件结构 / File Structure

每个 Skill 是一个文件夹，唯一必需的文件是 SKILL.md。

your-skill-name/ ├── SKILL.md # 必需 Required - 主 Skill 文件 ├── scripts/ # 可选 Optional - 可执行代码 │ ├── process_data.py │ └── validate.sh ├── references/ # 可选 Optional - 详细文档 │ ├── api-guide.md │ └── examples/ └── assets/ # 可选 Optional - 模板、字体、图标 └── report-template.md

关键规则 Critical Rules：
① 文件必须命名为 SKILL.md（大小写敏感），不接受 SKILL.MD、skill.md 等变体
② 文件夹使用 kebab-case：notion-project-setup ✅ — 不要用空格、下划线、大写
③ Skill 文件夹内禁止放 README.md，所有文档写在 SKILL.md 或 references/ 中
④ Frontmatter 中禁止 XML 尖括号（< >）以及 'claude'、'anthropic' 作为 Skill 名称

核心要素

YAML Frontmatter

Frontmatter 是 Claude 决定是否加载你的 Skill 的依据。这是渐进式披露的第一级，始终存在于系统提示中。

最小必需格式 / Minimal Required Format

YAML

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

完整字段参考 / Complete Fields Reference

YAML

---
name: skill-name               # 必填 Required: kebab-case
description: ...              # 必填 Required: ≤1024 字符
license: MIT                  # 可选 Optional
compatibility: ...           # 可选 Optional: ≤500 字符
allowed-tools: "Bash(python:*) WebFetch"
metadata:                      # 可选 Optional: 自定义键值对
  author: YourCompany
  version: 1.0.0
  mcp-server: server-name
  tags: [automation, productivity]
---

最关键的字段

编写 Description

Description 决定了 Skill 的触发时机。结构公式：[做什么] + [何时使用] + [关键能力]

中英文示例对比 / Examples Comparison

✅ Good Descriptions

# Specific and actionable
description: Analyzes Figma design files and generates developer
  handoff documentation. Use when user uploads .fig files,
  asks for "design specs", "component documentation", or
  "design-to-code handoff".

# Clear trigger phrases
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".

❌ Bad Descriptions

# Too vague — 太模糊
description: Helps with projects.

# Missing triggers — 缺少触发条件
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers — 太技术化
description: Implements the Project entity model with hierarchical relationships.

✅ 好的描述

# 具体且可操作
description: 分析 Figma 设计文件并生成开发交接文档。
  当用户上传 .fig 文件、要求「设计规格」、
 「组件文档」或「设计转代码交接」时使用。

# 包含触发短语
description: 管理 Linear 项目工作流，包括冲刺规划、
  任务创建和状态跟踪。当用户提及「冲刺」、
 「Linear 任务」、「项目规划」或「创建工单」时使用。

❌ 差的描述

# 太模糊
description: 帮助处理项目。

# 缺少触发条件
description: 创建复杂的多页文档系统。

💡 自定义实战示例 / Custom Practical Examples

以下是根据指南原则编写的额外示例，展示不同场景的 description：

✅ Good

description: Generates weekly team status
  reports from Slack conversations and
  Jira tickets. Use when user says
  "weekly report", "team status",
  "standup summary", or "week recap".
  Outputs formatted Markdown or DOCX.

❌ Bad

description: Makes reports from
  team data.

✅ Good

description: 自动化代码审查工作流。
  从 GitHub PR 获取 diff，运行静态分析，
  生成结构化审查意见。当用户说「审查 PR」、
 「代码审查」、「review 这个 PR」时使用。
  支持 Python、TypeScript、Go。

❌ Bad

description: 帮助审查代码质量。

✅ Good

description: End-to-end customer onboarding
  for PayFlow. Handles account creation,
  payment setup, and subscription management.
  Use when user says "onboard new customer",
  "set up subscription", or "create PayFlow
  account". Do NOT use for general billing
  queries.

❌ Bad

description: PayFlow customer operations
  and payment processing interface.

编写指南

编写 Skill 指令 / Writing Instructions

Frontmatter 之后的 Markdown 正文是 Skill 的实际指令。以下是推荐结构和对比示例。

指令编写对比 / Good vs Bad Instructions

✅ 具体可操作 Specific

Run `python scripts/validate.py
  --input {filename}` to check
  data format.

If validation fails, common issues:
- Missing required fields
  (add them to the CSV)
- Invalid date formats
  (use YYYY-MM-DD)

❌ 模糊笼统 Vague

Validate the data before proceeding.

✅ 明确验证条件 Explicit

CRITICAL: Before calling create_project,
verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

❌ 语意不清 Ambiguous

Make sure to validate things properly.

高级技巧：对于关键验证，考虑在 scripts/ 中捆绑一个脚本以编程方式执行检查，而不是依赖语言指令。代码是确定性的，语言解释不是。

Chapter 5

五大设计模式 / Five Patterns

这些模式来自早期采用者和内部团队。点击展开查看每个模式的详细示例（中英双语）。

顺序工作流编排 Sequential Workflow

多步骤特定顺序 ▼

适用于需要按特定顺序执行的多步骤流程。关键技术：明确的步骤顺序、步骤间依赖、每阶段验证、失败回滚。

# Workflow: Onboard New Customer

# Step 1: Create Account
Call MCP tool: create_customer
Parameters: name, email, company

# Step 2: Setup Payment
Call MCP tool: setup_payment_method
Wait for: payment method verification

# Step 3: Create Subscription
Call MCP tool: create_subscription
Parameters: plan_id, customer_id (from Step 1)

# Step 4: Send Welcome Email
Call MCP tool: send_email
Template: welcome_email_template

# 工作流：新客户入职

# 步骤 1：创建账户
调用 MCP 工具：create_customer
参数：name, email, company

# 步骤 2：设置支付
调用 MCP 工具：setup_payment_method
等待：支付方式验证

# 步骤 3：创建订阅
调用 MCP 工具：create_subscription
参数：plan_id, customer_id（来自步骤 1）

# 步骤 4：发送欢迎邮件
调用 MCP 工具：send_email
模板：welcome_email_template

多 MCP 协调 Multi-MCP Coordination

跨多个服务 ▼

工作流跨越多个服务时使用。关键技术：阶段分离、MCP 间数据传递、进入下一阶段前验证、集中式错误处理。

# Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications

# Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets, generate shareable links

# Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks

# Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering

迭代精炼 Iterative Refinement

质量随迭代改善 ▼

当输出质量可通过迭代改善时使用。关键技术：明确质量标准、验证脚本、知道何时停止。

# Initial Draft  →  # Quality Check  →  # Refinement Loop  →  # Finalization
Fetch data          Run validate.py      Fix each issue          Apply formatting
Generate draft      Identify issues      Regenerate sections     Generate summary
Save to temp        List problems        Re-validate             Save final version
                                         Repeat until threshold

上下文感知工具选择 Context-Aware Tool Selection

同目标不同工具 ▼

相同结果但根据上下文选择不同工具。关键技术：决策标准、备用选项、选择透明化。

# Decision Tree: Smart File Storage
Large files (>10MB)    → Cloud Storage MCP
Collaborative docs     → Notion/Docs MCP
Code files             → GitHub MCP
Temporary files        → Local storage

# Then: explain the choice to user

领域特定智能 Domain-Specific Intelligence

嵌入专业知识 ▼

在工具访问之外添加专业领域知识。关键技术：领域知识嵌入逻辑、操作前先合规、全面文档记录。

# Payment Processing with Compliance
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists  / 检查制裁名单
   - Verify jurisdiction    / 验证管辖权
   - Assess risk level      / 评估风险等级
3. IF passed → process payment
   ELSE → flag for review, create compliance case
4. Generate audit report    / 生成审计报告

Chapter 3

测试与迭代 / Testing & Iteration

有效的 Skill 测试覆盖三个维度：触发、功能、性能。

🎯

触发测试 Trigger Tests

确保 Skill 在正确时机加载。测试明显任务、改写请求、以及不应触发的无关主题。目标：90%+ 触发率。

⚙️

功能测试 Functional Tests

验证输出正确性：API 调用成功、错误处理有效、边缘情况覆盖。

📊

性能对比 Performance

证明 Skill 的改进：对比有无 Skill 的对话轮次、token 消耗、失败率。

性能对比示例 / Performance Comparison

指标 Metric	无 Skill Without	有 Skill With
交互方式	每次手动提供指令	自动执行工作流
对话轮次	15 次来回	仅 2 个澄清问题
失败 API 调用	3 次需重试	0 次
Token 消耗	12,000	6,000 ↓50%

迭代建议：先在单个任务上迭代直到 Claude 成功，然后将获胜方法提取为 Skill。这利用了 Claude 的上下文学习，比广泛测试提供更快的信号。

Chapter 5

故障排除 / Troubleshooting

常见问题的诊断和解决方案速查。

🔴 Skill 无法上传

错误信息	原因	解决方案
`Could not find SKILL.md`	文件名不精确	重命名为 `SKILL.md`（大小写敏感）
`Invalid frontmatter`	YAML 格式错误	确保有 `---` 分隔符，引号正确闭合
`Invalid skill name`	名称含空格或大写	使用 kebab-case: `my-cool-skill`

🟡 触发问题

触发不足 Under-triggering

症状：Skill 从不自动加载
原因：description 太模糊
修复：添加具体触发短语和关键词

调试：问 Claude「你会在什么时候使用
[skill 名称] Skill？」

过度触发 Over-triggering

症状：无关查询时也加载
原因：description 太宽泛
修复：
  ① 添加负面触发条件（Do NOT use for...）
  ② 缩小范围（"PDF 法律文档" 而非"文档"）
  ③ 明确排除（不用于一般财务查询）

🟠 指令未被遵循

指令太冗长

保持简洁，用要点列表。将详细参考移到 references/ 目录。SKILL.md 保持 5,000 词以内。

关键指令被埋没

放在顶部，用 ## Critical 标题。必要时重复关键点。

语言模糊

用代码验证替代语言指令。「确保正确验证」→ 具体列出每个验证条件。

模型「懒惰」

添加鼓励语：「花时间彻底完成」「质量比速度更重要」「不要跳过验证步骤」。在用户提示词中比在 SKILL.md 中更有效。

附录 A

快速检查清单 / Quick Checklist

构建 Skill 的完整检查项，确保不遗漏任何关键步骤。

🏁 开始之前

确定了 2-3 个具体用例 / Identified 2-3 concrete use cases
已识别所需工具（内置或 MCP）/ Tools identified
已审阅本指南和示例 Skill / Reviewed guide and examples
已规划文件夹结构 / Planned folder structure

🔨 开发期间

文件夹使用 kebab-case 命名
SKILL.md 文件存在（拼写精确）
YAML frontmatter 有 --- 分隔符
name：kebab-case，无空格，无大写
description 包含「做什么」和「何时使用」
无 XML 标签（< >）
指令清晰且可操作
包含错误处理
提供了示例
参考资料链接清晰

📤 上传之前

已测试明显任务的触发
已测试改写请求的触发
已验证不会在无关主题上触发
功能测试通过
工具集成正常（如适用）
已压缩为 .zip 文件

🚀 上传之后

在真实对话中测试
监控触发不足/过度触发
收集用户反馈
迭代描述和指令
更新元数据中的版本号

什么是 Skill？

三级渐进式披露 / Three-Level Progressive Disclosure

三大设计原则 / Three Core Principles

可组合性 Composability

可移植性 Portability

渐进披露 Progressive Disclosure

Skill vs MCP：厨房类比

文件结构 / File Structure

YAML Frontmatter

最小必需格式 / Minimal Required Format

完整字段参考 / Complete Fields Reference

编写 Description

中英文示例对比 / Examples Comparison

✅ Good Descriptions

❌ Bad Descriptions

✅ 好的描述

❌ 差的描述

💡 自定义实战示例 / Custom Practical Examples

编写 Skill 指令 / Writing Instructions

推荐模板 / Recommended Template

指令编写对比 / Good vs Bad Instructions

五大设计模式 / Five Patterns

顺序工作流编排 Sequential Workflow

多 MCP 协调 Multi-MCP Coordination

迭代精炼 Iterative Refinement

上下文感知工具选择 Context-Aware Tool Selection

领域特定智能 Domain-Specific Intelligence

测试与迭代 / Testing & Iteration

触发测试 Trigger Tests

功能测试 Functional Tests

性能对比 Performance

性能对比示例 / Performance Comparison

故障排除 / Troubleshooting

🔴 Skill 无法上传

🟡 触发问题

🟠 指令未被遵循

指令太冗长

关键指令被埋没

语言模糊

模型「懒惰」

快速检查清单 / Quick Checklist

🏁 开始之前

🔨 开发期间

📤 上传之前

🚀 上传之后