构建 Claude Skill 的完整指南｜Anthropic

引言：什么是 Skill，为什么它很重要

Skill 是一个文件夹——里面装着一组指令，用来教 Claude 如何处理某类特定的任务或工作流。它是把 Claude 定制成你专属助手的最强方式之一。

与其每次对话都重新解释你的偏好、流程和领域知识，不如把它们一次性教给 Claude，然后永远受益。

Skill 特别适合这些场景：

• 根据规格文档生成前端设计
• 用一致的方法论开展研究
• 按团队风格指南撰写文档
• 编排多步骤流程

它能很好地配合 Claude 的内建能力，比如代码执行和文档生成。如果你正在做 MCP 集成，Skill 会是另一个强大的能力层——把原始的工具访问能力转化为可靠且优化的工作流。

这份指南覆盖什么？

你会学到：

• Skill 结构的技术要求与最佳实践
• 独立 Skill 与 MCP 增强型 Skill 的模式
• 在不同用例中行之有效的模式
• 如何测试、迭代和分发你的 Skill

适合谁读：

• 希望 Claude 始终如一地执行特定流程的开发者
• 想让 Claude 跟随特定流程的高阶用户
• 希望在组织内部标准化 Claude 使用方式的团队

两条阅读路径

• 想做独立 Skill？重点看「基础概念」「规划与设计」。
• 想给 MCP 集成做增强？「Skills + MCP」小节是为你准备的。

两条路径共享同样的技术要求，按需取舍即可。

一、基础概念（Fundamentals）

Skill 是什么样的文件夹？

一个 Skill 文件夹通常包含：

• SKILL.md（必需）：带 YAML frontmatter 的 Markdown 指令文件
• scripts/（可选）：可执行代码（Python、Bash 等）
• references/（可选）：按需加载的参考文档
• assets/（可选）：模板、字体、图标等输出资源

三大核心设计原则

Skill 采用三层加载机制，让 Claude 在不浪费上下文的前提下保留专业能力：

• 第一层（YAML frontmatter）：始终加载进 Claude 的系统提示。给出最少的信息，让 Claude 判断何时调用这个 Skill，但不加载具体内容。
• 第二层（SKILL.md 正文）：当 Claude 认为这个 Skill 与当前任务相关时才加载，包含完整指令和指导。
• 第三层（链接文件）：Skill 目录里的额外文件，只有 Claude 真正需要时才会去查阅。

这种设计最小化了 token 消耗，同时保留了专业能力。

Claude 可以同时加载多个 Skill。你的 Skill 应当与其他 Skill 友好共存，而不是假设自己是唯一的能力来源。

Skill 在 Claude.ai、Claude Code 和 API 上的运行方式是一致的。一次创建，多处使用——前提是运行环境支持 Skill 所依赖的资源。

给 MCP 构建者：Skill + Connector 的协同

如果你已经有一个能跑的 MCP server，最难的工作已经完成。Skill 是叠加在它之上的知识层——把你已经掌握的工作流和最佳实践显式化，让 Claude 能稳定复用。

• MCP 提供的是专业厨房：访问工具、食材和设备的能力。
• Skill 提供的是菜谱：一步步告诉你如何做出有价值的成品。

两者结合，用户不必自己摸索每一步就能完成复杂任务。

没有 Skill 时：

• 用户连上你的 MCP 后，不知道下一步该做什么
• 大量「怎么用你这个集成做 X」的工单涌入
• 每次对话都从零开始
• 不同用户的 prompt 不同，结果不一致
• 问题其实是「缺少工作流指引」，用户却以为是连接器有 bug

有 Skill 后：

• 预制工作流在需要时自动激活
• 工具调用稳定可靠
• 每次交互都内嵌最佳实践
• 你的集成学习曲线更平缓

二、规划与设计（Planning and Design）

从用例出发

动手写代码之前，先明确 2-3 个具体用例。

一个好的用例定义长这样：

