内容主要来自 anthropic网站：

https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en

一、先说结论：Skill 不是“提示词库”，而是“流程工程”
官方对 Skill 的定义非常明确：

Skill 是一组指令——被打包成一个简单文件夹——用来教 Claude 如何处理特定任务或工作流。这是你定制 Claude 最强大的方式之一：你只需教一次，以后每次都能受益。

重点在三点：

Skill 是文件夹，不是一段提示词，里面至少有 SKILL.md，还可以有脚本、参考文档、模板等。
解决的是“重复流程”的问题，每次都重新解释偏好、流程、规范，非常浪费。Skill 把这些变成一次配置、长期复用。
标志从“提示词工程”到“流程工程”的范式跃迁，真正有竞争力的不是谁的 Prompt 写得更花，而是谁能把业务流程沉淀成可复用的知识资产，交给 Claude 稳定执行。

二、Skill 是什么？一个文件夹的结构
官方给的结构非常简单：

your-skill-name/
├── SKILL.md # 必需 - 主技能文件（YAML 头 + Markdown 指令）
├── scripts/ # 可选 - 可执行代码（Python、Bash 等）
│ ├── process_data.py
│ └── validate.sh
├── references/ # 可选 - 按需加载的参考文档
│ ├── api-guide.md
│ └── examples/
└── assets/ # 可选 - 模板、字体、图标等

└── report-template.md

核心只有一个：SKILL.md 是必须的，其他都是可选。

关键命名与结构规则（硬性）
官方给了一堆“必须/禁止”的规则，踩坑重灾区：

SKILL.md 命名

必须精确为 SKILL.md，区分大小写。

SKILL.MD、skill.md 等任何变体都不行。

Skill 文件夹命名

只能用 kebab-case：notion-project-setup

禁止：Notion Project Setup（空格）、notion_project_setup（下划线）、NotionProjectSetup（大写）

不要在 Skill 文件夹里放 README.md

所有文档都放在 SKILL.md或 references/ 里。

如果是通过 GitHub 分发，仓库根目录可以有 README，但那是给人看的，不是给 Claude 的。

三、三大核心设计理念：渐进式披露 / 可组合 / 可移植
官方把 Skill 的设计理念总结成三条，这是整份指南的灵魂：

  1. 渐进式披露（Progressive Disclosure）
    Skill 用三层系统组织内容，避免把所有东西塞进上下文：

1.第一层：YAML 头（始终加载）

  • 每次都进 Claude 的系统提示。
  • 只放最关键的信息：这个 Skill 叫什么、什么时候该用它。
  • 控制字数，因为这部分一直占上下文。

2.第二层：SKILL.md 正文（相关时才加载）

  • 当 Claude 判断当前任务跟这个 Skill 有关，才加载完整指令。
  • 这里放工作流、步骤、注意事项。

3.第三层：链接文件（按需查阅）

  • references/、scripts/、assets/ 里的文件。
  • Claude 只在真正需要时去读。

好处：既省 token，又保留专业深度。

类比一下：普通提示词工程：把所有资料都塞进 system prompt，结果又贵又容易忘。

Skill：像有经验的医生，平时只看症状，遇到罕见病例知道去哪里查详细资料。

  1. 可组合性（Composability）
    Claude 可以同时加载多个 Skill。

你的 Skill 要能和其他 Skill 协作，而不是假设“只有我存在”。
设计时要考虑：如果还有别的 Skill 也在工作，会不会打架？

  1. 可移植性（Portability）
    Skill 在 Claude.ai、Claude Code、API 上的工作方式完全一样。

一次创建，只要环境支持依赖，就可以到处跑，无需改代码。
四、面向 MCP 构建者：Skill 是“食谱”，MCP 是“厨房”
如果你已经在做 MCP 集成，官方的比喻非常值得记住：

MCP：专业厨房提供工具、食材、设备（刀具、灶台、食材），Claude 能“接触”到一切。
Skill：食谱告诉 Claude 用这些工具，按什么顺序，做出什么东西。
没有 Skill 时，常见问题：

