Claude官方Skills-构建完全指南：从零到一打造你的AI技能包

javaTodo
0 阅读23分钟

Claude官方Skills-构建完全指南：从零到一打造你的AI技能包

本文已收录到 AI编程一站式导航。本文链接：[03.9 2026 年最佳 AI 编码工具完全指南](code.ai80.vip/ai-tool-gui… 2026 年最佳 AI 编码工具完全指南) 强烈推荐：AI编程巴士网站：稳定纯净的ClaudeCode套餐供应；

写在前面

Skill 是 Claude 生态里一个非常实用的扩展机制——简单来说，就是用一个文件夹把"你希望 Claude 怎么干活"这件事固化下来。不用每次对话都重新解释你的偏好、流程和专业知识，教一次就够了。

这份指南是 Anthropic 官方出品的完整教程，从 Skill 的基础概念到规划设计、测试迭代、分发部署，再到五大实战模式和排错指南，33 页的内容一网打尽。

你可能会好奇：

  • Skill 到底是什么，跟 MCP 是什么关系？
  • YAML frontmatter 怎么写才能让 Claude 精准触发？
  • 有哪些经过验证的设计模式可以直接用？
  • 写完怎么测试、怎么分发给团队？

一个个来。

引言

Skill 是一组打包成简单文件夹的指令集，教会 Claude 如何处理特定任务或工作流。这是定制 Claude 最强大的方式之一。

Skill 在以下场景特别好用：你有可重复的工作流——比如根据规格说明生成前端设计、用统一方法论做调研、按团队风格指南创建文档、或者编排多步骤流程。它们跟 Claude 内置能力（代码执行、文档创建等）配合使用效果很好。如果你在做 MCP 集成，Skill 还能再加一层，把原始的工具访问变成可靠、优化过的工作流。

你会学到什么

  • Skill 结构的技术要求和最佳实践
  • 独立 Skill 和 MCP 增强工作流的设计模式
  • 各种场景下验证有效的模式
  • 如何测试、迭代和分发 Skill

适合谁

  • 想让 Claude 稳定遵循特定工作流的开发者
  • 想让 Claude 按特定方式工作的高级用户
  • 想在组织内标准化 Claude 使用方式的团队

两条路线

你的目标 重点阅读 构建独立 Skill 基础概念 → 规划与设计 → 用例分类 1-2 增强 MCP 集成 "Skills + MCP" 章节 → 用例分类 3

两条路线共享相同的技术要求，按需选择就好。

说实话，按照这份指南走，用 skill-creator 工具，大概一个工作时段就能搭出一个可用的 Skill 并完成测试。

第一章：基础概念

Skill 是什么？

一个 Skill 就是一个文件夹，里面包含：

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

核心设计原则

渐进式披露（Progressive Disclosure）

Skill 用三层体系来管理信息加载：

  • 第一层（YAML frontmatter） ：始终加载到 Claude 的系统提示词中。只提供足够的信息让 Claude 知道什么时候该用这个 Skill，不会加载全部内容。
  • 第二层（SKILL.md 正文） ：当 Claude 判断 Skill 跟当前任务相关时才加载。包含完整指令和指导。
  • 第三层（关联文件） ：Skill 目录内的附加文件，Claude 只在需要时才去查找和读取。

这套渐进式披露机制在保持专业能力的同时，最大限度减少了 Token 消耗。

可组合性（Composability）

Claude 可以同时加载多个 Skill。你的 Skill 应该能跟其他 Skill 和平共处，不要假设自己是唯一可用的能力。

可移植性（Portability）

Skill 在 Claude.ai、Claude Code 和 API 上表现一致。写一次就能在所有平台上跑，前提是运行环境支持 Skill 所需的依赖。

MCP 开发者须知：Skills + 连接器

如果你只做独立 Skill、不涉及 MCP，可以跳到"规划与设计"章节，以后需要再回来看。

如果你已经有一个可用的 MCP 服务器，最难的部分已经搞定了。Skill 是在 MCP 之上的知识层——把你已经掌握的工作流和最佳实践固化下来，让 Claude 能一致地执行。