Use Case: Project Sprint Planning
Trigger: 用户说「help me plan this sprint」或「create sprint tasks」
Steps:
1. 通过 Linear（MCP）拉取当前项目状态
2. 分析团队速度和容量
3. 给出任务优先级建议
4. 在 Linear 中创建带有合适标签和估时的任务
Result: 一个完整规划好的 Sprint，任务已就位

问自己几个问题：

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

三种最常见的 Skill 用例类型

Anthropic 团队总结了三种最常见的 Skill 形态：

用途：生成一致、高质量的输出，比如文档、PPT、应用、设计稿、代码等。

真实例子：frontend-design Skill（以及 docx、pptx、xlsx、ppt 系列 Skill）。

「创建独特、达到生产级品质的前端界面。在构建 Web 组件、页面、artifact、海报或应用时使用。」

核心技巧：

• 内嵌风格指南与品牌规范
• 用模板结构保证一致性
• 在收尾前过一遍质量清单
• 不依赖外部工具，纯靠 Claude 内建能力

用途：需要稳定方法论的多步流程，包括跨多个 MCP server 的协调。

真实例子：skill-creator Skill。

「创建新 Skill 的交互式向导。带用户走完用例定义、frontmatter 生成、指令撰写和校验的全过程。」

核心技巧：

• 带校验门的分步流程
• 常见结构的模板
• 内建的复审与改进建议
• 迭代式精炼循环

用途：为 MCP server 提供的工具访问能力补充工作流指引。

真实例子：Sentry 出品的 sentry-code-review Skill。

「通过 Sentry MCP 接入错误监控数据，自动分析并修复 GitHub Pull Request 中检测到的 bug。」

核心技巧：

• 按顺序协调多次 MCP 调用
• 内嵌领域专业知识
• 提供用户原本需要自己说明的上下文
• 处理常见的 MCP 错误

定义成功标准

你怎么知道 Skill 跑通了？

• Skill 在 90% 的相关查询上正确触发
  • 测量方式：跑 10-20 个应该触发的测试 query，看自动加载 vs. 需要显式调用的比例。
• 完成工作流的工具调用数控制在 X 次以内
  • 测量方式：开启 vs. 关闭 Skill，对同一任务计数。比较 tool call 数与 token 消耗。
• 每个工作流 0 次失败的 API 调用
  • 测量方式：监控测试期间的 MCP server 日志，跟踪重试率和错误码。

• 用户不需要提示 Claude「下一步该做什么」
  • 评估方式：测试中记录你需要纠偏或澄清的次数；找种子用户收集反馈。
• 工作流无需用户修正即可完成
  • 评估方式：同一请求跑 3-5 次，比较结构一致性与质量。
• 不同会话间结果稳定
  • 评估方式：一个新用户能否在最少指导下一次成功？

技术要求

your-skill-name/
├── SKILL.md            # 必需 - 主文件
├── scripts/            # 可选 - 可执行代码
│   ├── process_data.py
│   └── validate.sh
├── references/         # 可选 - 参考文档
│   ├── api-guide.md
│   └── examples/
└── assets/             # 可选 - 模板等
    └── report-template.md

SKILL.md 命名：

• 必须严格叫 SKILL.md（大小写敏感）
• SKILL.MD、skill.md 等变体都不接受

Skill 文件夹命名：

• ✅ 使用 kebab-case：notion-project-setup
• ❌ 不能有空格：Notion Project Setup
• ❌ 不能用下划线：notion_project_setup
• ❌ 不能用大写：NotionProjectSetup

不要放 README.md：

• Skill 文件夹内部不要包含 README.md
• 所有文档放进 SKILL.md 或 references/
• 注意：如果通过 GitHub 分发，仓库根目录仍然需要一个面向人类访问者的 README——见「分发与分享」章节。

YAML frontmatter：最重要的部分

YAML frontmatter 决定了 Claude 何时加载你的 Skill。务必写对。

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

