Building Skills for Claude Code：完整开发指南

本文详细介绍如何为 Claude Code 创建 Skills，包括核心设计原则、Skill 架构、渐进式披露模式以及生产环境部署策略。

Skills 与 Sub-Agents、MCP 的区别

在深入了解 Skills 之前，重要的是理解它们与其他 Claude Code 扩展机制的比较：

何时使用：

• Skills：需要 Claude 遵循特定程序、使用领域知识或重复执行确定性脚本时
• Sub-Agents：需要并行工作、委托复杂研究或隔离任务上下文时
• MCP：需要与外部系统、API 或实时数据源交互时

Skills 是无需外部基础设施即可扩展 Claude 能力的最简单方式——非常适合打包团队知识和工作流。

什么是 Claude Code Skills？

核心概念

Skills 是模块化的、自包含的包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。将它们视为特定领域或任务的"入职指南"——它们将 Claude 从通用代理转变为具备程序性知识的专业代理。

根据 Anthropic 官方 skills 仓库，skills 旨在教 Claude 如何重复完成特定目标——无论是将品牌指南应用于文档、执行组织工作流，还是自动化个人流程。

Skills 提供的能力

关键特性

核心设计原则

在深入实现之前，理解区分有效 skills 和臃肿 skills 的三个原则。

原则 1：简洁至上

上下文窗口是公共资源。Skills 与 Claude 需要的其他一切共享它：系统提示、对话历史、其他 skills 的元数据，以及实际的用户请求。

默认假设：Claude 已经非常聪明。 只添加 Claude 还没有的上下文。

质疑每条信息：

• "Claude 真的需要这个解释吗？"
• "这段文字是否值得它的 token 成本？"

专业提示： 优先选择简洁示例而非冗长解释。一个精心设计的示例比段落描述传达更多信息——且成本更少 token。

原则 2：设置适当的自由度

将特定性水平与任务的脆弱性和可变性相匹配：

专业见解： 将 Claude 想象成探索路径：有悬崖的窄桥需要特定护栏（低自由度），而开阔田野允许多条路线（高自由度）。将 skill 的指导与地形匹配。

原则 3：渐进式披露

Skills 使用三级加载系统来高效管理上下文：

第 1 级 - 元数据（始终加载）

• YAML frontmatter 中的名称和描述
• 每个 skill 约 100 个 token
• 无需消耗上下文即可实现发现

第 2 级 - SKILL.md 主体（触发时）

• 主要指令和程序
• 目标少于 500 行 / 5k token
• 当 Claude 确定 skill 相关时加载

第 3 级 - 打包资源（按需）

• 脚本、参考资料、资产
• 无限容量
• 脚本无需加载到上下文即可执行

警告： 保持 SKILL.md 主体精简且在 500 行以内。如果接近此限制，将内容拆分到单独的参考文件中。这可以防止上下文膨胀同时保持能力。

Skill 的解剖结构

必需结构