用户连了 MCP，但不知道下一步该做什么；
大量工单问“怎么用你的集成做 X”；
每次对话从头开始，结果不一致；
用户骂 MCP 不好用，其实缺的是工作流指导。
有了 Skill 之后：

预构建的工作流在需要时自动激活；
工具调用稳定可靠；
最佳实践被嵌入每次交互；
新用户学习成本大幅降低。
五、从用例出发：三类高频场景 & 成功指标
官方建议：写代码前，先定义 2–3 个具体用例。

  1. 三类常见用例类别
    官方观察到的三类高频场景：

类别

适合场景

典型示例

关键技术

类别 1：文档与资产创建

需要一致、高质量输出（文档、前端、PPT、代码等）

frontend-design Skill：生成生产级前端界面

嵌入风格指南和品牌规范；模板结构；完成前质量检查清单；无需外部工具，只用 Claude 内置能力

类别 2：工作流自动化

多步骤流程，需要一致方法论，可能跨多个 MCP

skill-creator Skill：引导用户创建新 Skill

带验证节点的分步工作流；常见结构模板；内置审查和改进建议；迭代优化循环

类别 3：MCP 增强

为 MCP 工具访问加工作流引导

sentry-code-review Skill：用 Sentry 数据分析 PR bug

按顺序协调多个 MCP 调用；嵌入领域专业知识；提供用户本需手动指定的上下文；常见 MCP 错误处理

  1. 定义“成功”的标准：定量 + 定性
    官方给了很实用的基准（注意：是参考目标，不是硬门槛）：

定量指标：

90% 的相关查询中自动触发
测试 10–20 个应该触发的查询，统计自动加载比例。
在 X 次工具调用内完成工作流
对比开启 / 未开启 Skill 的相同任务，统计工具调用次数和总 token。
每个工作流 0 次 API 调用失败
监控 MCP 服务器日志，追踪重试率和错误码。
定性指标：

用户不需要提示 Claude 下一步做什么；
工作流无需用户纠正即可完成；
跨会话结果一致（新用户也能一次成功）。
六、YAML 头：Skill 的“门面”，决定会不会被触发
官方反复强调：YAML 头是 Claude 决定是否加载 Skill 的唯一依据，写好它是最重要的一步。

  1. 最简必需格式

name: your-skill-name

description: 它做什么。当用户要求[特定短语]时使用。

  1. 字段要求
    name（必需）

只允许 kebab-case，无空格、无大写；
应与文件夹名保持一致。
description（必需）

必须同时包含：
Skill 做什么；
何时使用它（触发条件）；
不超过 1024 字符；
禁止 XML 标签（< >）；
包含用户可能说的具体任务；
如相关，提及文件类型（如 .fig、.pdf）。
license（可选）：开源时使用，如 MIT、Apache-2.0。

compatibility（可选）：1–500 字符，说明环境要求（产品、系统包、网络等）。

metadata（可选）：自定义键值对，建议包含 author、version、mcp-server 等。

  1. 安全限制
    YAML 头中禁止 XML 尖括号 < >；

Skill 名称不能包含 claude / anthropic 等保留词。
原因：YAML 头会进系统提示，恶意内容可能注入指令。

  1. description 写法：好 vs 坏
    官方给了非常直观的对比：

好的 description：

好 - 具体且可操作 description:

分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、要求“设计规格”、“组件文档”或“设计到代码交接”时使用。

好 - 包含触发短语 description:

管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到“冲刺”、“Linear 任务”、“项目规划”或要求“创建工单”时使用。 # 好 - 清晰的价值主张 description: PayFlow 端到端客户入职工作流。处理账户创建、支付设置和订阅管理。当用户说“入职新客户”、“设置订阅”或“创建 PayFlow 账户”时使用。

不好的 description：

太模糊

description: 帮助处理项目。

缺少触发条件

description: 创建复杂的多页文档系统。

太技术化，没有用户触发条件

description: 实现具有层次关系的 Project 实体模型。

关键差异：

好 description 包含用户真实会说的触发短语，坏 description 只有抽象功能描述。

七、SKILL.md 正文：教 Claude “具体怎么做”
YAML 头决定“什么时候用”，SKILL.md 正文决定“具体怎么做”。官方给了一个推荐结构：