这就是起步所需的全部。

name（必需）：

• 只能用 kebab-case
• 不能有空格或大写
• 应与文件夹名一致

description（必需）：

• 必须同时包含：
  • 这个 Skill 做什么
  • 何时使用它（触发条件）
• 控制在 1024 字符以内
• 禁止 XML 标签（< 或 >）
• 包含用户可能说出的具体短语
• 涉及文件类型时要点明

license（可选）：

• 适用于开源 Skill
• 常见值：MIT、Apache-2.0

compatibility（可选）：

• 1-500 字符
• 标明环境需求：目标产品、依赖的系统包、是否需要联网等

metadata（可选）：

• 任意自定义键值对
• 推荐字段：author、version、mcp-server
• 示例：

metadata:
	author: ProjectHub
	version: 1.0.0
	mcp-server: projecthub

frontmatter 中禁止：

• XML 尖括号（< >）
• 名字含 claude 或 anthropic 的 Skill（保留字）

原因：frontmatter 会进入 Claude 的系统提示，恶意内容可能注入指令。

编写有效的 Skill

Anthropic 工程博客指出：「这段 metadata……提供刚好够用的信息，让 Claude 知道何时该调用每个 Skill，而无需把全部内容塞进上下文。」这正是渐进式披露的第一层。

推荐结构：

[做什么] + [何时使用] + [关键能力]

好的描述示例：

# ✅ 具体且可操作
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".

# ✅ 包含触发短语
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.
Handles account creation, payment setup, and subscription management.
Use when user says "onboard new customer", "set up subscription",
or "create PayFlow account".

反面教材：

# ❌ 太笼统
description: Helps with projects.

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

# ❌ 太技术化，没有用户视角的触发词
description: Implements the Project entity model with hierarchical relationships.

frontmatter 之后，用 Markdown 写正式的指令。下面是一个可以直接套用的模板：

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [第一个主要步骤]
说明清楚发生了什么。

示例：

python scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功的样子]

（按需添加更多步骤）

## Examples

### Example 1: [常见场景]
用户说：「Set up a new marketing campaign」

执行：
1. 通过 MCP 拉取现有 campaign
2. 用提供的参数创建新 campaign

结果：campaign 创建完成并附确认链接

## Troubleshooting

### Error: [常见错误信息]
**Cause:** [为什么发生]
**Solution:** [如何修复]

具体且可执行

✅ 好：

运行 `python scripts/validate.py --input {filename}` 检查数据格式。
如果校验失败，常见问题包括：
- 缺少必填字段（在 CSV 中补上）
- 日期格式无效（使用 YYYY-MM-DD）

❌ 差：

在继续前正确地验证数据。

包含错误处理

## Common Issues

### MCP Connection Failed
如果看到「Connection refused」：
1. 确认 MCP server 在跑：Settings > Extensions
2. 确认 API key 有效
3. 尝试重连：Settings > Extensions > [Your Service] > Reconnect

清晰引用打包资源

写查询前，先查阅 `references/api-patterns.md` 了解：
- 速率限制策略
- 分页模式
- 错误码与处理方式

用好渐进式披露

SKILL.md 只保留核心指令，详细文档放进 references/ 并链接过去。

三、测试与迭代（Testing and Iteration）

按需求程度，Skill 的测试可以从轻到重分几个层级：

• 在 Claude.ai 手动测试：直接发 query，观察行为。零成本、迭代快。
• 在 Claude Code 做脚本化测试：自动化测试用例，每次改动都可复现。
• 通过 Skills API 做程序化测试：构建评测套件，对一组定义好的测试集批量跑。

选哪种取决于你的质量要求和 Skill 的可见度——小团队内部用的 Skill 和服务千万企业用户的 Skill，测试投入完全不同。

推荐的三类测试

目标：确保 Skill 在合适的时机加载。

检查清单：

