Claude Code 技能系统完全指南

什么是 Claude Code Skill

Claude Code 的技能系统（Skills）本质上是一种结构化的 prompt，通过 SKILL.md 文件来扩展 Claude 的能力。你可以把它理解为：给 Claude 一套可复用的”操作手册”，让它在特定场景下表现得更专业、更一致。

和传统的 prompt template 不同，Skill 有几个核心优势：

可复用：写一次，跨项目、跨会话使用
可分享：团队成员之间共享工作流
可组合：Skill 可以调用 MCP 工具、编排多步骤流程
渐进式披露：Claude 只在需要时才加载详细指令，节省 context window

一句话总结：Skill = 可复用的结构化指令 + 可选的工具调用能力。

如果按 PDF 的学习路径来看，可以分两条线：

构建独立 skill：优先看基础、规划设计、文档/工作流两类模式
增强 MCP 集成：优先看 skill + MCP 协同、MCP 增强与多服务编排

在你已有明确用例和 MCP 连接前提下，首个可工作的 skill 通常可以在 15-30 分钟内做出初版。

核心设计原则

Anthropic 在官方指南中反复强调了几个设计哲学，理解这些比记住语法更重要。

1. 渐进式披露（Progressive Disclosure）

这是整个技能系统最核心的设计理念。Skill 采用三级信息架构：

级别	触发时机	内容	对应区域
L1	始终加载在系统提示中	名称 + 简短描述	YAML frontmatter 的 `name` + `description`
L2	Skill 被激活时	完整的系统级 prompt	`SKILL.md` 的 body
L3	执行过程中按需加载	详细参考文档、示例代码	通过 `Read` 工具读取外部文件

为什么要这样设计？因为 context window 是稀缺资源。如果把所有指令一次性塞给 Claude，既浪费 token 又会降低指令的优先级。渐进式披露确保 Claude 在每个阶段只获取它当前需要的信息。

markdown

<!-- L1: YAML frontmatter - 极简描述 -->
---
name: deploy
description: 自动化部署到生产环境
---

<!-- L2: Body - 核心指令 -->
## 部署流程
1. 运行测试
2. 构建项目
3. 推送到远端

<!-- L3: 按需读取外部文件 -->
如果遇到 SSL 证书问题，读取 `docs/ssl-troubleshooting.md` 获取详细解决方案。

2. 明确优于隐含

不要假设 Claude “应该知道”你想要什么。Skill 中的每一条指令都应该是明确、具体、可执行的。

反面示例：

markdown

帮我写好代码

正面示例：

markdown

## 代码规范
- 使用 TypeScript strict mode
- 函数参数超过 3 个时使用对象解构
- 错误处理使用 Result 模式而非 try-catch
- 所有公共 API 必须有 JSDoc 注释

3. 动词驱动，面向行动

Skill 不是文档，是操作手册。每条指令都应该告诉 Claude “做什么”，而不是”是什么”。

markdown

<!-- 好：动词驱动 -->
1. 读取 `package.json` 获取项目依赖
2. 运行 `bun run test` 确认测试通过
3. 执行 `bun run build` 生成构建产物
4. 使用 `git push` 推送到远端

<!-- 不好：描述性的 -->
项目使用 bun 作为包管理器，测试框架是 vitest...

4. 约束优于建议

当你想要 Claude 遵循特定行为时，使用约束性语言而不是建议性语言。

markdown

<!-- 好：约束性 -->
NEVER delete files without user confirmation
ALWAYS run tests before committing
MUST use semantic commit messages

<!-- 不好：建议性 -->
It would be nice to run tests before committing
Consider using semantic commit messages

5. 可组合性（Composability）

Claude 可以在同一轮对话中同时加载多个 skill。设计 skill 时不要假设“只有我一个 skill 在工作”，而要尽量做到：

与其他 skill 的职责边界清晰
不重写全局规则，避免冲突
输出可被其他 skill 继续消费

6. 可移植性（Portability）

同一个 skill 在 Claude.ai、Claude Code、API 中应尽量保持一致行为。实践上，这意味着：

核心指令尽量与平台无关
把环境依赖写进 compatibility 或说明文档
需要外部能力时，显式声明 MCP 或系统依赖

