Claude Skills 构建完全指南（中文版）

封面与目录

Cover and Contents

引言

Introduction

技能（Skill）是一组指令，打包为一个简单文件夹，用来教 Claude 如何处理特定任务或工作流。技能是按你实际需求定制 Claude 的最强方式之一。你不需要在每次对话里重复解释偏好、流程和领域经验；技能让你“教一次，长期复用”。

当你的工作流具有可重复性时，技能尤其有价值：例如按规格生成前端设计、用一致方法做研究、按团队规范生成文档、或编排多步骤流程。它也能与 Claude 的内置能力（如代码执行、文档创建）很好协同。对于正在构建 MCP 集成的人来说，技能还能再提供一层能力：把“原始工具访问”转化为“稳定、可优化的工作流”。

本指南覆盖构建高质量技能所需的全部核心内容：从规划与结构，到测试与分发。无论你是为自己、团队还是社区构建技能，都能在本文找到可直接落地的模式与真实示例。

你将学到什么

• 技能结构的技术要求与最佳实践
• 独立技能与 MCP 增强工作流的设计模式
• 我们在不同场景中验证有效的通用方法
• 如何测试、迭代并分发你的技能

适合谁阅读

• 希望 Claude 稳定执行特定流程的开发者
• 希望 Claude 按固定方法完成任务的高阶用户
• 希望在组织内标准化 Claude 使用方式的团队

阅读路径（Two Paths Through This Guide）

如果你在构建独立技能：重点看“基础”“规划与设计”以及类别 1-2。若你在增强 MCP 集成：重点看“Skills + MCP”部分以及类别 3。两条路径共享同一套技术要求，你只需按自己的场景取用。

读完后，你应当能在一次专注会话内完成一个可用技能。借助 skill-creator，首个可运行技能通常可在 15-30 分钟内构建并完成基础测试。

下面开始正文。

基础（Fundamentals）

什么是技能？

一个技能文件夹通常包含：

• SKILL.md（必需）：带 YAML 前置元数据的 Markdown 指令文件
• scripts/（可选）：可执行代码（Python、Bash 等）
• references/（可选）：按需加载的文档资料
• assets/（可选）：输出中会用到的模板、字体、图标等资源

核心设计原则

1) 渐进式披露（Progressive Disclosure）

技能采用三级加载体系：

• 第一层（YAML 前置元数据）：始终进入 Claude 的系统提示，用最少信息告诉 Claude“何时该用这个技能”，而不把全部内容塞进上下文。
• 第二层（SKILL.md 正文）：当 Claude 认为该技能与当前任务相关时加载，提供完整步骤和执行指导。
• 第三层（链接文件）：技能目录中的附加文件，Claude 仅在需要时才进一步读取。

这个机制能显著降低 token 消耗，同时保持专业能力密度。

2) 可组合性（Composability）

Claude 可以同时加载多个技能。你的技能需要能与其他技能协作，而不是假设自己是唯一能力源。

3) 可移植性（Portability）

技能在 Claude.ai、Claude Code 和 API 之间行为一致。只要环境满足依赖要求，写一次即可跨端复用。

面向 MCP 构建者：Skills + Connectors

如果你的 MCP 服务器已经可用，最难的连通层基本完成。技能是其上的“知识层”：把你已经掌握的流程和最佳实践固化下来，让 Claude 稳定复现。

如果你还在配置本地 MCP，可参考官方入门文档：Getting started with local MCP servers on Claude Desktop。

厨房类比

MCP 像专业厨房：提供工具、食材和设备访问。

技能像菜谱：提供一步步做出结果的方法。

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

为什么这对 MCP 用户重要

没有技能时：

• 用户连上 MCP 后不知道下一步做什么
• 支持工单反复问“你们这个集成怎么做 X？”
• 每段对话都从零开始
• 用户提示词每次不同，结果不稳定
• 真实问题是工作流指导缺失，但用户会把锅甩给连接器

有技能时：

• 预构建工作流按需自动激活
• 工具使用更稳定、更可靠
• 最佳实践被嵌入每次交互
• 集成学习门槛显著降低

规划与设计（Planning and Design）

从用例开始

在写任何代码前，先明确 2-3 个技能必须支持的具体用例。

优秀用例定义示例：

Use Case: Project Sprint Planning
Trigger: User says "help me plan this sprint" or "create sprint tasks"
Steps:
1. Fetch current project status from Linear (via MCP)
2. Analyze team velocity and capacity
3. Suggest task prioritization
4. Create tasks in Linear with proper labels and estimates
Result: Fully planned sprint with tasks created

你应先问自己：

