---
title: Claude Code 技能系统完全指南 - 从原理到实战
slug: claude-code-skill-guide
date: 2026-02-27
author: Frankie 徐
category: ai
tags: ['claude', 'claude-code', 'ai', 'skill', 'mcp', 'prompt-engineering']
description: 深度解析 Claude Code 技能系统的设计哲学与实战技巧，涵盖 SKILL.md 编写规范、三级渐进式披露、五大设计模式和 MCP 集成。
permalink: https://www.210k.cc/claude-code-skill-guide
---

## 什么是 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
## 数据库迁移流程

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

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

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

**量化指标示例**

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

**定性指标示例**

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

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

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

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

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

## 五大设计模式

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

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

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

```
Step 1 → Step 2 → Step 3 → Done
```

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

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

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

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

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

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

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

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

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

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

```
Draft → Review → Revise → Review → Final
```

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

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

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

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

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

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

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

```
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 不只是“调用工具”，还要把行业规则和治理逻辑编码进去。

```
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，你可以：

1. **标准化工具使用方式**：skill 定义了"怎么用"这些工具
2. **编排多工具流程**：一个 skill 串联多个 MCP 工具
3. **添加安全约束**：通过 `allowed_tools` 限制工具范围
4. **封装领域知识**：把"怎么用这个 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 的建议，测试分三层，按你的场景选择严谨度：

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

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

### 使用 Skill Creator

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

推荐流程：

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

### 迭代策略

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

**1) 触发测试（Trigger）**

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

**2) 功能测试（Functionality）**

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

**3) 性能对比（Performance）**

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

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

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

## 分发与共享

### 当前分发方式

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

**个人使用流程**

1. 下载 skill 文件夹
2. 按需打包为 `.zip`
3. 在 Claude.ai 通过 `设置 > 能力 > 技能` 上传
4. 或放入 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 依赖代码执行工具测试版提供的隔离执行环境。

### 推荐发布路径（Today）

1. 在 GitHub 托管技能仓库（提供安装说明、截图、示例）
2. 在 MCP 文档中增加“配套 skill”章节，解释组合价值
3. 提供一步步安装与验证指南（下载、上传、启用、测试）

## 常见问题与排查

### Skill 没有被触发

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

**排查步骤**：

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

### Claude 偏离了 Skill 指令

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

**常见原因与修复**：

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

### MCP 工具调用失败

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

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

### 技能上传失败

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

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

**常见错误 2**：`无效的 frontmatter`

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

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

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

### 触发过于频繁

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

**修复方法**：

1. 添加负面触发器（`Do NOT use for ...`）
2. 缩小领域边界（从“处理文档”改为“处理 PDF 法务合同”）
3. 明确“适用场景 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
## 发布前检查

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

## 验证文章

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

## 发布

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

这个 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
---
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: support@example.com
---
```

## 附录 C：示例技能路线

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

## 总结

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

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

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