对 MCP 构建者：连接器 + Skill

可以把 MCP 和 skill 理解为“连接能力 + 领域流程”：

维度	MCP（连接性）	Skill（知识层）
作用	连接工具和实时数据	教 Claude 如何正确使用这些工具
输出	“能做什么”	“应该怎么做”
价值	提供能力入口	提供稳定、可复用的工作流

如果只有 MCP 没有 skill，用户往往知道“连上了”，但不知道“下一步怎么做”；skill 的作用就是把最佳实践固化下来，显著降低学习成本。

SKILL.md 文件结构

文件位置

一个 skill 是一个文件夹，不是单个 .md 文件。推荐结构如下：

text

your-skill-name/
├── SKILL.md        # 必需，且必须是这个精确名称（区分大小写）
├── scripts/        # 可选，可执行脚本（Python/Bash 等）
├── references/     # 可选，按需加载文档
└── assets/         # 可选，模板/字体/图标等资源

命名和目录的硬规则：

SKILL.md 只能叫 SKILL.md，skill.md/SKILL.MD 都不行
skill 文件夹名必须用 kebab-case（如 notion-project-setup）
文件夹名不要空格、下划线、大写
skill 文件夹内不要放 README.md（说明文档放 SKILL.md 或 references/）

YAML Frontmatter

每个 Skill 文件的头部必须包含 YAML frontmatter，定义元数据：

yaml

---
name: skill-name           # 必填：调用名称（/skill-name）
description: |             # 必填：简短描述（L1 级别）
  一句话说明这个 skill 做什么
allowed_tools:             # 可选：skill 可使用的工具白名单
  - Bash(bun run build)
  - Read
  - Write
  - Edit
  - Glob
  - Grep
allowed_tools_on_approve:  # 可选：用户批准后可使用的工具
  - Bash(git push)
---

关键字段说明

name：Skill 的标识符（用于匹配和显式调用）。命名建议：

使用 kebab-case（my-skill-name）
简短且语义化（deploy、review-pr、gen-cover）

description：L1 级别的描述信息。当用户浏览可用 skills 时看到的内容。要求：

一句话说清楚 skill 做什么
不要包含实现细节

allowed_tools：工具白名单。这是一个重要的安全机制 —— 你可以精确控制 skill 能调用哪些工具。格式支持参数级别的控制：

yaml

allowed_tools:
  - Bash(bun run test)      # 只允许运行这个特定命令
  - Bash(bun run build)     # 只允许运行这个特定命令
  - Read                    # 允许读取任意文件
  - Edit                    # 允许编辑任意文件

allowed_tools_on_approve：需要用户二次确认的工具。适用于有破坏性的操作（如 git push、rm 等）。

PDF 里还强调了几个经常被忽略但很关键的字段与限制：

license（可选）：开源分发时建议填写（如 MIT、Apache-2.0）。

compatibility（可选）：声明运行环境要求（目标产品、系统依赖、网络要求等）。

metadata（可选）：自定义键值，建议放作者、版本、MCP 服务名等。

yaml

---
name: projecthub-planner
description: 管理 ProjectHub 冲刺规划流程。用于用户提到 sprint、task creation、project planning 等场景。
license: MIT
compatibility: Claude Code with network access and ProjectHub MCP connected
metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub
---

安全限制（必须遵守）

frontmatter 中不要出现 XML 尖括号 < >
description 要同时写清“做什么 + 何时用”，且控制在 1024 字符内
skill 名称不要使用 Claude 或 Anthropic（保留名称）

Skill Body 编写指南

Frontmatter 之后的内容就是 skill 的核心指令（L2 级别），这部分是 Claude 实际执行时会加载的完整 prompt。

结构模板

一个好的 skill body 通常包含以下部分：

markdown

---
name: example-skill
description: 示例 skill
---

## 概述
简要说明这个 skill 的目标和适用场景。

## 前置检查
在开始之前需要验证的条件。
- 检查必要的文件是否存在
- 验证环境变量是否配置

## 执行步骤
1. 第一步：具体操作
2. 第二步：具体操作
3. 第三步：具体操作

## 约束条件
- NEVER: 禁止的操作
- ALWAYS: 必须遵守的规则