• 用户到底想完成什么目标？
• 这件事需要哪些多步骤流程？
• 需要哪些工具（Claude 内置 / MCP）？
• 应内嵌哪些领域知识或最佳实践？

常见技能用例分类

Anthropic 内部与早期生态实践中，常见三类：

类别 1：文档与资产生成（Document & Asset Creation）

用于生成一致且高质量的输出，例如文档、演示、应用、设计、代码等。

真实示例：frontend-design skill（另可参考 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 服务器协同。

真实示例：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 skill。

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

关键技巧：

• 按序协调多次 MCP 调用
• 把领域经验固化在流程中
• 提供原本要用户自己补充的关键上下文
• 为 MCP 常见错误设计异常处理

定义成功标准

你如何判断技能有效？这些指标是目标型基线，而非绝对阈值。建议保持评估严谨，同时接受其中会包含一定“体验导向（vibes-based）”判断。相关测量指导与工具仍在持续完善。

定量指标（Quantitative）

• 90% 相关查询可自动触发技能。
  测量方法：准备 10-20 个应触发查询，记录自动加载次数与需显式调用次数。
• 在 X 次工具调用内完成流程。
  测量方法：对比“有技能/无技能”执行同一任务时的工具调用次数与总 token 消耗。
• 每条工作流 0 次 API 调用失败。
  测量方法：在测试运行中监控 MCP 日志，统计重试率与错误码。

定性指标（Qualitative）

• 用户不需要额外提示下一步。
  评估方法：测试中统计你需要重定向/澄清的频率，并收集内测反馈。
• 工作流无需用户纠偏即可完成。
  评估方法：同一请求运行 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）

技能文件夹命名：

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

不要在技能目录放 README.md：

• 技能目录内不应包含 README.md
• 技能文档放在 SKILL.md 或 references/
• 若通过 GitHub 分发，可在仓库根目录放 README 供人类读者使用（见第 4 章）

YAML 前置元数据：最关键部分

Claude 是否加载技能，主要由 frontmatter 决定。这里写对最重要。

最小必需格式

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

起步只需这三行。

字段要求

name（必需）

• 仅允许 kebab-case
• 不能包含空格或大写
• 建议与文件夹同名

description（必需）

• 必须同时包含：技能做什么（WHAT）+ 何时使用（WHEN）
• 长度小于 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 的技能（保留前缀）

原因：frontmatter 会出现在 Claude 系统提示中，恶意内容可能触发指令注入风险。

如何写有效技能

description 字段写法

Anthropic 工程博客指出：这段元数据应“提供足够信息，让 Claude 知道何时使用技能，而无需把全部内容加载进上下文”（见 Equipping Agents for the Real World）。这正是渐进式披露的第一层。

推荐结构：

[What it does] + [When to use it] + [Key capabilities]

优秀示例：

# 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

清晰引用附带资源

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

坚持渐进式披露：SKILL.md 聚焦核心指令；细节文档移入 references/ 并在正文链接。

测试与迭代（Testing and Iteration）

技能测试可按不同严格度实施：

• Claude.ai 手动测试：直接输入查询观察行为，迭代快、无需额外配置。
• Claude Code 脚本化测试：自动化测试用例，便于在修改后重复验证。
• 通过 Skills API 程序化测试：构建评估套件，对固定测试集系统化运行。

选型取决于你的质量要求和技能影响范围。仅供小团队内部使用的技能，与面向上千企业用户的技能，测试需求不会相同。

推荐测试框架

1) 触发测试（Triggering Tests）

目标：确保技能在正确时机加载。

测试项：

• ✅ 对明显任务可触发
• ✅ 对改写表达可触发
• ❌ 对无关话题不触发

示例测试集：

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless ProjectHub skill handles sheets)

2) 功能测试（Functional Tests）

目标：验证技能产出正确结果。

测试项：

• 输出有效
• API 调用成功
• 错误处理生效
• 边界条件覆盖

Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
  - Project created in ProjectHub
  - 5 tasks created with correct properties
  - All tasks linked to project
  - No API errors

3) 性能对比（Performance Comparison）

目标：证明技能相对基线确实提升结果。

可直接复用第 2 章“成功标准”中的指标，示例如下：

Without skill:
- User provides instructions each time
- 15 back-and-forth messages
- 3 failed API calls requiring retry
- 12,000 tokens consumed

With skill:
- Automatic workflow execution
- 2 clarifying questions only
- 0 failed API calls
- 6,000 tokens consumed

使用 skill-creator

skill-creator 可通过 Claude.ai 插件目录使用，也可下载用于 Claude Code。若你已有 MCP 服务器并明确了前 2-3 个核心工作流，通常一次会话（15-30 分钟）即可产出并测试一个可用技能。

