The Complete Guide to Building Skills for Claude

说明

本文按原文《The Complete Guide to Building Skills for Claude》完整重写为中文，保留原始章节结构、示例与要点。

引言
第 1 章：基础（Fundamentals）
第 2 章：规划与设计（Planning and Design）
第 3 章：测试与迭代（Testing and Iteration）
第 4 章：分发与分享（Distribution and Sharing）
第 5 章：模式与故障排查（Patterns and Troubleshooting）
第 6 章：资源与参考（Resources and References）
附录 A：快速检查清单（Quick Checklist）
附录 B：YAML Frontmatter 参考
附录 C：完整 Skill 示例资源

引言

Skill 是一组指令，以一个简单文件夹的形式打包，用来教 Claude 如何处理特定任务或工作流。Skill 是最强大的 Claude 定制方式之一。与其在每次对话里反复解释你的偏好、流程和领域经验，不如一次教会 Claude，之后反复复用。

当你有可重复工作流时，Skill 的价值非常明显：比如从规格生成前端设计、按统一方法做研究、生成符合团队风格规范的文档、编排多步骤流程。Skill 与 Claude 内建能力（如代码执行、文档创建）协同良好。对 MCP 集成构建者而言，Skill 还能再加一层能力，把“原始工具访问”变成“可靠且优化的工作流”。

本指南覆盖构建高质量 Skill 所需的完整内容：从规划、结构到测试与分发。无论你是给自己、团队还是社区构建 Skill，都能看到可落地模式和真实案例。

你将学到

Skill 结构的技术要求与最佳实践
独立 Skill 与 MCP 增强型工作流的模式
在不同场景中被验证有效的模式
如何测试、迭代、分发你的 Skill

适用对象

希望 Claude 稳定遵循特定流程的开发者
希望 Claude 稳定执行特定流程的高级用户
希望在组织内标准化 Claude 工作方式的团队

本指南的两条路径

如果你在构建独立 Skill：重点看「基础」「规划与设计」以及类别 1-2。
如果你在增强MCP 集成：重点看「Skills + MCP」以及类别 3。

两条路径共享同一套技术要求，只是关注点不同。

学完你会得到什么

学完后，你可以在一轮会话内完成一个可用 Skill。使用 skill-creator 构建并测试第一个可运行 Skill，通常约需 15–30 分钟。

第 1 章：基础（Fundamentals）

什么是 Skill

一个 Skill 文件夹通常包含：

SKILL.md（必需）：使用 Markdown 编写，含 YAML frontmatter
scripts/（可选）：可执行代码（Python、Bash 等）
references/（可选）：按需加载的文档资料
assets/（可选）：输出所需模板、字体、图标等

核心设计原则

1) 渐进式披露（Progressive Disclosure）

Skill 使用三层结构：

第一层（YAML frontmatter）：始终加载在 Claude 的 system prompt 中；只提供“何时该用这个 Skill”的最小信息，不把全部内容都塞进上下文。
第二层（SKILL.md 正文）：当 Claude 判断与当前任务相关时才加载，包含完整指令与执行指导。
第三层（关联文件）：Skill 目录内的附加文件，Claude 按需再导航与读取。

这种渐进式披露可以在保持专业能力的同时，尽量节省 token。

2) 可组合性（Composability）

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

3) 可移植性（Portability）

Skill 在 Claude.ai、Claude Code、API 上工作方式一致。只要环境满足依赖，一次构建即可跨端使用。

面向 MCP 构建者：Skills + Connectors

Tip

如果你构建的是不依赖 MCP 的独立 Skill，可以先跳到「规划与设计」，之后再回来看本节。

如果你已经有一个可工作的 MCP server，最难的一步其实已经完成。Skill 是其上的“知识层”：把你已知的最佳实践和工作流沉淀下来，让 Claude 稳定应用。

厨房类比

MCP 像专业厨房：提供工具、食材、设备。
Skill 像菜谱：提供逐步操作，产出有价值结果。

二者结合后，用户无需自己摸索每一步，也能完成复杂任务。

MCP 与 Skill 如何协作