## 错误处理
遇到特定错误时的处理方式。

## 输出格式
最终输出应该是什么格式/结构。

编写技巧

使用 Markdown 结构化：Claude 对 Markdown 格式的理解非常好，善用标题、列表、代码块来组织指令。

关键信息前置：把最重要的指令放在 body 的开头。Claude 对靠近开头的内容权重更高。

包含示例：给 Claude 看期望的输入/输出示例，比文字描述有效得多：

markdown

## Commit Message 格式

遵循 Conventional Commits 规范：

**好的示例：**
- `feat(auth): add OAuth2 login flow`
- `fix(api): handle null response from payment gateway`
- `refactor(db): migrate from raw SQL to Drizzle ORM`

**不好的示例：**
- `update code`
- `fix bug`
- `wip`

条件分支：当 skill 需要根据不同情况采取不同行动时，明确写出判断逻辑：

markdown

## 部署策略

1. 检查当前分支：
   - 如果是 `main` 分支 → 部署到生产环境
   - 如果是 `staging` 分支 → 部署到预发布环境
   - 如果是其他分支 → 提示用户确认目标环境

三大用例类别

1. 文档与内容创建

最简单也是最常见的 skill 类型。通过详细的格式规范和示例，让 Claude 生成符合团队标准的文档。

典型场景：

生成 API 文档
撰写 changelog
创建 PR 描述模板
生成技术设计文档（RFC/ADR）

yaml

---
name: write-adr
description: 生成架构决策记录（ADR）
allowed_tools:
  - Read
  - Write
  - Glob
---

markdown

## 任务
创建一个新的架构决策记录（ADR）。

## 步骤
1. 读取 `docs/adr/` 目录，找到最新的 ADR 编号
2. 创建新文件 `docs/adr/NNNN-title.md`
3. 使用以下模板填充内容：
   - 标题
   - 状态（Proposed）
   - 上下文（为什么要做这个决策）
   - 决策（选择了什么方案）
   - 后果（正面和负面影响）
4. 让用户审阅并确认

## 约束
- ADR 编号必须递增
- 状态只能是：Proposed, Accepted, Deprecated, Superseded
- 必须包含至少一个替代方案的讨论

2. 工作流自动化

这类 skill 编排多个步骤，自动完成一个完整的工作流。通常涉及文件操作、Git 命令、构建工具等。

典型场景：

发布流程（build → test → tag → push → deploy）
PR 审查流程
项目初始化
数据迁移

yaml

---
name: release
description: 执行版本发布流程
allowed_tools:
  - Bash(bun run test)
  - Bash(bun run build)
  - Bash(bun version)
  - Read
  - Edit
allowed_tools_on_approve:
  - Bash(git tag)
  - Bash(git push)
---

markdown

## 发布流程

1. **前置检查**
   - 确认当前在 `main` 分支
   - 确认工作区干净（无未提交更改）
   - 运行 `bun run test` 确保测试通过

2. **版本更新**
   - 询问用户发布类型（patch/minor/major）
   - 更新 `package.json` 中的版本号
   - 更新 CHANGELOG.md

3. **构建验证**
   - 运行 `bun run build`
   - 确认构建成功

4. **发布**（需用户确认）
   - 创建 git tag
   - 推送到远端
   - 输出发布摘要

3. MCP 工具增强

这是最强大也最复杂的 skill 类型。通过集成 MCP（Model Context Protocol）服务器，skill 可以与外部系统交互 —— 数据库、API、浏览器、设计工具等。

典型场景：

数据库查询与迁移
浏览器自动化测试
设计系统同步（Figma → 代码）
第三方 API 集成

yaml

---
name: db-migrate
description: 执行数据库迁移
allowed_tools:
  - mcp__postgres__query
  - Read
  - Write
  - Bash(bun run drizzle-kit generate)
  - Bash(bun run drizzle-kit push)
---

markdown

## 数据库迁移流程

读取当前 schema 文件
使用 MCP postgres 工具查询当前数据库状态
生成迁移文件：`bun run drizzle-kit generate`
在预览环境中执行迁移并验证
让用户确认后推送到生产环境

定义成功标准（很多文章会漏掉）

只写流程不够，必须定义“怎样算有效”。PDF 给出的建议是量化 + 定性双轨评估：