创建阶段可做：

• 从自然语言描述自动生成技能
• 生成格式正确、含 frontmatter 的 SKILL.md
• 建议触发短语和文档结构

审查阶段可做：

• 标记常见问题（描述模糊、缺触发词、结构问题）
• 识别潜在过触发/欠触发风险
• 基于技能目标建议测试用例

迭代改进可做：

• 你在实战中遇到边界问题后，可把案例回喂给 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 负责设计与优化建议，不会替你执行自动化测试套件或输出量化评估结果。

基于反馈持续迭代

技能是“活文档”，应持续更新。重点观察以下信号：

触发不足（Undertriggering）

• 该触发时没触发
• 用户需要手动启用
• 用户反复问“这个什么时候用”

解决：在 description 中增加细节和语义边界，技术术语可加入关键词。

过度触发（Overtriggering）

• 无关查询也触发
• 用户主动关闭技能
• 用户困惑技能用途

解决：增加负向触发条件，收紧描述范围。

执行问题（Execution Issues）

• 结果不稳定
• API 调用失败
• 用户必须频繁纠正

解决：改进步骤指令并补充错误处理机制。

分发与共享（Distribution and Sharing）

技能会让你的 MCP 集成更“完整”。在用户比较多个连接器时，带技能的集成通常能更快产生价值，因此相对“仅有 MCP”的方案更具优势。

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

个人用户获取技能：

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

组织级技能：

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

开放标准（An Open Standard）

Agent Skills 已作为开放标准发布（agentskills.io）。与 MCP 一样，技能目标是跨平台可移植：同一技能应可在 Claude 及其他 AI 平台使用。也存在针对特定平台能力做了深度优化的技能；作者可在 compatibility 字段注明。Anthropic 正与生态伙伴共同推进标准落地，并且已经看到早期采用。

通过 API 使用 Skills

在应用、代理系统和自动化流水线中，API 可直接管理并执行技能。

关键能力：

• /v1/skills 端点：列出和管理技能
• 在 Messages API 中通过 container.skills 注入技能
• 通过 Claude Console 做版本管理
• 可结合 Claude Agent SDK 构建自定义代理

API 与 Claude.ai 的使用边界：

注：API 中的 Skills 当前依赖 Code Execution Tool beta 提供的安全执行环境。

实现文档：

• Skills API Quickstart
• Create Custom Skills
• Skills in the Agent SDK

当前推荐分发路径

建议先用 GitHub 公共仓库托管技能，并提供清晰 README（给人类读者；这与技能目录内部不放 README.md 不冲突）和带截图的示例用法。然后在 MCP 文档中加入技能链接、价值说明和快速上手指南。

1. 托管到 GitHub
   公开仓库、清晰安装说明、示例与截图。
2. 在 MCP 仓库文档中联动
   从 MCP 文档跳转到技能，明确“二者一起用”的收益，附快速上手。
3. 写安装指引

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

技能定位（Positioning）

你如何描述技能，决定了用户是否理解其价值并愿意尝试。写 README、文档或宣传文案时可遵循：

讲结果，不讲实现细节：

✅ 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 的协同叙事：

模式与排障（Patterns and Troubleshooting）

下面这些模式来自早期采用者和内部团队的真实技能实践。它们是“常见有效做法”，不是强制模板。

选择方法：问题导向 vs 工具导向

可把它想成逛 Home Depot：

• 你可能带着问题来：“我要修厨房柜子”，店员再给你匹配工具。
• 也可能先买了电钻，再问“具体这活怎么做”。

技能同理：

• 问题导向：“我需要搭建项目工作区” → 技能按顺序编排正确 MCP 调用。用户描述结果，技能处理工具。
• 工具导向：“我已经连好了 Notion MCP” → 技能教 Claude 最优工作流与最佳实践。用户已有访问，技能补充专业方法。

多数技能会偏向其中一种。先明确你的 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）

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

Example: Design-to-development handoff

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

适用：输出质量需要多轮迭代才能达到标准。

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

适用：技能不仅调用工具，还能注入专业知识约束。

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

技能无法上传

错误：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

技能不触发

症状：技能从不自动加载。

修复：重写 description 字段（参考前文好/坏示例）。快速检查：

• 描述是否过于泛化（如“Helps with projects”）？
• 是否包含用户实际会说的触发短语？
• 适用时是否写了相关文件类型？

调试方法：直接问 Claude：When would you use the [skill name] skill? Claude 会复述描述，可据此补漏。

技能触发过于频繁

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

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

解决 2：提高描述具体性

# Too broad
description: Processes documents

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

解决 3：澄清作用范围

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

MCP 连接问题

症状：技能能加载，但 MCP 调用失败。