打个比方：MCP 提供的是专业厨房——工具、食材、设备一应俱全。Skill 提供的是菜谱——一步步教你怎么做出好菜。两者结合，用户不用自己琢磨每一步该怎么做。

MCP（连接层） Skills（知识层） 把 Claude 连接到你的服务（Notion、Asana、Linear 等） 教 Claude 如何有效使用你的服务 提供实时数据访问和工具调用 捕获工作流和最佳实践 Claude 能做什么 Claude 该怎么做

没有 Skill 的痛点

  • 用户连上 MCP 但不知道接下来该干嘛
  • 不断收到"怎么用你们的集成做 X"的工单
  • 每次对话都从零开始
  • 不同用户提示词不同，结果不一致
  • 用户把工作流问题归咎于你的连接器

有 Skill 后的改变

  • 预置工作流在需要时自动激活
  • 工具调用一致且可靠
  • 最佳实践嵌入每次交互
  • 集成学习曲线大幅降低

第二章：规划与设计

从用例出发

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

好的用例定义长这样：

用例：项目 Sprint 规划
触发条件：用户说"帮我规划这个 sprint"或"创建 sprint 任务"
步骤：
1. 通过 MCP 从 Linear 获取当前项目状态
2. 分析团队速度和产能
3. 建议任务优先级
4. 在 Linear 中创建带标签和估时的任务
结果：Sprint 规划完成，任务全部创建

规划时问自己：

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

三种常见用例分类

Anthropic 在实践中观察到三种常见模式：

分类 1：文档与资产创建

适用场景：创建一致的、高质量的输出——文档、演示文稿、应用、设计、代码等。

实际案例：frontend-design Skill（另外还有 docx、pptx、xlsx、ppt 等 Skill）

"创建高设计质量的、有辨识度的、生产级的前端界面。在构建 Web 组件、页面、海报或应用时使用。"

核心技巧：

  • 嵌入风格指南和品牌标准
  • 用模板结构保证输出一致性
  • 定稿前跑质量检查清单
  • 不需要外部工具——直接用 Claude 内置能力

分类 2：工作流自动化

适用场景：受益于统一方法论的多步骤流程，包括跨多个 MCP 服务器的协调。

实际案例：skill-creator Skill

"创建新 Skill 的交互式指南。引导用户完成用例定义、frontmatter 生成、指令编写和验证。"

核心技巧：

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

分类 3：MCP 增强

适用场景：为 MCP 服务器提供的工具访问添加工作流指导。

实际案例：sentry-code-review Skill（来自 Sentry）

"利用 Sentry 的错误监控数据（通过 MCP 服务器），自动分析并修复 GitHub Pull Request 中检测到的 Bug。"

核心技巧：

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

定义成功标准

怎么知道 Skill 是否好用？以下是一些参考基准——更多是方向性指标，不是精确阈值。目前 Anthropic 正在开发更完善的测量工具。

定量指标：

指标 目标 怎么测 Skill 在相关查询中被触发 90% 跑 10-20 个测试查询，统计自动触发 vs 手动调用的比例 工作流在 X 次工具调用内完成 对比有无 Skill 同一任务对比，统计工具调用次数和总 Token 消耗 每个工作流 API 调用失败数 0 监控 MCP 服务器日志，跟踪重试率和错误码

定性指标：

  • 用户不需要提示 Claude 下一步该做什么
  • 工作流无需用户纠正即可完成
  • 跨会话结果一致

技术要求

文件结构

your-skill-name/
├── SKILL.md              # 必需 - 主 Skill 文件
├── 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（可选） ：开源时使用，常见 MIT、Apache-2.0

compatibility（可选） ：1-500 字符，说明环境要求

metadata（可选） ：

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

安全限制

Frontmatter 中禁止：

  • XML 尖括号（< >）
  • Skill 名称中包含"claude"或"anthropic"（保留字）

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

写好 description 字段

引用 Anthropic 工程博客的话：

"这些元数据……提供了刚好足够的信息让 Claude 知道什么时候该用每个 Skill，而不需要把所有内容都加载到上下文中。"