量化指标示例

触发率：在 10-20 条“应触发”测试请求里，自动触发接近 90%
效率：和无 skill 的基线相比，工具调用次数与 token 消耗显著下降
稳定性：关键工作流中的 API 失败次数趋近于 0

定性指标示例

用户无需频繁提示“下一步该做什么”
同类请求多次执行，结构和质量保持一致
新用户在最小指导下也能完成任务

先选框架：问题优先 vs 工具优先

这部分在 PDF 中非常实用，但常被省略：

问题优先：用户先描述结果（如“帮我完成 sprint 规划”），skill 再自动编排工具
工具优先：用户先接入 MCP（如 Notion/Linear），skill 负责注入最佳实践

大多数场景会偏向其中一种。先明确你的主路径，再决定 skill 的结构和提示语言。

五大设计模式

Anthropic 官方指南总结了五种经过验证的 skill 设计模式，每种解决不同类型的问题。

模式 1：顺序编排（Sequential Orchestration）

最基础的模式。按固定顺序执行一系列步骤，前一步的输出作为后一步的输入。

plaintext

Step 1 → Step 2 → Step 3 → Done

适用场景：发布流程、CI/CD pipeline、文件处理流水线

关键要点：

每一步必须有明确的完成条件
定义步骤之间的数据传递方式
任何一步失败时的回滚策略

markdown

## 部署流程（顺序编排）
`bun run type-check` → 类型检查通过
`bun run test` → 所有测试通过
`bun run build` → 构建成功，输出到 dist/
`git push origin main` → 推送到远端
确认 Cloudflare Pages 部署成功

模式 2：多 MCP 协调（Multi-MCP Coordination）

当一个 skill 需要同时使用多个 MCP 服务器时使用。例如：从数据库读取数据 → 在浏览器中验证 → 发送通知。

plaintext

MCP Server A ─┐
              ├→ Skill 协调逻辑 → 输出
MCP Server B ─┘

适用场景：跨系统数据同步、全栈测试、复杂集成任务

关键要点：

明确每个 MCP 服务器的职责
处理跨系统的错误传播
注意不同 MCP 工具的响应格式差异

通过多轮循环逐步改进输出质量。每一轮产出 → 评估 → 修改 → 再评估。

plaintext

Draft → Review → Revise → Review → Final

适用场景：代码审查、文档打磨、UI 调整、性能优化

关键要点：

定义明确的”完成标准”（何时停止迭代）
设置最大迭代次数（防止无限循环）
每轮记录改进了什么

markdown

## 代码审查（迭代优化）

重复以下循环，最多 3 轮：

分析代码，列出问题（安全、性能、可维护性）
按严重程度排序
修复最高优先级的问题
重新检查是否引入新问题
如果没有 high/critical 问题 → 完成

模式 4：上下文感知工具选择（Context-Aware Tool Selection）

目标相同，但根据上下文自动选择不同工具路径。

plaintext

Inspect Context → Select Best Tool → Execute → Explain Why

适用场景：文件存储、渠道分发、跨系统同步、路由决策

关键要点：

决策标准必须显式（文件大小、协作需求、数据敏感级别等）
为每类分支准备 fallback 方案
向用户解释“为什么选这个工具”

markdown

## 智能文件存储

1. 检查文件类型与大小
2. 选择存储位置：
   - 大文件（>10MB）→ 云存储 MCP
   - 协作文档 → Notion/Docs MCP
   - 代码文件 → GitHub MCP
   - 临时文件 → 本地存储
3. 执行对应 MCP 调用并返回访问链接
4. 说明选择理由

模式 5：领域特定智能（Domain-Specific Intelligence）

Skill 不只是“调用工具”，还要把行业规则和治理逻辑编码进去。

plaintext

Fetch Data → Apply Domain Rules → Decide → Act → Audit

适用场景：金融合规、医疗流程、法务审阅、风控审批

关键要点：

把专业规则写入流程，而不是依赖用户临时补充
先做合规/约束判断，再执行动作
全流程可审计，输出决策依据

markdown

## 支付处理（含合规）

1. 通过 MCP 获取交易上下文
2. 执行合规检查：
   - 制裁名单校验
   - 司法辖区校验
   - 风险评级