MCP（连接能力）	Skills（知识能力）
把 Claude 连接到你的服务（Notion、Asana、Linear 等）	教 Claude 如何高效使用这些服务
提供实时数据访问和工具调用	沉淀工作流与最佳实践
定义 Claude 能做什么	定义 Claude 应该怎么做

为什么这对 MCP 用户很重要

没有 Skill 时：

用户连上 MCP 后，不知道下一步做什么
经常出现“如何用你这个集成做 X？”的支持工单
每次对话都从零开始
由于提示方式每次不同，结果不一致
用户会把问题归咎于 connector，实际问题是缺少工作流指导

有 Skill 时：

预构建工作流在需要时自动触发
工具调用更稳定、更可靠
每次交互都自带最佳实践
集成的学习成本更低

第 2 章：规划与设计（Planning and Design）

从用例开始

在写代码前，先确定 2–3 个 Skill 要支持的具体用例。

好的用例定义示例：

用例：项目冲刺规划（Project Sprint Planning）
触发：用户说“help me plan this sprint”或“create sprint tasks”
步骤：
1. 通过 MCP 从 Linear 拉取当前项目状态
2. 分析团队 velocity 与容量
3. 给出任务优先级建议
4. 在 Linear 中按正确标签和估时创建任务
结果：产出已完整规划的 sprint，并已创建任务

自检问题：

用户真正想完成什么？
需要哪些多步骤流程？
需要哪些工具（内建能力或 MCP）？
需要内嵌哪些领域知识或最佳实践？

常见 Skill 用例类别

Anthropic 观察到三大类：

类别 1：文档与资产创建（Document & Asset Creation）

用途：稳定生成高质量产物（文档、演示、应用、设计、代码等）
实例：frontend-design（也可参考 docx、pptx、xlsx、ppt 相关 skills）
示例描述：

Create distinctive, production-grade frontend interfaces with high design quality.
Use when building web components, pages, artifacts, posters, or applications.

关键技术：
- 内嵌风格指南与品牌规范
- 模板化结构保证输出一致性
- 交付前质量检查清单
- 无需外部工具（依赖 Claude 内建能力）

类别 2：工作流自动化（Workflow Automation）

用途：对多步骤流程进行方法化执行，含多 MCP server 协调
实例：skill-creator
示例描述：

Interactive guide for creating new skills. Walks the user through use case definition,
frontmatter generation, instruction writing, and validation.

关键技术：
- 分步骤流程 + 校验关卡
- 常见结构模板
- 内建评审与改进建议
- 迭代式优化闭环

类别 3：MCP 增强（MCP Enhancement）

用途：为 MCP 提供的工具访问补上工作流指导层
实例：Sentry 的 sentry-code-review
示例描述：

Automatically analyzes and fixes detected bugs in GitHub Pull Requests using
Sentry's error monitoring data via their MCP server.

关键技术：
- 按顺序编排多个 MCP 调用
- 内嵌领域专家知识
- 自动补齐用户通常不会显式给出的上下文
- 对常见 MCP 问题的错误处理

定义成功标准（Success Criteria）

这类指标更像“目标基准”，不是绝对阈值。应追求严谨，但也要接受一定程度的体验判断（vibes-based assessment）。文档说明：团队也在持续完善更稳健的测量方法与工具。

定量指标

相关请求中，Skill 触发率达到 90%
- 测量：准备 10–20 条应触发请求，统计自动加载 vs 需手动调用的比例
在 X 次工具调用内完成工作流
- 测量：对比启用/不启用 Skill 的同任务调用次数与 token 消耗
每次工作流 API 调用失败为 0
- 测量：查看 MCP server 日志，跟踪重试率与错误码

定性指标

用户无需提示 Claude 下一步做什么
- 评估：记录测试中你需要重定向/澄清的频率，并收集 beta 用户反馈
工作流完成过程中无需用户纠正
- 评估：同一请求跑 3–5 次，比较结构一致性与质量
跨会话结果稳定
- 评估：新用户首次尝试是否能在极少指导下完成任务

技术要求（Technical Requirements）

文件结构