这是渐进式披露的第一层。

结构：[做什么] + [什么时候用] + [核心能力]

好的 description：

# 具体且可操作
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：

# 太模糊
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: [第一个主要步骤]
清晰说明这一步做什么。

示例：
```bash
python scripts/fetch_data.py --project-id PROJECT_ID

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

（根据需要添加更多步骤）

Examples

Example 1: [常见场景]

用户说："Set up a new marketing campaign" 操作：

  1. 通过 MCP 获取现有活动
  2. 用提供的参数创建新活动 结果：活动创建完成，附确认链接

Troubleshooting

Error: [常见错误消息]

原因：[为什么会出现] 解决：[怎么修]


### 指令编写最佳实践

**要具体、可执行**：

```markdown
# ✅ 好：
运行 `python scripts/validate.py --input {filename}` 检查数据格式。
如果验证失败，常见问题包括：
- 缺少必需字段（添加到 CSV 中）
- 日期格式无效（使用 YYYY-MM-DD）

# ❌ 坏：
在继续之前验证一下数据。

包含错误处理：

## Common Issues

### MCP Connection Failed
如果看到 "Connection refused"：
1. 确认 MCP 服务器在运行：检查 Settings > Extensions
2. 确认 API key 有效
3. 尝试重新连接：Settings > Extensions > [Your Service] > Reconnect

清晰引用捆绑资源：

在写查询之前，查阅 `references/api-patterns.md` 了解：
- 限流策略
- 分页模式
- 错误码和处理方式

善用渐进式披露：SKILL.md 聚焦核心指令，详细文档放到 references/ 里并做链接引用。

第三章：测试与迭代

Skill 可以根据需要选择不同级别的测试严格度：

  • Claude.ai 手动测试：直接跑查询观察行为。迭代快，不需要额外设置。
  • Claude Code 脚本测试：自动化测试用例，代码变更后可重复验证。
  • Skills API 编程测试：构建评估套件，系统性地对定义好的测试集进行验证。

根据质量要求和 Skill 的受众规模来选择方案。小团队内部用的 Skill 和部署给上千企业用户的 Skill，测试需求天差地别。

小贴士：先在单个任务上迭代，成功后再扩展。实践中最有效的方法是在一个有挑战的任务上反复调试直到 Claude 能搞定，然后把成功的方法提炼成 Skill。这比一上来就做广泛测试效率高得多。

推荐测试方法

有效的 Skill 测试通常覆盖三个方面：

1. 触发测试

目标：确保 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"
  （除非你的 Skill 确实处理表格）

2. 功能测试

目标：验证 Skill 产出正确的结果。

测试：创建包含 5 个任务的项目
输入：项目名 "Q4 Planning"，5 个任务描述
执行：Skill 执行工作流
验证：
- 项目在 ProjectHub 中创建成功
- 5 个任务创建成功且属性正确
- 所有任务关联到项目
- 没有 API 错误

3. 性能对比

目标：证明 Skill 确实改善了结果。

对比项 不用 Skill 用 Skill 用户操作 每次都要提供指令 自动执行工作流 来回对话 15 条消息 只需 2 个澄清问题 API 调用失败 3 次需要重试 0 次 Token 消耗 12,000 6,000

使用 skill-creator

skill-creator 是 Anthropic 提供的辅助工具，在 Claude.ai 和 Claude Code 中都可用。如果你有 MCP 服务器并且知道 2-3 个核心工作流，用它一个工作时段就能搭出一个可用的 Skill。

它能做什么：

  • 根据自然语言描述生成 Skill
  • 产出格式正确的 SKILL.md 和 frontmatter
  • 建议触发短语和结构
  • 审查并发现常见问题（描述模糊、触发条件缺失、结构问题）
  • 识别过度/不足触发的风险
  • 根据 Skill 用途建议测试用例

用法：直接跟 Claude 说"Use the skill-creator skill to help me build a skill for [your use case]"

注意：skill-creator 帮你设计和优化 Skill，但不会执行自动化测试套件或生成定量评估结果。

基于反馈迭代

Skill 是活的文档，要根据使用情况持续优化。