每个 skill 遵循此结构：

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter 元数据 (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令 (必需)
└── 打包资源 (可选)
    ├── scripts/     - 可执行代码
    ├── references/  - 上下文文档
    └── assets/      - 输出文件（模板等）

SKILL.md 格式

---
name: your-skill-name
description: 这个 skill 做什么以及何时使用它。包括触发上下文、文件类型、任务类型和用户可能提到的关键词。
---

# Your Skill Name

[指令部分]
清晰、分步的 Claude 指导。

[示例部分]
具体的输入/输出示例。

Frontmatter 要求

关键： 描述字段是主要触发机制。包括 skill 做什么以及何时使用的具体触发器/上下文。主体仅在触发后加载——在主体中放置"何时使用"部分是无效的。

打包资源

脚本 (scripts/)

需要确定性可靠性的任务的可执行代码（Python/Bash 等）。

何时包含：

• 相同代码被重复重写
• 需要确定性可靠性
• 容易出错的复杂操作

好处：

• Token 高效
• 确定性结果
• 无需加载到上下文即可执行

# 示例：scripts/rotate_pdf.py
#!/usr/bin/env python3
"""将 PDF 页面旋转指定度数。"""

import argparse
from pypdf import PdfReader, PdfWriter

def rotate_pdf(input_path, output_path, degrees):
    reader = PdfReader(input_path)
    writer = PdfWriter()

    for page in reader.pages:
        page.rotate(degrees)
        writer.add_page(page)

    with open(output_path, "wb") as f:
        writer.write(f)

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("input", help="输入 PDF 路径")
    parser.add_argument("output", help="输出 PDF 路径")
    parser.add_argument("--degrees", type=int, default=90)
    args = parser.parse_args()
    rotate_pdf(args.input, args.output, args.degrees)

参考资料 (references/)

按需加载到上下文的文档。

何时包含：

• 数据库模式
• API 文档
• 领域知识
• 公司政策
• 详细工作流指南

最佳实践： 如果文件很大（>10k 词），在 SKILL.md 中包含 grep 搜索模式。

专业提示： 信息应该存在于 SKILL.md 或参考资料中——而不是两者。仅在 SKILL.md 中保留基本程序指令；将详细参考材料移到参考资料文件。这保持 SKILL.md 精简同时使信息可发现。

资产 (assets/)

不加载到上下文但用于输出的文件。

何时包含：

• 模板（PowerPoint、文档）
• 品牌资产（logo、图片）
• 样板代码
• 字体

好处： 将输出资源与文档分离，使 Claude 无需加载即可使用文件。

不应包含的内容

Skill 应仅包含基本文件。不要创建：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

Skill 应仅包含 AI 代理完成工作所需的内容——而不是关于创建、设置程序或用户文档的辅助上下文。

六步 Skill 创建流程

步骤 1：用具体示例理解

仅在使用模式已经清楚理解时跳过。

要创建有效的 skill，收集具体的使用示例。问这样的问题：

• "这个 skill 应该支持什么功能？"
• "你能给出这个 skill 如何使用的示例吗？"
• "用户会说什么来触发这个 skill？"

专业见解： 不要用问题压倒用户。从最重要的开始，根据需要跟进。当你清楚了解 skill 应支持的功能时结束。

图像编辑器 skill 的示例：

• 用户可能会说："去除这张图片的红眼"
• 用户可能会说："将这张图片旋转 90 度"
• 用户可能会说："将这张照片调整为 800x600"

步骤 2：规划可重用内容

通过以下方式分析每个示例：

1. 考虑如何从头开始执行示例
2. 确定重复执行时什么脚本、参考资料和资产会有帮助

示例分析：

步骤 3：初始化 Skill

从头创建时，使用 Anthropic 的初始化脚本：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本：

• 在指定路径创建 skill 目录
• 生成带有正确 frontmatter 的 SKILL.md 模板
• 创建示例资源目录
• 添加可自定义或删除的示例文件

手动初始化替代方案：

mkdir -p my-skill/{scripts,references,assets}
touch my-skill/SKILL.md

步骤 4：编辑 Skill

记住：你是为另一个 Claude 实例创建这个。包含有益且非明显的信息。

从可重用内容开始

实现步骤 2 中确定的脚本、参考资料和资产。

重要： 通过实际运行测试所有脚本。如果有很多类似脚本，测试代表性样本以确保它们工作。

删除 skill 不需要的任何示例文件。

编写 SKILL.md

编写指南： 始终使用祈使/不定式形式。

Frontmatter 示例：

---
name: docx-processor
description: 全面的文档创建、编辑和分析，支持修订追踪、评论、格式保留和文本提取。当 Claude 需要处理专业文档（.docx 文件）时使用：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订追踪，(4) 添加评论，或任何其他文档任务。
---

主体结构：

# Skill 名称

## 入门
[基本第一步]

## 核心工作流
[分步程序]

## 扩展能力
- **特性 A**：参见 [FEATURE_A.md](references/feature_a.md)
- **特性 B**：参见 [FEATURE_B.md](references/feature_b.md)

## 示例
[具体输入/输出对]

步骤 5：打包 Skill

开发完成后，打包成可分发的 .skill 文件：

scripts/package_skill.py <path/to/skill-folder>

可选输出目录：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本：

1. 自动验证 skill：
   • YAML frontmatter 格式和必需字段
   • 命名约定和目录结构
   • 描述完整性和质量
   • 文件组织和资源引用
2. 打包 如果验证通过，创建 .skill 文件（zip 格式）

如果验证失败，修复错误后重新运行。

步骤 6：基于使用迭代

Skills 通过实际使用改进：

1. 在实际任务上使用 skill
2. 注意困难或低效之处
3. 确定 SKILL.md 或资源需要更新
4. 实施更改并再次测试

专业提示： 迭代通常发生在使用 skill 之后，对表现有新鲜记忆时。立即捕捉改进想法，当它们还清晰时。

高级 Skill 模式

本节涵盖有效组织和构建 skills 的高级模式。

渐进式披露模式

模式 1：带参考资料的高级指南

# PDF 处理

## 快速开始
用 pdfplumber 提取文本：
[代码示例]

## 额外能力
- **表单填写**：参见 [FORMS.md](references/forms.md)
- **API 参考**：参见 [REFERENCE.md](references/reference.md)
- **示例**：参见 [EXAMPLES.md](references/examples.md)

Claude 仅在需要时加载参考文件。

模式 2：领域特定组织

对于具有多个领域的 skills，按领域组织：

bigquery-skill/
├── SKILL.md（概述和导航）
└── references/
    ├── finance.md（收入、计费指标）
    ├── sales.md（机会、管道）
    ├── product.md（API 使用、特性）
    └── marketing.md（活动、归因）

当用户询问销售指标时，Claude 只读取 sales.md。

模式 3：框架/变体组织

对于支持多个框架的 skills：

cloud-deploy/
├── SKILL.md（工作流 + 提供商选择）
└── references/
    ├── aws.md（AWS 部署模式）
    ├── gcp.md（GCP 部署模式）
    └── azure.md（Azure 部署模式）

当用户选择 AWS 时，Claude 只读取 aws.md。

模式 4：条件详情

显示基本内容，链接到高级：

# DOCX 处理

## 创建文档

新文档使用 docx-js。参见 [DOCX-JS.md](references/docx-js.md)。

## 编辑文档

简单编辑直接修改 XML。

**修订追踪**：参见 [REDLINING.md](references/redlining.md)
**OOXML 详情**：参见 [OOXML.md](references/ooxml.md)

重要指南

• 避免深层嵌套引用 - 保持参考资料从 SKILL.md 只有一级深度
• 结构化较长文件 - 对于 >100 行的文件，在顶部包含目录

工作流模式

顺序工作流

对于复杂的多步骤任务，将工作分解为带有前期概述的独立步骤：

## 填写 PDF 表单

此过程涉及 5 个步骤：

1. 分析表单结构
2. 创建字段映射
3. 验证映射
4. 填写表单
5. 验证输出

### 步骤 1：分析表单

[详细指令]

### 步骤 2：创建字段映射

[详细指令]
...

条件工作流

对于有决策分支的任务：

## 文档处理

首先，确定任务类型：

- **创建新文档**：转到 A 部分
- **编辑现有文档**：转到 B 部分
- **转换格式**：转到 C 部分

### A 部分：创建新文档

[创建的具体步骤]

### B 部分：编辑现有文档

[编辑的具体步骤]
...

输出模式

模板模式（严格）

对于需要精确性的场景：

## 报告格式

始终使用此确切结构：

### 执行摘要

[2-3 句总结发现]

### 关键发现

1. [有支持数据的发现]
2. [有支持数据的发现]

### 建议

- [可执行的建议]
- [可执行的建议]

模板模式（灵活）

当适应性增加价值时：

## 分析格式

使用此建议结构，根据需要调整：

- **概述**：上下文和范围
- **分析**：关键观察
- **见解**：模式和影响
- **下一步**：建议的行动

对章节深度和细节使用你的最佳判断。

示例模式

对于风格一致性，包含输入/输出对：

## 提交消息示例

**输入**：添加了用户认证
**输出**：feat(auth): 实现基于 JWT 的用户认证

**输入**：修复了支付处理中的 bug
**输出**：fix(payments): 解决结账流程中的竞态条件

**输入**：更新了依赖
**输出**：chore(deps): 将 axios 升级到 1.6.0，更新 lodash

专业见解： 示例比单独描述更清晰地帮助 Claude 理解期望的风格和细节。当输出质量依赖风格一致性时，投资于好的示例。

真实 Skill 示例

示例 1：API 文档 Skill

---
name: api-documenter
description: 从代码生成和维护 API 文档。在记录 REST API、生成 OpenAPI 规范、创建 SDK 文档或维护 API 参考指南时使用。在涉及 API 文档、端点文档或 Swagger/OpenAPI 的请求时触发。
---

# API 文档 Skill

从源代码和规范生成全面的 API 文档。

## 用法

OpenAPI 生成：
python scripts/generate_openapi.py --input ./routes --output api-spec.yaml

## 文档模板

### 端点文档
  ## [METHOD] /path/to/endpoint

  **描述**：此端点做什么

  **认证**：必需/可选

  **参数**：
  | 名称 | 类型 | 必需 | 描述 |
  |------|------|----------|-------------|

  **响应**：{ "example": "response" }

## 额外特性
- **SDK 生成**：参见 [SDK.md](references/sdk.md)
- **版本控制**：参见 [VERSIONING.md](references/versioning.md)

示例 2：数据库迁移 Skill

---
name: db-migrator
description: 为 PostgreSQL、MySQL 和 SQLite 创建和管理数据库迁移。在生成迁移、处理模式更改、管理回滚或使用 Prisma 或 TypeORM 等 ORM 时使用。在迁移请求、模式更改或数据库版本控制时触发。
---

# 数据库迁移 Skill

创建安全、可逆的数据库迁移。

## 工作流

1. 分析当前模式
2. 确定所需更改
3. 生成迁移文件
4. 验证迁移安全性
5. 提供回滚策略

## 迁移安全检查

任何破坏性操作前：
- 验证无数据丢失
- 检查外键约束
- 估计锁定持续时间
- 准备回滚脚本

## 框架特定指南
- **Prisma**：参见 [PRISMA.md](references/prisma.md)
- **TypeORM**：参见 [TYPEORM.md](references/typeorm.md)
- **原始 SQL**：参见 [RAW_SQL.md](references/raw_sql.md)

示例 3：代码审查 Skill

---
name: code-reviewer
description: 执行全面的代码审查，关注安全性、性能和可维护性。在审查拉取请求、审计代码质量、检查漏洞或确保最佳实践时使用。在审查请求、PR 分析或安全审计时触发。
---

# 代码审查 Skill

系统的代码审查，关注安全性、性能和质量。

## 审查清单

### 安全性（关键）
- [ ] SQL 注入漏洞
- [ ] XSS 攻击向量
- [ ] 硬编码密钥/凭证
- [ ] 认证绕过风险
- [ ] 输入验证缺口

### 性能
- [ ] N+1 查询模式
- [ ] 内存泄漏潜力
- [ ] 低效算法
- [ ] 缺少索引

### 质量
- [ ] DRY 违规
- [ ] 死代码
- [ ] 复杂函数（>50 行）
- [ ] 缺少错误处理

## 输出格式
  [严重级别] 问题标题
  位置：file:line
  问题：哪里错了
  影响：为什么重要
  修复：如何解决

## 语言特定指南
- **JavaScript/TypeScript**：参见 [JS.md](references/js.md)
- **Python**：参见 [PYTHON.md](references/python.md)
- **Go**：参见 [GO.md](references/go.md)

发现 Skills：在哪里找到现成的 Skills

在从头构建自己的 skills 之前，探索不断增长的社区贡献 skills 生态系统。这些目录提供数千个生产就绪的 skills，你可以用单个命令安装。

skills.sh - Agent Skills 目录

skills.sh 是最大的社区驱动 skills 目录，拥有 20,000+ skills，涵盖前端设计、SEO、营销、文案和测试等类别。

一键安装：

npx skills add <owner/repo>

热门 skills 包括：

• vercel-react-best-practices - Vercel 的 React 最佳实践
• seo-audit - 全面的 SEO 审计
• web-design-guidelines - 现代网页设计模式
• frontend-design - 前端架构指导
• copywriting - 专业文案标准

排行榜显示趋势和历来最受欢迎的 skills，便于发现其他开发者认为有用的内容。

Context7 - LLM 文档平台

Context7 为 LLM 和 AI 代码编辑器提供最新文档。除了 skills，它还提供：

• 流行库和框架的上下文文档
• 策划的高质量 Skills 库
• Claude Code 和其他 AI 工具的集成指南

当你需要与最新库版本保持同步的 skills 时，Context7 特别有用。

专业提示： 在构建自定义 skill 之前，先搜索这些目录。你可能会找到你需要的——或者至少是一个自定义的好起点。

部署和生产

存储和共享 Skills

个人 Skills

在所有项目中可用：

项目 Skills

通过 git 与团队共享：

从市场安装

将 Anthropic skills 仓库注册为插件：

然后浏览并安装特定 skill 集：

安装后，skills 在你提到相关任务时自动激活。

生产注意事项

验证清单

部署 skill 前：

• YAML frontmatter 有效
• 描述包含 what 和 when
• 所有脚本已测试且工作
• 从 SKILL.md 正确链接参考资料
• SKILL.md 和参考资料之间无重复信息
• 总 SKILL.md 在 500 行以内
• 无无关文档文件

安全最佳实践

警告： 使用前始终审计 skills，特别是来自外部来源的。检查意外的网络调用、文件修改或数据外泄模式。

环境变量：

• 永不在 skills 中硬编码 API 密钥或密钥
• 引用环境变量：$API_KEY
• 在 SKILL.md 中记录所需变量

工具限制：

• 适当时在前言中使用 allowed-tools
• 对敏感操作限制为只读工具

性能优化

Token 效率：

• 最小化 SKILL.md 大小
• 使用参考资料存储详细内容
• 提供示例而非解释

加载优化：

• 按领域结构化参考资料
• 在大文件中包含目录
• 使用清晰的文件命名以便快速发现

常见问题

什么是 Claude Code Skill？

Skill 是一个模块化包，包含 Claude 可以动态发现和加载的指令、脚本和资源。它将 Claude 从通用助手转变为特定任务的专业代理。

Claude 如何发现我的 skill？

Claude 在启动时读取 skill 元数据（名称和描述）。当请求匹配描述时，Claude 加载完整的 SKILL.md 并遵循其指令。这称为"渐进式披露"。

我应该在哪里存储我的 skills？

个人 skills 放在 ~/.claude/skills/ 用于跨项目使用。项目 skills 放在 .claude/skills/ 通过 git 与团队成员共享。

Skills 和斜杠命令有什么区别？

斜杠命令是用户调用的（/command）并立即执行。Skills 是模型调用的——Claude 根据上下文自动发现和使用它们。Skills 更适合复杂的多步能力。

如何限制 skill 可以使用的工具？

在你的 YAML frontmatter 中添加 allowed-tools。例如：allowed-tools: Bash, Read, Grep 在允许读取操作的同时防止文件修改。

我应该在描述字段中放什么？

包括 skill 做什么以及何时使用。添加触发上下文、文件类型、任务类型和用户可能提到的关键词。这是 skill 发现的主要机制。

SKILL.md 应该有多长？

保持在 500 行以内。如果接近此限制，将内容拆分到参考文件。从 SKILL.md 清晰链接到它们，以便 Claude 知道它们存在。

Skills 可以包含可执行代码吗？

可以。将脚本放在 scripts/ 目录中。这些可以是 Python、Bash 或任何可执行文件。脚本提供确定性可靠性，无需加载到上下文即可执行。

如何调试不工作的 skill？

检查 YAML frontmatter 是否有效，描述是否包含相关触发词，文件是否在正确位置。问 Claude"有哪些 skills 可用？"来验证发现。

我可以与团队共享 skills 吗？

可以。将 skills 存储在项目中的 .claude/skills/ 并提交到 git。克隆仓库的团队成员自动拥有访问权限。

结论

相关资源

Skills 目录：

• skills.sh - 拥有 20K+ 社区 skills 的 Agent Skills 目录
• Context7 - LLM 文档和 skills 平台
• SEO Audit Skill - SEOmator 的全面 SEO 审计 skill（108 条规则）

官方资源：

• Anthropic Skills Repository - 官方 skills 集合和示例
• Anthropic Agent Skills Blog - Skill 架构深度解析
• Claude Code Documentation - 官方 Claude Code 文档

构建你的 Skill 库

Claude Code Skills 代表了我们与 AI 助手工作方式的根本性转变。不是每次对话都从头开始，你可以将专业知识打包成可重用的模块，随着时间的推移复合价值。

关键要点

对于个人开发者：

• 从自动化你最重复任务的技能开始
• 保持 SKILL.md 精简——500 行以内
• 使用渐进式披露管理复杂性
• 打包前彻底测试脚本

对于团队：

• 将共享 skills 存储在 .claude/skills/ 用于 git 分发
• 为团队采用彻底记录 skills
• 对安全敏感操作使用 allowed-tools
• 将 skills 视为可重用的团队资产

对于生产环境：

• 部署前验证所有 skills
• 审计第三方 skills 的安全性
• 监控 skill 使用模式
• 基于实际性能迭代

关键要点： 最好的 skills 是不可见的——它们在需要时激活，无需张扬地提供所需内容。从一个解决你最大痛点的 skill 开始，基于使用迭代，并随着时间的推移构建你的库。精心制作的技能的复合效应会改变你的整个工作流。

最后更新：2025年12月