your-skill-name/
├── SKILL.md              # Required - main skill file
├── scripts/              # Optional - executable code
│   ├── process_data.py   # Example
│   └── validate.sh       # Example
├── references/           # Optional - documentation
│   ├── api-guide.md      # Example
│   └── examples/         # Example
└── assets/               # Optional - templates, etc.
    └── report-template.md # Example

关键规则

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 仍然建议保留给人类读者（见第 4 章）

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（可选）：

开源时使用
常见值：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 的 system prompt；恶意内容可能进行指令注入。

写出有效 Skill

`description` 字段

工程博客强调：这段元数据应提供“足够但不过量”的信息，让 Claude 知道何时使用 Skill，而无需提前加载全部内容。这正是渐进式披露的第一层。

推荐结构：

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

好的描述示例：

# Good - 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".
 
# Good - includes 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".
 
# Good - clear value proposition
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".

差的描述示例：

# 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.

主体指令写法

frontmatter 之后，使用 Markdown 编写执行指令。

推荐结构模板：

---
name: your-skill
description: [...]
---
 
# Your Skill Name
 
## Instructions
 
### Step 1: [First Major Step]
Clear explanation of what happens.
 
Example:
 
```bash
python 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 MCP
2. Create new campaign with provided parameters
 
Result: 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)

指令最佳实践

明确、可执行

✅ Good：

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)

❌ Bad：

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

清晰引用打包资源

在写查询前先看 references/api-patterns.md，用于：

限流策略（rate limiting）
分页模式（pagination）
错误码与处理方式

使用渐进式披露

让 SKILL.md 聚焦核心指令；把细节文档放进 references/ 并链接过去。

第 3 章：测试与迭代（Testing and Iteration）

测试强度可按需求分级

在 Claude.ai 手动测试：直接发查询观察行为；迭代快、零配置
在 Claude Code 脚本化测试：自动执行测试集，重复验证改动
通过 Skills API 程序化测试：构建系统化评估套件，跑固定测试集

测试强度应匹配你的质量目标与可见性：内部小团队自用，与面向大量企业用户上线，要求不同。

专业建议

先围绕一个高难任务迭代到“能成功”，再把有效方法抽取为 Skill。这样能充分利用 Claude 的上下文学习能力，并比一开始做大范围测试更快得到有效信号。打好基础后，再扩展测试覆盖面。

使用 `skill-creator` Skill

skill-creator 可在 Claude.ai（插件目录）使用，也可下载用于 Claude Code，可辅助你构建和迭代 Skill。

如果你已有 MCP server，且明确前 2–3 个关键工作流，通常可在一轮会话（约 15–30 分钟）完成可用 Skill 的构建与测试。

用于创建：

从自然语言描述生成 Skill
生成格式正确、含 frontmatter 的 SKILL.md
建议触发短语与结构

用于评审：

标注常见问题（描述模糊、缺少触发条件、结构问题）
识别过触发 / 欠触发风险
根据 Skill 目标建议测试用例

用于迭代：

你在实战中遇到边界问题或失败案例后，可回传给 skill-creator
示例：

Use the issues & solution identified in this chat to improve how the skill handles [specific edge case]

使用方式：

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

注意：skill-creator 能帮助设计与优化 Skill，但不会执行自动化测试套件，也不会产出定量评估结果。

基于反馈迭代

Skill 是“活文档”，应持续迭代。

欠触发信号：

应触发时没触发
用户需要手动启用
用户常问“什么时候该用它”

解决：增强 description 的细节与语义覆盖，尤其补充技术关键词。

过触发信号：

无关查询也触发
用户频繁关闭该 Skill
用户对 Skill 目的感到困惑

解决：增加负触发条件，收窄描述边界。

执行问题信号：

输出不一致
API 调用失败
用户需要反复纠正

解决：强化指令、补充错误处理。

Skill 能让你的 MCP 集成更完整。用户在比较 connectors 时，“带 Skill 的连接器”能更快让用户获得价值，相比仅有 MCP 的方案更有优势。

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

个人用户获取 Skill：

下载 Skill 文件夹
（必要时）将文件夹打包为 zip
在 Claude.ai：Settings > Capabilities > Skills 上传
或放入 Claude Code 的 skills 目录

组织级 Skill：

管理员可全工作区部署（已于 2025-12-18 发布）
支持自动更新
支持集中管理

开放标准

Agent Skills 已作为开放标准发布。和 MCP 一样，目标是跨工具/跨平台可移植：同一 Skill 不应只限定在单一平台。文档同时说明：某些 Skill 会针对特定平台能力做优化，作者可在 compatibility 字段注明。文档也提到其已与生态成员协作推进标准，并看到早期采用进展。

通过 API 使用 Skills

在应用、Agent、自动化工作流等程序化场景中，可通过 API 直接管理并执行 Skill。

关键能力：

使用 /v1/skills 端点列出和管理 skills
在 Messages API 请求中通过 container.skills 参数加入 skills
通过 Claude Console 做版本管理
可与 Claude Agent SDK 配合构建自定义 agents

何时用 API，何时用 Claude.ai / Claude Code

用例	最佳入口
最终用户直接交互使用 skills	Claude.ai / Claude Code
开发中的手动测试与迭代	Claude.ai / Claude Code
个人临时工作流	Claude.ai / Claude Code
应用程序内程序化调用 skills	API
大规模生产部署	API
自动化流水线与 agent 系统	API

Note

API 中的 Skills 依赖 Code Execution Tool beta，它提供 Skill 运行所需的安全环境。

实现细节参考：

Skills API Quickstart
Create Custom skills
Skills in the Agent SDK

当前推荐做法

建议先在 GitHub 建公开仓库，附清晰 README（面向人类读者；与 Skill 文件夹内禁止 README.md 不冲突）和截图示例。然后在 MCP 文档中增加 Skill 章节，说明二者组合价值并给出快速开始指引。

在 GitHub 托管
- 开源 Skill 使用公开仓库
- README 写清安装方法
- 提供示例与截图
在 MCP 仓库文档中说明
- 从 MCP 文档链接到 Skill
- 解释二者结合价值
- 提供 quick-start
提供安装指南模板

## Installing the [Your Service] skill
 
1. Download the skill:
   - Clone repo: `git clone https://github.com/yourcompany/skills`
   - Or download ZIP from Releases