触发不足的信号：

  • Skill 该加载的时候没加载
  • 用户需要手动启用
  • 收到"什么时候该用这个 Skill"的支持问题

→ 解决办法：在 description 中加入更多细节和关键词，特别是技术术语。

触发过度的信号：

  • Skill 在不相关的查询中加载
  • 用户主动禁用它
  • 对 Skill 用途产生困惑

→ 解决办法：添加负面触发条件，更具体地限定范围。

执行问题：

  • 结果不一致
  • API 调用失败
  • 需要用户纠正

→ 解决办法：改进指令，增加错误处理。

第四章：分发与共享

Skill 让你的 MCP 集成更完整。用户在选择连接器时，有 Skill 的方案能更快体现价值，比纯 MCP 方案更有竞争力。

当前分发方式（2026 年 1 月）

个人用户安装 Skill：

  1. 下载 Skill 文件夹
  2. 打包成 zip（如需要）
  3. 通过 Claude.ai 的 Settings > Capabilities > Skills 上传
  4. 或放到 Claude Code 的 skills 目录

组织级 Skill：

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

开放标准

Anthropic 已经把 Agent Skills 发布为开放标准。跟 MCP 一样，他们认为 Skill 应该可以跨工具和平台使用——同一个 Skill 不管你用 Claude 还是其他 AI 平台都能跑。不过有些 Skill 是专门为特定平台的能力设计的，作者可以在 compatibility 字段里标注。

通过 API 使用 Skills

对于编程场景——比如构建应用、Agent 或自动化工作流——API 提供了对 Skill 管理和执行的直接控制。

核心能力：

  • /v1/skills 端点用于列出和管理 Skill
  • 通过 Messages API 的 container.skills 参数添加 Skill
  • 在 Claude Console 中进行版本控制和管理
  • 与 Claude Agent SDK 配合构建自定义 Agent

何时用 API vs Claude.ai：

使用场景 推荐平台 终端用户直接使用 Skill Claude.ai / Claude Code 开发过程中的手动测试和迭代 Claude.ai / Claude Code 个人临时工作流 Claude.ai / Claude Code 应用程序编程调用 Skill API 大规模生产部署 API 自动化流水线和 Agent 系统 API

注意：API 中的 Skills 需要 Code Execution Tool beta，它提供了 Skill 运行所需的安全环境。

推荐做法

先在 GitHub 上托管 Skill：公开仓库、清晰的 README（给人看的，不是放在 Skill 文件夹里的）、示例用法和截图。然后在 MCP 文档中添加链接，解释两者结合的价值，并提供快速入门指南。

安装指南模板：

## Installing the [Your Service] Skill

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

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

3. 启用并测试：
   - 开启 [Your Service] Skill
   - 确保 MCP 服务器已连接
   - 问 Claude："Set up a new project in [Your Service]"

写好 Skill 介绍

聚焦成果，而不是功能：

# ✅ 好：
"ProjectHub Skill 让团队几秒钟就能搭好完整的项目工作区
——包括页面、数据库和模板——而不是花 30 分钟手动设置。"

# ❌ 坏：
"ProjectHub Skill 是一个包含 YAML frontmatter 和 Markdown 指令的文件夹，
调用我们的 MCP 服务器工具。"

突出 MCP + Skills 的组合故事：

"我们的 MCP 服务器让 Claude 能访问你的 Linear 项目。我们的 Skill 教 Claude 你们团队的 Sprint 规划工作流。两者结合，实现 AI 驱动的项目管理。"

第五章：模式与排错

以下模式来自早期用户和内部团队的实践。它们代表了经过验证的常见做法，不是死板的模板。

选择你的方式：问题先行 vs 工具先行

打个比方，就像去建材超市。你可能带着一个问题进去——"我要修厨房柜子"——店员帮你找到合适的工具。也可能是你看中了一把新电钻，想知道怎么用它干你的活。

Skill 也是一样：

  • 问题先行："我需要搭建项目工作区"→ Skill 按正确顺序编排 MCP 调用。用户描述结果，Skill 搞定工具。
  • 工具先行："我连上了 Notion MCP"→ Skill 教 Claude 最优工作流和最佳实践。用户有了工具访问，Skill 提供专业知识。