• ✅ 在显而易见的任务上触发
• ✅ 在改写后的请求上触发
• ❌ 在无关话题上不触发

示例测试集：

应当触发：
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

不应触发：
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet"（除非 ProjectHub Skill 真的处理 sheet）

目标：验证 Skill 的输出是否正确。

检查清单：

• 输出结果正确
• API 调用成功
• 错误处理生效
• 边界情况被覆盖

示例：

测试：创建带 5 个任务的项目
给定：项目名 "Q4 Planning"，5 条任务描述
执行：Skill 跑完整个工作流
期望：
 - ProjectHub 中创建了对应项目
 - 5 个任务被创建且属性正确
 - 所有任务都关联到项目
 - 无 API 错误

目标：证明 Skill 比基线更好。

基线对比示例：

没有 Skill：
- 用户每次都要交代上下文
- 15 轮来回消息
- 3 次 API 调用失败需要重试
- 12,000 tokens 消耗

有 Skill：
- 工作流自动执行
- 只需 2 个澄清问题
- 0 次失败的 API 调用
- 6,000 tokens 消耗

使用 skill-creator Skill

skill-creator 在 Claude.ai 的插件目录中可以拿到，Claude Code 也能下载安装。它能在一次会话内帮你构建并测试一个可工作的 Skill——前提是你已经有 MCP server 并清楚自己最关心的 2-3 个工作流。通常需要 15-30 分钟。

它能做什么：

• 创建 Skill：从自然语言描述生成 Skill，产出符合规范的 SKILL.md，并推荐触发短语与结构。
• 复审 Skill：识别常见问题（描述太模糊、缺触发词、结构问题），评估过/欠触发风险，基于声明目的建议测试用例。
• 迭代改进：遇到边界情况或失败后，把案例带回去，让 skill-creator 帮你针对性优化。

使用方式：

Use the skill-creator skill to help me build a skill for [your use case]

基于反馈持续迭代

Skill 是活文档，要根据信号不断调整。

欠触发（Undertriggering）信号：

• 该加载时没加载
• 用户在手动启用
• 收到「什么时候用这个 Skill」的提问

解决方案：在 description 中增加细节与差异化描述，尤其是技术术语的关键词。

过触发（Overtriggering）信号：

• 在不相关 query 上也加载
• 用户在主动禁用它
• 用户搞不清它到底干嘛的

解决方案：加入「反向触发」，让范围更具体。

执行问题：

• 结果不稳定
• API 调用失败
• 用户需要不断纠正

解决方案：改进指令、补充错误处理。

四、分发与分享（Distribution and Sharing）

Skill 让你的 MCP 集成「更完整」。当用户比较连接器时，带 Skill 的连接器能更快带来价值，相比纯 MCP 方案有明显优势。

当前的分发模型（2026 年 1 月）

个人用户如何获取 Skill：

1. 下载 Skill 文件夹
2. 必要时打包成 zip
3. 在 Claude.ai 中通过 Settings > Capabilities > Skills 上传
4. 或放进 Claude Code 的 skills 目录

组织级 Skill：

• 管理员可在工作区范围内统一部署（2025 年 12 月 18 日上线）
• 支持自动更新
• 集中化管理

一个开放标准

Anthropic 已经把 Agent Skills 作为开放标准发布。和 MCP 一样，他们认为 Skill 应当跨工具、跨平台可移植——同一个 Skill 应当能在 Claude 与其他 AI 平台之间通用。

当然，部分 Skill 会专门利用某平台特定能力，作者可以在 compatibility 字段里说明。Anthropic 正与生态伙伴合作推进这一标准，早期采用情况令人鼓舞。

通过 API 使用 Skill

面向程序化使用（应用、Agent、自动化工作流），API 提供了对 Skill 管理与执行的直接控制：

• /v1/skills 端点：列举与管理 Skill
• 在 Messages API 请求中通过 container.skills 参数挂载 Skill
• 在 Claude Console 做版本管理
• 与 Claude Agent SDK 配合构建自定义 Agent