2. Install in Claude:
   - Open Claude.ai > Settings > skills
   - Click "Upload skill"
   - Select the skill folder (zipped)
3. Enable the skill:
   - Toggle on the [Your Service] skill
   - Ensure your MCP server is connected
4. Test:
   - Ask Claude: "Set up a new project in [Your Service]"

Skill 的定位表达（Positioning）

你如何描述 Skill，会直接决定用户是否理解价值、是否愿意尝试。

聚焦结果，不要堆功能：

✅ Good：

The ProjectHub skill enables teams to set up complete project workspaces in seconds
— including pages, databases, and templates — instead of spending 30 minutes on
manual setup.

❌ Bad：

The ProjectHub skill is a folder containing YAML frontmatter and Markdown
instructions that calls our MCP server tools.

强调 MCP + Skills 组合叙事：

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.

第 5 章：模式与故障排查（Patterns and Troubleshooting）

这些模式来自早期采用者与内部团队实践，代表“常见有效路径”，不是强制模板。

选型：问题优先 vs 工具优先

文档使用 Home Depot 类比：

你可以带着问题进店（“我要修厨房柜子”），店员给你匹配工具；
也可以先拿起一个新电钻，再问它怎么用于当前任务。

Skill 也是同理：

问题优先（Problem-first）：
- 示例：“I need to set up a project workspace”
- Skill 负责按正确顺序编排 MCP 调用
- 用户表达目标，Skill 处理工具
工具优先（Tool-first）：
- 示例：“I have Notion MCP connected”
- Skill 负责教授最优工作流和最佳实践
- 用户有工具访问，Skill 提供专业方法

大多数 Skill 会偏向其中一种 framing。先选对 framing，再选下方模式。

模式 1：顺序工作流编排（Sequential workflow orchestration）

适用：用户需要按固定顺序执行多步骤流程。

示例结构：

## 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 协同（Multi-MCP coordination）