大多数 Skill 偏向其中一个方向。搞清楚哪种适合你的用例，有助于选择下面的模式。

模式 1：顺序工作流编排

适用场景：用户需要按特定顺序执行的多步骤流程。

## Workflow: Onboard New Customer

### Step 1: Create Account
调用 MCP 工具：`create_customer`
参数：name, email, company

### Step 2: Setup Payment
调用 MCP 工具：`setup_payment_method`
等待：支付方式验证通过

### Step 3: Create Subscription
调用 MCP 工具：`create_subscription`
参数：plan_id, customer_id（来自 Step 1）

### Step 4: Send Welcome Email
调用 MCP 工具：`send_email`
模板：welcome_email_template

核心技巧：明确的步骤顺序、步骤间依赖、每步验证、失败时的回滚指令。

模式 2：多 MCP 协调

适用场景：工作流跨越多个服务。

## Phase 1: Design Export (Figma MCP)
1. 从 Figma 导出设计资产
2. 生成设计规格
3. 创建资产清单

## Phase 2: Asset Storage (Drive MCP)
1. 在 Drive 中创建项目文件夹
2. 上传所有资产
3. 生成可分享链接

## Phase 3: Task Creation (Linear MCP)
1. 创建开发任务
2. 将资产链接附加到任务
3. 分配给工程团队

## Phase 4: Notification (Slack MCP)
1. 在 #engineering 频道发布交接摘要
2. 包含资产链接和任务引用

核心技巧：清晰的阶段划分、MCP 之间的数据传递、进入下一阶段前验证、集中化错误处理。

模式 3：迭代优化

适用场景：输出质量通过迭代改进。

## Initial Draft
1. 通过 MCP 获取数据
2. 生成初稿报告
3. 保存到临时文件

## Quality Check
1. 运行验证脚本：`scripts/check_report.py`
2. 识别问题：缺少章节、格式不一致、数据验证错误

## Refinement Loop
1. 逐个解决识别到的问题
2. 重新生成受影响的章节
3. 重新验证
4. 达到质量阈值前重复

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

核心技巧：明确的质量标准、迭代改进、验证脚本、知道什么时候该停。

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

适用场景：同一目标，不同上下文用不同工具。

## Decision Tree
1. 检查文件类型和大小
2. 确定最佳存储位置：
   - 大文件 (>10MB)：使用云存储 MCP
   - 协作文档：使用 Notion/Docs MCP
   - 代码文件：使用 GitHub MCP
   - 临时文件：使用本地存储

## Execute Storage
根据决策调用对应 MCP 工具，应用服务特定的元数据，生成访问链接。

## Provide Context
向用户解释为什么选择了这个存储方式。

核心技巧：清晰的决策标准、备选方案、对选择过程保持透明。

模式 5：领域专业知识嵌入

适用场景：Skill 需要添加超越工具访问的专业知识。

## Before Processing (Compliance Check)
1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 检查制裁名单
   - 验证司法管辖区许可
   - 评估风险等级
3. 记录合规决策

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

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

核心技巧：领域专业知识嵌入逻辑、行动前先合规、全面的文档记录、清晰的治理结构。

排错指南

Skill 上传失败

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

  • 原因：文件没有精确命名为 SKILL.md
  • 解决：重命名为 SKILL.md（区分大小写）

错误："Invalid frontmatter"

  • 原因：YAML 格式问题
# ❌ 缺少分隔符
name: my-skill
description: Does things

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

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

错误："Invalid skill name"

  • 原因：名称有空格或大写
  • My Cool Skill ❌ → my-cool-skill ✅

Skill 不触发

症状：Skill 从不自动加载。

排查清单：

  • description 是不是太笼统了？（"Helps with projects" 不行）
  • 有没有包含用户实际会说的触发短语？
  • 涉及特定文件类型的有没有提到？

调试方法：直接问 Claude "When would you use the [skill name] skill?" —— Claude 会引用 description 内容，根据缺失的部分调整。