预期输出：

[描述成功的样子]  （根据需要添加更多步骤）  

## 示例  

### 示例 1：[常见场景]  用户说：“设置一个新的营销活动”  操作： 

    1. 通过 MCP 获取现有活动 

    2. 使用提供的参数创建新活动  结果：活动已创建，附带确认链接  （根据需要添加更多示例）  

## 故障排查  

### 错误：[常见错误消息]  原因：[为什么会发生]  解决方案：[如何修复]  （根据需要添加更多错误案例）

指令编写的最佳实践
✅ 好：

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.

包含错误处理：

Common Issues

MCP Connection Failed

If you see "Connection refused":

  1. Verify MCP server is running: Check Settings > Extensions
  2. Confirm API key is valid
  3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect

清晰引用捆绑资源

Before writing queries, consult references/api-patterns.md

for:

  • Rate limiting guidance
  • Pagination patterns
  • Error codes and handling

使用渐进式披露：保持 SKILL.md 专注于核心指令，把详细文档移到 references/ 并链接过去。

八、测试与迭代：从“感觉”到“指标”
官方推荐三种测试方式，从粗到细：

专业提示：

官方建议先在单个最难的任务上迭代，直到 Claude 成功，再把这套方法抽象成 Skill。

这样比一上来就写很多用例更高效。

推荐的测试三维度

      ✅ 在改写请求上触发；
      ❌ 在无关主题上不触发。

九、五大设计模式：从“简单流程”到“领域专家”
官方总结了五种常见模式，适合直接照着用：

模式 1：顺序工作流编排
场景：多步骤流程，有严格顺序和依赖。

示例：客户入职

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
关键技术：显式步骤排序、依赖关系、每阶段验证、失败回滚。

模式 2：多 MCP 协调
场景：跨多个服务的工作流。

示例：Figma → Drive → Linear → Slack

Phase 1: Design Export (Figma MCP)

  1. Export design assets from Figma
  2. Generate design specifications
  3. Create asset manifest

Phase 2: Asset Storage (Drive MCP)

  1. Create project folder in Drive
  2. Upload all assets
  3. Generate shareable links

Phase 3: Task Creation (Linear MCP)

  1. Create development tasks
  2. Attach asset links to tasks
  3. Assign to engineering team

Phase 4: Notification (Slack MCP)

  1. Post handoff summary to #engineering
  2. Include asset links and task references
    关键技术：阶段分离、MCP 间数据传递、进入下一阶段前验证、集中错误处理。

模式 3：迭代优化
场景：输出质量随迭代改善。

示例：报告生成

Iterative Report Creation

Initial Draft

  1. Fetch data via MCP
  2. Generate first draft report
  3. Save to temporary file

Quality Check

  1. Run validation script: scripts/check_report.py
  2. Identify issues:
  • Missing sections
  • Inconsistent formatting
  • Data validation errors

Refinement Loop

  1. Address each identified issue
  2. Regenerate affected sections
  3. Re-validate
  4. Repeat until quality threshold met

Finalization

  1. Apply final formatting
  2. Generate summary
  3. Save final version
    关键技术：明确质量标准、迭代改进、验证脚本、知道何时停止。

模式 4：上下文感知工具选择
场景：同一结果，根据上下文选不同工具。

示例：智能文件存储

Smart File Storage

Decision Tree

  1. Check file type and size

  2. Determine best storage location:

    • Large files (>10MB): Use cloud storage MCP
    • Collaborative docs: Use Notion/Docs MCP
    • Code files: Use GitHub MCP
    • Temporary files: Use local storage

Execute Storage

Based on decision:

  • Call appropriate MCP tool
  • Apply service-specific metadata
  • Generate access link

Provide Context to User

Explain why that storage was chosen
关键技术：清晰决策标准、回退选项、对选择保持透明。

模式 5：领域特定智能
场景：Skill 增加的是专业知识，而不仅仅是工具访问。

示例：金融合规支付处理

Payment Processing with Compliance

Before Processing (Compliance Check)

  1. Fetch transaction details via MCP

  2. Apply compliance rules:

    • Check sanctions lists
    • Verify jurisdiction allowances
    • Assess risk level
  3. Document compliance decision