适用：一个工作流跨多个服务。

示例（设计到开发交接）：

### 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 间数据传递明确
进入下一阶段前先校验
统一错误处理

适用：输出质量需要通过迭代提升。

示例（报告生成）：

## 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：上下文感知的工具选择（Context-aware tool selection）

适用：目标相同，但需要按上下文切换工具。

示例（文件存储）：

## 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

关键技术：

决策标准明确
有 fallback 选项
对选择过程保持透明

模式 5：领域专用智能（Domain-specific intelligence）

适用：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

关键技术：

逻辑中内嵌领域知识
先合规、后执行
完整留痕文档
治理边界清晰

故障排查（Troubleshooting）

1) Skill 无法上传

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

原因：文件名不是严格 SKILL.md
解决：
- 改名为 SKILL.md（区分大小写）
- 用 ls -la 确认可见

错误：Invalid frontmatter

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

# Wrong - missing delimiters
name: my-skill
description: Does things
 
# Wrong - unclosed quotes
name: my-skill
description: "Does things
 
# Correct
---
name: my-skill
description: Does things
---

错误：Invalid skill name

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

# Wrong
name: My Cool Skill
 
# Correct
name: my-cool-skill

2) Skill 不触发

症状：Skill 从不自动加载。

修复：

回到 description 字段重写（参考前文好/坏示例）

快速检查：

是否过于泛化？（如 Helps with projects）
是否包含用户真实会说的触发短语？
若场景相关，是否写明了文件类型？

调试方法：

When would you use the [skill name] skill?

Claude 会回显该 description，可据此补齐缺失信息。

3) Skill 触发过于频繁

症状：无关查询也会加载。

解决方案：

增加负触发条件

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).

写得更具体

# Too broad
description: Processes documents
 
# More specific
description: Processes PDF legal documents for contract review

明确范围边界

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

4) MCP 连接问题

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

检查清单：

检查 MCP server 是否已连接
- Claude.ai：Settings > Extensions > [Your Service]
- 状态应为 Connected
检查认证
- API key 有效且未过期
- 权限 / scope 正确
- OAuth token 已刷新
独立测试 MCP（不经过 Skill）
- 让 Claude 直接调用 MCP
- 例如：Use [Service] MCP to fetch my projects
- 若失败，问题在 MCP，不在 Skill
校对工具名
- Skill 中引用的 MCP 工具名是否准确
- 对照 MCP 文档
- 工具名区分大小写

5) 指令未被遵循

症状：Skill 加载了，但 Claude 没按指令执行。

常见原因与处理：

指令过长冗余
- 保持简洁
- 多用项目符号和编号列表
- 详细参考拆分到独立文件
关键指令埋得太深
- 把关键要求放前面
- 使用 ## Important / ## Critical 标题
- 必要时重复关键点
语言歧义

# Bad
Make sure to validate things properly
 
# Good
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

高级技巧：对关键校验项，优先用脚本做程序化检查，不要只依赖自然语言约束。代码是确定性的，语言解释不是。文档提示可参考 Office skills 的该模式。

模型“偷懒”

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

备注：这类鼓励语放在用户 prompt 中，通常比写在 SKILL.md 更有效。

6) 大上下文问题

症状：Skill 变慢或回答质量下降。

原因：

Skill 内容过大
同时启用太多 Skill
没有渐进加载，而是一次性全加载

解决：

优化 SKILL.md 体积
- 细节挪到 references/
- 用链接代替内联长文
- SKILL.md 控制在 5,000 词以内
减少同时启用数量
- 若同时启用超过 20–50 个，需评估是否过多
- 建议按需启用
- 可考虑按能力打包 Skill packs

第 6 章：资源与参考（Resources and References）

如果你在构建第一个 Skill，建议先看 Best Practices Guide，再按需查 API 文档。

官方文档

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

示例 Skills

公开仓库：

GitHub：anthropics/skills
包含 Anthropic 提供、可供你二次定制的 skills

工具与实用项

skill-creator：

Claude.ai 内置，Claude Code 也可用
可从描述生成 skill
可审阅并给出建议
使用方式：Help me build a skill using skill-creator