何时用 API vs. Claude.ai？

现阶段推荐的分发方式

1. 托管在 GitHub
   • 公开仓库
   • 清晰的 README（面向人类——和 Skill 文件夹内禁止的那个 README.md 是两回事）
   • 示例与截图
2. 在 MCP 仓库中链接 Skill
   • 在 MCP 文档中指向你的 Skill
   • 说明组合使用的价值
   • 提供快速上手指南
3. 写一份安装指南

## 安装 [Your Service] Skill

1. 下载 Skill：
   - clone 仓库：`git clone https://github.com/yourcompany/skills`
   - 或从 Releases 下载 ZIP

2. 在 Claude 中安装：
   - 打开 Claude.ai > Settings > Skills
   - 点击 "Upload skill"
   - 选择 Skill 文件夹（zip 包）

3. 启用 Skill：
   - 启用 [Your Service] Skill 开关
   - 确认对应 MCP server 已连接

4. 测试：
   - 问 Claude：「Set up a new project in [Your Service]」

如何描述你的 Skill

描述方式直接决定了用户会不会去试。

聚焦结果，而不是功能：

✅ 好：

「ProjectHub Skill 让团队在几秒钟内就能搭起一个完整的项目空间——包含页面、数据库、模板——而不是花 30 分钟手动配置。」

❌ 差：

「ProjectHub Skill 是一个文件夹，包含 YAML frontmatter 和 Markdown 指令，调用我们的 MCP server 工具。」

讲好「MCP + Skill」组合的故事：

「我们的 MCP server 让 Claude 能访问你的 Linear 项目；我们的 Skill 教 Claude 团队的 Sprint 规划方法。两者结合，让 AI 真正胜任项目管理。」

五、常见模式与排错（Patterns & Troubleshooting）

以下模式来自早期采用者与 Anthropic 内部团队的实践沉淀，是已被验证好用的常见做法，而非硬性模板。

选择思路：以问题为中心 vs. 以工具为中心

把它想象成逛 Home Depot 五金店——

• 你可以带着问题进门：「我要修橱柜」→ 店员会给你推荐合适的工具；
• 也可以先选了工具：「我有了一把新电钻」→ 然后问怎么用在你的场景。

Skill 也一样：

• 问题驱动：「我要搭建一个项目空间」→ Skill 帮你按正确顺序协调一堆 MCP 调用。用户描述结果，Skill 处理工具。
• 工具驱动：「我已经接好了 Notion MCP」→ Skill 教 Claude 该如何高效使用它。用户有访问权，Skill 提供专业知识。

多数 Skill 会偏向其中一种。先明确自己的定位，再选下面对应的模式。

模式 1：顺序工作流编排

何时用：用户的多步流程必须按特定顺序执行。

示例结构：

## Workflow: 新客户 Onboarding

### Step 1: 创建账户
调用 MCP 工具：`create_customer`
参数：name, email, company

### Step 2: 设置付款方式
调用 MCP 工具：`setup_payment_method`
等待：付款方式验证完成

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

### Step 4: 发送欢迎邮件
调用 MCP 工具：`send_email`
模板：welcome_email_template

核心技巧：

• 显式声明步骤顺序
• 表明步骤间的依赖关系
• 每一步都做校验
• 提供失败回滚指引

模式 2：多 MCP 协同

何时用：工作流横跨多个服务。

示例：设计到开发交付

### Phase 1: 设计导出（Figma MCP）
1. 从 Figma 导出设计资源
2. 生成设计规格
3. 创建资源清单

### Phase 2: 资源存储（Drive MCP）
1. 在 Drive 中创建项目文件夹
2. 上传所有资源
3. 生成可共享链接

### Phase 3: 任务创建（Linear MCP）
1. 创建开发任务
2. 将资源链接挂到任务上
3. 指派给工程团队