3. 若通过：
   - 调用支付 MCP 处理交易
4. 若不通过：
   - 标记人工审查
   - 创建合规案例
5. 记录审计日志与处理结论

Skill 与 MCP 的集成

MCP（Model Context Protocol）是 Claude Code 与外部世界交互的桥梁。Skill 通过 allowed_tools 字段声明它需要使用的 MCP 工具。

MCP 工具引用格式

yaml

allowed_tools:
  - mcp__server-name__tool-name

例如：

mcp__postgres__query —— PostgreSQL 查询
mcp__playwright__browser_snapshot —— 浏览器截图
mcp__github__create_issue —— 创建 GitHub Issue

MCP + Skill 的协同价值

单独使用 MCP 工具，你需要每次手动描述意图。但配合 Skill，你可以：

标准化工具使用方式：skill 定义了”怎么用”这些工具
编排多工具流程：一个 skill 串联多个 MCP 工具
添加安全约束：通过 allowed_tools 限制工具范围
封装领域知识：把”怎么用这个 API”的知识固化到 skill 中

实际示例：Playwright 测试 Skill

yaml

---
name: e2e-test
description: 使用 Playwright 运行端到端测试
allowed_tools:
  - mcp__playwright__browser_navigate
  - mcp__playwright__browser_snapshot
  - mcp__playwright__browser_click
  - mcp__playwright__browser_fill_form
  - Read
  - Glob
---

markdown

## E2E 测试流程

1. 读取 `tests/e2e/` 目录下的测试场景文件
2. 对每个场景：
   a. 导航到目标页面
   b. 执行用户操作（点击、填写表单等）
   c. 截取页面快照验证结果
   d. 记录通过/失败状态
3. 生成测试报告

测试与迭代

测试方法论

按 PDF 的建议，测试分三层，按你的场景选择严谨度：

Claude.ai 手动测试：最快速迭代，适合早期验证
Claude Code 脚本化测试：可重复验证，适合回归检查
API 编程测试：评估集批量运行，适合生产级质量门禁

一个实用策略是：先在一个高价值、难度高的真实任务上反复迭代，跑通后再扩展测试集。

使用 Skill Creator

skill-creator 可以生成初稿并给出结构建议，也能做审查和改写建议，但它不会替代自动化评测套件，也不会直接产出量化评估结果。

推荐流程：

用 /skill-creator 生成初始版本
手动审查和修改
实际测试几轮
根据测试结果迭代优化

迭代策略

把测试拆成三组更容易定位问题：

1) 触发测试（Trigger）

应触发：明确请求 + 改写请求
不应触发：无关主题

2) 功能测试（Functionality）

输出结构是否正确
工具/API 调用是否成功
错误处理是否可恢复
边界条件是否覆盖

3) 性能对比（Performance）

与无 skill 的基线比较：消息轮数、工具调用次数、token 消耗、失败率

常见反馈信号与修复策略：

信号	现象	修复方向
触发不足	应触发但未加载	`description` 增加更具体的任务词和触发短语
过度触发	无关请求也加载	添加负面触发器，缩小适用边界
执行不稳	步骤跳过、调用失败、需人工纠偏	精简主指令，补错误处理与关键验证点

分发与共享

当前分发方式

按 PDF 的时间线（截至 2026 年 1 月）：

个人使用流程

下载 skill 文件夹
按需打包为 .zip
在 Claude.ai 通过 设置 > 能力 > 技能 上传
或放入 Claude Code 技能目录

组织级能力

工作区范围技能已在 2025 年 12 月 18 日 发布
支持集中管理与自动更新

开放标准定位

技能被定位为开放标准，目标是尽量跨平台可移植；如果某个 skill 强依赖特定平台能力，建议在 compatibility 字段中明确声明。

命名与定位

如果你打算分享 skill，注意以下几点：

命名简洁语义化：deploy、review-pr、gen-api-doc
描述要突出价值：不是”这个 skill 做什么”，而是”用了这个 skill 你能得到什么”
标注依赖：如果 skill 依赖特定的 MCP 服务器或工具，在描述中明确说明

通过 API 使用 Skill

面向程序化场景（应用、智能体、自动化流水线）时，PDF 提到的关键点：