校验能力：

skill-creator 可评估你的 skill
可直接提问：Review this skill and suggest improvements

获取支持

技术问题：

一般问题可去 Claude Developers Discord 社区论坛

Bug 报告：

GitHub Issues：anthropics/skills/issues
提交时包含：Skill 名称、错误信息、复现步骤

附录 A：快速检查清单（Quick Checklist）

上传前后都可用这份清单验证 Skill。若想快速起步，可先让 skill-creator 生成草稿，再用本清单逐项补全。

开始前

已识别 2–3 个具体用例
已识别所需工具（内建或 MCP）
已阅读本指南与示例 skills
已规划文件夹结构

开发中

上传前

已测试“明显任务”触发
已测试“改写请求”触发
已验证不会触发无关主题
功能测试通过
工具集成可用（如适用）
已压缩为 .zip

上传后

附录 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: [required description]
license: MIT # Optional: License for open-source
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Optional: Restrict tool access
metadata: # Optional: Custom fields
  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 中执行代码（使用安全 YAML 解析）
名称以 claude 或 anthropic 为前缀的 Skill（保留）

附录 C：完整 Skill 示例资源

要看完整、可生产使用、覆盖本指南模式的 skills，可参考：

Document Skills：PDF、DOCX、PPTX、XLSX 生成
Example Skills：多种工作流模式
Partner Skills Directory：查看合作方 skills（如 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等）

这些仓库会持续更新，包含本指南之外的更多示例。你可以 clone 后按自身场景修改，并作为模板复用。

claude.ai

AI 知识库

探索

Claude Skills 完整构建指南（中文）

The Complete Guide to Building Skills for Claude

目录

引言

你将学到

适用对象

本指南的两条路径

学完你会得到什么

第 1 章：基础（Fundamentals）

什么是 Skill

核心设计原则

1) 渐进式披露（Progressive Disclosure）

2) 可组合性（Composability）

3) 可移植性（Portability）

面向 MCP 构建者：Skills + Connectors

厨房类比

MCP 与 Skill 如何协作

为什么这对 MCP 用户很重要

第 2 章：规划与设计（Planning and Design）

从用例开始

常见 Skill 用例类别

类别 1：文档与资产创建（Document & Asset Creation）

类别 2：工作流自动化（Workflow Automation）

类别 3：MCP 增强（MCP Enhancement）

定义成功标准（Success Criteria）

定量指标

定性指标

技术要求（Technical Requirements）

文件结构

关键规则

YAML frontmatter：最关键部分

写出有效 Skill

description 字段

主体指令写法

指令最佳实践

第 3 章：测试与迭代（Testing and Iteration）

测试强度可按需求分级

推荐测试方法

1) 触发测试（Triggering tests）

2) 功能测试（Functional tests）

3) 性能对比（Performance comparison）

使用 skill-creator Skill

基于反馈迭代

第 4 章：分发与分享（Distribution and Sharing）

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

开放标准

通过 API 使用 Skills

何时用 API，何时用 Claude.ai / Claude Code

当前推荐做法

Skill 的定位表达（Positioning）

第 5 章：模式与故障排查（Patterns and Troubleshooting）

选型：问题优先 vs 工具优先

模式 1：顺序工作流编排（Sequential workflow orchestration）

模式 2：多 MCP 协同（Multi-MCP coordination）

模式 3：迭代精修（Iterative refinement）

模式 4：上下文感知的工具选择（Context-aware tool selection）

模式 5：领域专用智能（Domain-specific intelligence）

故障排查（Troubleshooting）

1) Skill 无法上传

2) Skill 不触发

3) Skill 触发过于频繁

4) MCP 连接问题

5) 指令未被遵循

6) 大上下文问题

第 6 章：资源与参考（Resources and References）

官方文档

示例 Skills

工具与实用项

获取支持

附录 A：快速检查清单（Quick Checklist）

开始前

开发中

上传前

上传后

附录 B：YAML Frontmatter 参考

必填字段

含可选字段的完整示例

安全说明

`description` 字段

使用 `skill-creator` Skill