Skill 触发太频繁

症状：Skill 在不相关的查询中加载。

解决方案：

  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. 更具体：

# 太宽泛
description: Processes documents
# 更具体
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 连接问题

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

排查步骤：

  1. 确认 MCP 服务器已连接（Claude.ai: Settings > Extensions > 应显示 "Connected"）
  2. 检查认证（API key 有效且未过期、权限/作用域正确、OAuth token 已刷新）
  3. 独立测试 MCP（不通过 Skill，直接让 Claude 调用 MCP 工具。如果这也失败，问题出在 MCP 不在 Skill）
  4. 验证工具名称（Skill 引用的 MCP 工具名是否正确，工具名区分大小写）

指令没被遵循

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

常见原因及解决：

  1. 指令太啰嗦：保持简洁，用项目符号和编号列表，详细参考放到单独文件。
  2. 关键指令被埋没：把关键指令放在顶部，用 ## Important 或 ## Critical 标题，必要时重复关键点。
  3. 表述模糊：
# ❌ 坏：
Make sure to validate things properly

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

4. 模型"偷懒"：加入明确鼓励（注意：加在用户提示词中比加在 SKILL.md 里更有效）：

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

进阶技巧：对于关键验证，考虑捆绑一个脚本来做程序化检查，而不是纯靠语言指令。代码是确定性的，语言理解不是。参考 Office Skills 中的这种模式。

大上下文问题

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

解决方案：

  1. 优化 SKILL.md 大小：把详细文档移到 references/，用链接引用，SKILL.md 控制在 5,000 词以内。
  2. 减少同时启用的 Skill 数量：如果同时启用了超过 20-50 个 Skill，考虑按功能分组，选择性启用。

第六章：资源与参考

如果你是第一次构建 Skill，建议先看最佳实践指南，然后按需查阅 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

公开 Skills 仓库：

  • GitHub: anthropics/skills
  • 包含 Anthropic 创建的 Skill，可以直接定制使用

工具

skill-creator：

  • Claude.ai 和 Claude Code 中内置
  • 可以根据描述生成 Skill
  • 审查并提供改进建议
  • 使用方式："Help me build a skill using skill-creator"

获取支持

  • 技术问题：Claude Developers Discord 社区论坛
  • Bug 报告：GitHub Issues (anthropics/skills/issues)，附上 Skill 名称、错误信息和复现步骤

常见问题

Q: Skill 跟 Prompt 模板有什么区别？

A: Prompt 模板是一次性的——每次用都要手动粘贴或调用。Skill 是持久化的知识包，Claude 能自动识别什么时候该用、怎么用。而且 Skill 支持多文件结构（脚本、参考文档、资产），不只是一段文本。

Q: 一个 Skill 的 SKILL.md 应该多长？

A: 核心指令控制在 5,000 词以内。详细的参考文档、API 指南等放到 references/ 目录里。太长的 SKILL.md 会影响性能。

Q: 可以同时启用多少个 Skill？

A: 技术上没有硬限制，但同时启用 20-50 个以上可能导致响应变慢或质量下降。建议按功能分组，按需启用。

Q: Skill 可以跨平台使用吗？

A: 可以。同一个 Skill 在 Claude.ai、Claude Code 和 API 上都能用。不过如果 Skill 依赖特定环境（比如需要 Python 运行时），要确保目标平台支持。可以在 compatibility 字段中标注环境要求。

Q: 怎么快速入门？

A: 最快的方式：在 Claude.ai 中使用 skill-creator。告诉 Claude "Help me build a skill using skill-creator for [你的用例]"，它会引导你完成整个流程——用例定义、frontmatter 生成、指令编写、验证，一个工作时段搞定。

原文链接：resources.anthropic.com/hubfs/The-C…

本文已收录到 AI编程一站式导航。本文链接：[03.9 2026 年最佳 AI 编码工具完全指南](code.ai80.vip/ai-tool-gui… 2026 年最佳 AI 编码工具完全指南) 强烈推荐：AI编程巴士网站：稳定纯净的ClaudeCode套餐供应；

avatar
文章
阅读
粉丝