使用 /v1/skills 进行技能列表与管理
在消息请求中通过 container.skills 挂载技能
结合 Claude Console 做版本管理
可用于 Agent SDK 场景

注意：API 中运行 skills 依赖代码执行工具测试版提供的隔离执行环境。

常见问题与排查

Skill 没有被触发

症状：应触发场景下，skill 没有自动加载。

排查步骤：

优先检查 description：是否写了用户真实会说的触发短语
描述是否过泛（例如“帮助项目工作”这类表述通常触发效果差）
若与文件类型强相关，是否在描述中写明（如 PDF、CSV、Figma）
反问 Claude：你会在什么情况下使用这个 skill？，据回答回改描述

Claude 偏离了 Skill 指令

症状：Claude 开始执行 skill 但中途偏离了预设的流程。

常见原因与修复：

指令过长且分散：把关键规则前置，详细文档外移到 references/
关键约束被淹没：用清晰标题突出 CRITICAL 级验证项
语言模糊：改成可验证条件（例如参数非空、日期合法）
对关键验证依赖自然语言：尽可能脚本化验证（scripts/）

MCP 工具调用失败

症状：Skill 中引用的 MCP 工具无法正常调用。

排查步骤：

确认 MCP 服务器已正确配置（检查 claude_desktop_config.json 或 .claude/config.json）
确认 allowed_tools 中的工具名称拼写正确
检查 MCP 服务器是否正在运行
尝试在 skill 外直接调用 MCP 工具，确认工具本身是否正常

技能上传失败

常见错误 1：在上传文件夹中找不到 SKILL.md

原因：文件名不是精确的 SKILL.md
修复：重命名并检查大小写

常见错误 2：无效的 frontmatter

原因：YAML 分隔符缺失、引号未闭合、缩进错误
修复：用最小模板回退后再逐步添加字段

常见错误 3：无效的 skill 名称

原因：包含空格/大写/下划线
修复：改为 kebab-case

触发过于频繁

症状：无关请求也加载了 skill。

修复方法：

添加负面触发器（Do NOT use for ...）
缩小领域边界（从“处理文档”改为“处理 PDF 法务合同”）
明确“适用场景 vs 不适用场景”

上下文窗口溢出

症状：Skill 在处理大量文件或长对话时表现退化。

修复方法：

利用渐进式披露：把详细信息放到外部文件，用 Read 按需加载
减少 skill body 的长度，只保留核心指令
对大文件使用 Grep 搜索而不是 Read 全文
SKILL.md 尽量控制在 5000 词以内
同时启用的 skill 过多时（经验上 20-50 个）要做分组与裁剪

实战：写一个博客发布 Skill

把上面学到的知识串起来，看一个完整的实战示例。这个 skill 用于自动化博客文章的发布流程（以本站 Astro 博客为例）：

yaml

---
name: publish
description: 自动化博客文章发布流程 - 验证、构建、提交、推送
allowed_tools:
  - Bash(bun run type-check)
  - Bash(bun run build)
  - Bash(bun run check)
  - Bash(git status)
  - Bash(git add)
  - Bash(git diff)
  - Bash(git log)
  - Read
  - Glob
  - Grep
allowed_tools_on_approve:
  - Bash(git commit)
  - Bash(git push)
---

markdown

## 发布前检查

运行 `bun run check` 确认代码规范
运行 `bun run type-check` 确认无类型错误
运行 `bun run build` 确认构建成功

## 验证文章

用 Glob 找到新增/修改的 `.mdx` 文件
检查 frontmatter 必填字段是否完整
确认 cover image 文件存在
确认 slug 与文件名一致

## 发布

展示变更摘要（新增文章标题、修改的文件列表）
请用户确认后执行 git commit 和 push
输出部署状态

这个 skill 用到了：

顺序编排模式：检查 → 验证 → 发布
质量门控策略：每个阶段都有通过/失败检查
工具白名单：精确控制允许的操作
二次确认：破坏性操作（commit/push）需要用户批准

资源与参考文献（补全 PDF 第六章）

如果你是第一次做 skill，建议顺序是：最佳实践指南 → 技能文档 → API 参考 → MCP 文档。

可重点关注的资料类型：