### Phase 4: 通知（Slack MCP）
1. 在 #engineering 发布交付摘要
2. 包含资源链接与任务引用

核心技巧：

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

模式 3：迭代式精炼

何时用：输出质量随迭代而提升。

示例：报告生成

## Iterative Report Creation

### 初稿
1. 通过 MCP 拉数据
2. 生成首版报告
3. 存为临时文件

### 质量检查
1. 跑校验脚本：`scripts/check_report.py`
2. 识别问题：
   - 缺失章节
   - 格式不一致
   - 数据校验错误

### 精炼循环
1. 逐一处理识别到的问题
2. 重新生成受影响的章节
3. 重新校验
4. 直到质量阈值满足为止

### 收尾
1. 应用最终格式
2. 生成摘要
3. 保存最终版本

核心技巧：

• 明确的质量准则
• 迭代式改进
• 校验脚本兜底
• 知道什么时候该停

模式 4：上下文感知的工具选择

何时用：目标相同，但根据上下文要选不同工具。

示例：文件存储

## 智能文件存储

### 决策树
1. 检查文件类型与大小
2. 决定最佳存储位置：
   - 大文件（>10MB）：用云存储 MCP
   - 协作文档：用 Notion/Docs MCP
   - 代码文件：用 GitHub MCP
   - 临时文件：用本地存储

### 执行存储
基于决策：
- 调用对应的 MCP 工具
- 应用服务特定的 metadata
- 生成访问链接

### 向用户解释
说明为什么选了这个存储位置

核心技巧：

• 清晰的决策准则
• 备选方案兜底
• 对选择保持透明

模式 5：领域专属智能

何时用：Skill 在工具访问之外，额外注入专业领域知识。

示例：金融合规

## 支付处理与合规

### 处理前（合规检查）
1. 通过 MCP 拉取交易明细
2. 套用合规规则：
   - 制裁名单核查
   - 司法管辖区允许性核查
   - 风险等级评估
3. 记录合规决策

### 处理
IF 合规通过：
  - 调用支付处理 MCP 工具
  - 应用合适的反欺诈检查
  - 处理交易
ELSE:
  - 标记为待审
  - 创建合规案件

### 审计追踪
- 记录所有合规检查
- 记录处理决策
- 生成审计报告

核心技巧：

• 领域知识嵌入逻辑
• 行动前先做合规
• 完整的文档留痕
• 清晰的治理路径

排错（Troubleshooting）

错误：「Could not find SKILL.md in uploaded folder」

• 原因：文件名不严格等于 SKILL.md
• 解决：改名为 SKILL.md（大小写敏感）；用 ls -la 确认

错误：「Invalid frontmatter」

• 原因：YAML 格式错误
• 常见错误：

# ❌ 缺少分隔符
name: my-skill
description: Does things

# ❌ 引号未闭合
name: my-skill
description: "Does things

# ✅ 正确
---
name: my-skill
description: Does things
---

错误：「Invalid skill name」

• 原因：名字含空格或大写

# ❌
name: My Cool Skill

# ✅
name: my-cool-skill

症状：永远不自动加载。

修复：调整 description 字段。快速自检：

• 是不是太泛？（「Helps with projects」根本不行）
• 有没有包含用户真的会说的触发短语？
• 涉及的文件类型有没有点明？

调试技巧：问 Claude「你什么时候会用 [skill name] 这个 Skill？」Claude 会复述 description，根据回答补充缺失信息。

症状：在无关 query 上也加载。

解决方案：

1. 加入反向触发：

description: Advanced data analysis for CSV files. Use for statistical
modeling, regression, clustering. Do NOT use for simple data exploration
(use data-viz skill instead).

1. 更具体：

# ❌ 太宽
description: Processes documents

# ✅ 更具体
description: Processes PDF legal documents for contract review

1. 限定范围：

description: PayFlow payment processing for e-commerce. Use specifically
for online payment workflows, not for general financial queries.