Processing

IF compliance passed:

  • Call payment processing MCP tool
  • Apply appropriate fraud checks

  • Process transaction
    ELSE:

    • Flag for review
    • Create compliance case

Audit Trail

  • Log all compliance checks
  • Record processing decisions
  • Generate audit report

关键技术：逻辑中嵌入领域知识、行动前合规、全面文档、清晰治理。

十、故障排查：常见坑与官方解法
官方列了一堆典型问题，这里挑最关键的几个：

  1. Skill 无法上传
  • 错误：Could not find SKILL.md in uploaded folder
  • 原因：文件名不是 SKILL.md。
  • 解决：严格命名为 SKILL.md，区分大小写。
  • 错误：Invalid frontmatter
  • 原因：YAML 格式问题（缺少 ---、引号未闭合等）。
  • 解决：确保有 --- 分隔符，且 YAML 语法正确。
  • 错误：Invalid skill name
  • 原因：name 有空格或大写。
  • 解决：改用 kebab-case，如 my-cool-skill。
  1. Skill 不触发
  • 症状：Skill 从不自动加载。
  • 修复：改 description，让它更具体、包含触发短语。
  • 调试方法：问 Claude：“你什么时候会使用 [skill name] skill？”根据回答调整 description。
  1. Skill 触发太频繁
  • 症状：在不相关查询上也加载。
  • 解决：
  • 在 description 中加负面触发条件（如“不要用于简单数据探索，用 data-viz Skill 代替”）；
  • 更具体地描述范围；
  • 明确说“仅用于……”。
  1. MCP 连接问题
  • 检查清单：

a.MCP 服务器已在 Claude.ai 中连接；

b.API key / OAuth token 有效；

c.先让 Claude 直接调用 MCP 工具，确认 MCP 本身正常；

d.工具名称拼写与 MCP 文档一致（区分大小写）。

  1. 指令未被遵循
  • 常见原因：

a.指令太冗长 → 精简、用列表；

b.关键指令被埋没 → 放顶部，用 ## Important / ## Critical；

c.语言模糊 → 用明确、可操作的描述。

十一、分发与共享：从个人到组织
官方 2026 年初的分发方式：

个人 / 小团队：

- 把 Skill 文件夹压缩成 .zip；

- 在 Claude.ai → Settings → Skills 中上传；

- 在 Claude Code 中放到本地 skills 目录。

组织级：

- Team / Enterprise 管理员可以在工作区范围内部署 Skill，实现自动更新和集中管理。

API 使用：

- 通过 /v1/skills API 管理 Skill；

- 需要 Code Execution Tool Beta 执行环境。

开源 / 社区：

- 推荐托管在 GitHub，仓库根目录写 README 给人看，Skill 内部不放 README；

- 在 README / 文档中突出“成果”而不是“YAML 结构”。

十二、快速检查清单（开发 & 上传前后）
官方附录里的检查清单：

开始之前

  • 已识别 2–3 个具体用例；
  • 已识别需要的工具（内置 / MCP）；
  • 已阅读本指南和示例 Skill；
  • 已规划文件夹结构。

开发期间

  • 文件夹使用 kebab-case 命名；
  • SKILL.md 存在且拼写正确；
  • YAML 头有 --- 分隔符；
  • name 字段为 kebab-case，无空格、无大写；
  • description 包含“做什么 + 何时使用”；
  • 全文无 XML 标签 < >；
  • 指令清晰可操作；
  • 包含错误处理；
  • 引用文件已链接。

上传之前

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

上传之后

  • 在真实对话中测试；
  • 监控触发不足 / 过度触发；
  • 收集用户反馈；
  • 根据 description 和指令迭代；
  • 更新 metadata 中的版本号。

结语：从“会用 Claude”到“会流程工程”
整份指南传递的核心观念其实很朴素：

MCP 给厨房，Skill 给食谱，两者结合才有稳定出品
用好渐进式披露，兼顾专业深度和 token 效率
把重复流程变成 Skill，把经验变成可复用的资产
不要每次重新教 Claude 同一套流

标签: none

添加新评论