官方文档：最佳实践、技能文档、API 参考、MCP 文档
官方博客：代理技能介绍、工程实践、Skill 详解、Claude Code 技能构建案例
示例仓库：anthropics/skills 与伙伴技能目录（如 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等）

支持与反馈渠道：

一般问题：Claude 开发者社区（Discord/论坛）
Bug 反馈：对应技能仓库 Issues（附技能名、报错信息、复现步骤）

附录 A：快速检查清单

开始前

明确 2-3 个具体用例
确认所需工具（内置/MCP）
规划 skill 文件夹结构

开发中

文件夹命名 kebab-case
SKILL.md 文件名与大小写正确
frontmatter 分隔符完整
name 合规（无空格/大写）
description 包含“做什么 + 何时用”
不含 XML 尖括号 < >
指令可执行、含错误处理与示例

上传前

测试应触发场景
测试改写请求
测试无关请求不触发
跑通功能测试与工具调用
打包 .zip（如平台要求）

上传后

在真实对话中验证效果
监控触发不足/过度触发
收集用户反馈并迭代
更新版本号与元数据

附录 B：YAML 前置模板

最小可用模板：

yaml

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

扩展示例：

yaml

123456789101112131415

---
name: skill-name
description: [required description]
license: MIT
compatibility: Claude Code + network access + target MCP connected
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: [email protected]
---

附录 C：示例技能路线

文档类技能（PDF/DOCX/PPTX/XLSX 生成）
工作流类技能（顺序编排、迭代优化、多 MCP 协调）
伙伴技能目录（拿现成生产技能做二次改造）

总结

Claude Code 的 Skill 系统虽然简单（本质就是结构化的 Markdown 文件），但设计得很精巧。几个核心要点：

渐进式披露是灵魂：三级信息架构，按需加载，珍惜 context window
明确 > 隐含：写给 Claude 的指令越具体越好，不要假设它”应该知道”
约束 > 建议：用 MUST/NEVER/ALWAYS 而不是 “考虑”/“建议”
五大模式要记住：顺序编排、多 MCP 协调、迭代优化、上下文感知工具选择、领域特定智能
测试和迭代不能少：Skill 不是写完就行，需要在实际使用中不断打磨
安全第一：allowed_tools 和 allowed_tools_on_approve 是你的安全网

Skill 系统目前还在快速演进中，但核心设计哲学已经比较稳定。掌握这些原则，不管 API 怎么变，你都能写出高质量的 skill。

Claude Code 技能系统完全指南：从原理到实战

什么是 Claude Code Skill

核心设计原则

1. 渐进式披露（Progressive Disclosure）

2. 明确优于隐含

3. 动词驱动，面向行动

4. 约束优于建议

5. 可组合性（Composability）

6. 可移植性（Portability）

对 MCP 构建者：连接器 + Skill

SKILL.md 文件结构

文件位置

YAML Frontmatter

关键字段说明

安全限制（必须遵守）

Skill Body 编写指南

结构模板

编写技巧

三大用例类别

1. 文档与内容创建

2. 工作流自动化

3. MCP 工具增强

定义成功标准（很多文章会漏掉）

先选框架：问题优先 vs 工具优先

五大设计模式

模式 1：顺序编排（Sequential Orchestration）

模式 2：多 MCP 协调（Multi-MCP Coordination）

模式 3：迭代优化（Iterative Refinement）

模式 4：上下文感知工具选择（Context-Aware Tool Selection）

模式 5：领域特定智能（Domain-Specific Intelligence）

Skill 与 MCP 的集成

MCP 工具引用格式

MCP + Skill 的协同价值

实际示例：Playwright 测试 Skill

测试与迭代

测试方法论

使用 Skill Creator

迭代策略

分发与共享

当前分发方式

命名与定位

通过 API 使用 Skill

推荐发布路径（Today）

常见问题与排查

Skill 没有被触发

Claude 偏离了 Skill 指令

MCP 工具调用失败

技能上传失败

触发过于频繁

上下文窗口溢出

实战：写一个博客发布 Skill

资源与参考文献（补全 PDF 第六章）

附录 A：快速检查清单

附录 B：YAML 前置模板

附录 C：示例技能路线

总结