检查清单：

1. 确认 MCP 已连接
   Claude.ai：Settings > Extensions > [Your Service]，状态应为 Connected。
2. 检查认证
   API Key 是否有效、权限范围是否正确、OAuth token 是否刷新。
3. 独立测试 MCP
   不启用技能直接调用：Use [Service] MCP to fetch my projects。若失败，问题在 MCP 不是技能。
4. 核对工具名
   技能里引用的 MCP 工具名需与文档一致且大小写敏感。

指令未被遵循

症状：技能已加载，但 Claude 未按预期执行。

常见原因：

1. 指令过长
   保持简洁，优先项目符号和编号；细节移到外部参考文件。
2. 关键信息埋得太深
   关键规则放顶部，用 ## Important / ## Critical，必要时重复。
3. 语言含糊

# 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

高级技巧：对关键校验，可把检查逻辑写成脚本并程序化执行，而不是仅靠自然语言指令。代码是确定性的，语言解释不是（可参考 Anthropic Office skills 示例）。

4) 模型“懒惰”问题：可以显式加入执行倾向提示：

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

注：这类提示放在用户 prompt 中，通常比放在 SKILL.md 更有效。

大上下文问题（Large Context Issues）

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

常见原因：

• 技能内容体量过大
• 同时启用过多技能
• 没有使用渐进式披露，导致内容一次性全加载

解决方案：

1. 优化 SKILL.md 体积：把细节文档移至 references/，在正文做链接，建议保持 SKILL.md 小于 5,000 词。
2. 减少并发启用技能数量：若同时启用约 20-50 个技能，建议按需启用，或按能力打包为 skill packs。

资源与参考（Resources and References）

如果你是第一次构建技能，建议先看 Best Practices Guide，再按需查 API 文档。

官方文档（Official Documentation）

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

示例技能（Example Skills）

• 公开技能仓库：GitHub · anthropics/skills
• 包含 Anthropic 官方构建的可定制技能范例

工具与实用程序（Tools and Utilities）

skill-creator：

• Claude.ai 内置，也可用于 Claude Code
• 可从文字描述生成技能草稿
• 可审阅技能并给出优化建议
• 使用示例：Help me build a skill using skill-creator

验证：

• skill-creator 可评估技能质量
• 可直接提问：Review this skill and suggest improvements

获取支持（Getting Support）

技术问题：

• Claude Developers Discord 社区论坛：discord.com/invite/6PPFFzqPDZ

Bug 反馈：

• GitHub Issues：anthropics/skills/issues
• 反馈时建议包含：技能名、报错信息、复现步骤

附录 A：快速检查清单

Reference A: Quick Checklist

上传前后可用此清单做核对。若你想更快启动，可先用 skill-creator 生成初稿，再按此列表查漏补缺。

开始前

• 已识别 2-3 个具体用例
• 已识别所需工具（内置 / MCP）
• 已阅读本指南与示例技能
• 已规划文件夹结构

开发中

• 文件夹命名符合 kebab-case
• SKILL.md 文件存在且拼写准确
• YAML frontmatter 使用 --- 分隔
• name 字段：kebab-case、无空格、无大写
• description 同时包含 WHAT 与 WHEN
• 全文无 XML 标签（< >）
• 指令清晰且可执行
• 已包含错误处理
• 已提供示例
• references 链接清晰

上传前

• 已测试：明显任务可触发
• 已测试：改写请求可触发
• 已验证：无关话题不触发
• 功能测试通过
• 工具集成（若有）可正常工作
• 已压缩为 .zip 文件

上传后

• 在真实对话中测试
• 监控触发不足 / 过度触发
• 收集用户反馈
• 迭代 description 与 instructions
• 更新 metadata 中的版本号

附录 B：YAML 前置元数据参考

Reference 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: [email protected]

安全说明

允许：

• 标准 YAML 类型（字符串、数值、布尔、列表、对象）
• 自定义 metadata 字段
• 较长 description（最多 1024 字符）

禁止：

• XML 尖括号（< >）——安全限制
• 在 YAML 中执行代码（解析器为安全模式）
• 名称以 claude 或 anthropic 开头（保留）

附录 C：完整技能示例

Reference C: Complete Skill Examples

若你需要可直接用于生产的完整技能示例，可参考：

• Document Skills：PDF / DOCX / PPTX / XLSX 创建技能
• Example Skills：覆盖多种工作流模式（GitHub 仓库）
• Partner Skills Directory：查看 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等伙伴技能（Claude Connectors）

这些仓库会持续更新，包含超出本文覆盖范围的额外案例。建议直接克隆后按你的业务场景修改，并作为模板复用。

尾注：claude.ai