症状：Skill 加载了，但 MCP 调用失败。

自查清单：

1. MCP server 是否连上：Claude.ai > Settings > Extensions > 对应服务，状态应为「Connected」
2. 认证：API key 是否有效、权限是否足够、OAuth token 是否刷新过
3. 独立测试 MCP：让 Claude 不走 Skill 直接调用 MCP，「Use [Service] MCP to fetch my projects」。如果直接调用也失败，那是 MCP 的问题而不是 Skill 的。
4. 工具名一致性：Skill 引用的 MCP 工具名是否正确、大小写是否一致

症状：Skill 加载了，但 Claude 不按指令做。

常见原因：

1. 指令太啰嗦
   • 保持简洁
   • 用列表代替长段落
   • 详细参考挪到独立文件
2. 指令被埋没
   • 关键指令放最上面
   • 用 ## Important 或 ## Critical 这样的标题
   • 必要时重复关键点
3. 语言模糊

# ❌ 差
确保正确地校验内容

# ✅ 好
CRITICAL: 在调用 create_project 之前，请校验：
- 项目名非空
- 至少分配一位团队成员
- 开始日期不在过去

1. 模型「偷懒」：可以追加显式鼓励：

## Performance Notes
- 慢慢来，做扎实
- 质量比速度重要
- 不要跳过校验步骤

注：这种话放在用户 prompt 中比放在 SKILL.md 中效果更好。

症状：响应变慢或质量下降。

原因：

• Skill 内容本身过大
• 同时启用太多 Skill
• 没用渐进式披露，全量加载

解决方案：

1. 精简 SKILL.md
   • 详细文档挪进 references/
   • 用链接代替内嵌
   • 控制在 5,000 字以内
2. 减少启用的 Skill 数量
   • 同时启用 20-50 个以上就该重审了
   • 推荐选择性启用
   • 考虑把相关能力打包成 Skill 「pack」

六、资源与参考（Resources & References）

官方文档

Anthropic 资源：

• Best Practices Guide
• Skills Documentation
• API Reference
• MCP Documentation

博客文章：

• Introducing Agent Skills
• Engineering Blog: Equipping Agents for the Real World
• Skills Explained
• How to Create Skills for Claude
• Building Skills for Claude Code
• Improving Frontend Design through Skills

示例 Skill 仓库

• GitHub：anthropics/skills，包含 Anthropic 出品的可定制 Skill

工具

• skill-creator Skill：Claude.ai 内建，Claude Code 可下载；能从描述生成 Skill，复审并提建议
• 验证：可让它复审你的 Skill 并给出改进建议（「Review this skill and suggest improvements」）

获取支持

• 技术问题：Claude Developers Discord 社区论坛
• Bug 反馈：GitHub Issues 提交到 anthropics/skills/issues，附 Skill 名、报错信息、复现步骤

附录 A：上线前后的快速检查清单

用它来验证你的 Skill。也可以先用 skill-creator 生成初稿，再走一遍清单查漏补缺。

开始前

开发中

上传前

上传后

附录 B：YAML frontmatter 速查

必填字段：

---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific trigger phrases.
---

所有可选字段：

name: skill-name
description: [必填描述]
license: MIT                                        # 可选：开源协议
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

安全说明：

• 允许：任何标准 YAML 类型（字符串、数字、布尔值、列表、对象）、自定义 metadata、最长 1024 字符的描述
• 禁止：XML 尖括号、YAML 中的代码执行、含 claude / anthropic 前缀的 Skill 名（保留字）

附录 C：完整 Skill 示例

生产级、可直接借鉴的示例：

• Document Skills：PDF、DOCX、PPTX、XLSX 文档生成
• Example Skills：覆盖各种工作流模式
• Partner Skills Directory：Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的 Skill

这些仓库会持续更新，包含比本指南更丰富的示例。直接 clone、改造、当模板用即可。