Appearance
Claude Code Skills系统完全指南：从源码解析到实战构建
Skills不是Claude Code的内置功能，而是一套自定义扩展机制——把针对特定任务的专业知识打包成文件，让AI在遇到相应场景时直接调用，而不是每次重新描述。本文从官方源码出发，拆解Skills的完整结构、触发逻辑和设计原则。
Claude Code实战系列第三篇。前两篇分别是《CLAUDE.md协作指南》与《真实项目开发流程》，本篇聚焦Skills扩展体系，深度解析官方源码与设计理念。同时结合Anthropic官方Help Center最新发布的Skill创建规范，补充渐进式加载机制等关键细节。
Skills是什么
在Claude Code的语境里，Skill不是内置功能，而是一套自定义扩展机制。
它的核心思路：把针对特定任务的专业知识打包成文件，让Claude Code在遇到相应场景时能够调用这套知识，而不是每次都重新描述。
这和CLAUDE.md不同。CLAUDE.md是项目级上下文，回答的是"这个项目是什么"；Skill是任务级指令，回答的是"这类任务应该怎么做"。
打个比方：CLAUDE.md是宪法，定义项目的基本框架和原则；Skill是专业法，针对特定领域给出具体的执行规则。一个管大局，一个管细节，两者配合才能让AI真正按你的标准工作。
从官方源码看，Skills的文件结构非常清晰：
skill-name/
├── SKILL.md ← 必须文件，YAML frontmatter + 核心指令
├── references/ ← 可选，参考文档，按需加载
├── examples/ ← 可选，工作示例
└── scripts/ ← 可选，可执行脚本Claude Code启动时会扫描skills/目录，把每个子目录里的SKILL.md的name和description加载进上下文。当用户的描述触发了某个description，Claude会把对应的SKILL.md全文读入，然后按照里面的指令执行。
这里有个细节值得展开：加载是渐进式的。Anthropic官方文档明确提到，Skill的加载分三个层级——
- 第一层：metadata。Claude首先读取SKILL.md的YAML frontmatter（name和description），用它判断是否需要激活这个Skill。这一层的信息量最小，但足够做路由决策。
- 第二层：Markdown body。如果metadata匹配成功，Claude会继续读取SKILL.md的正文内容，获取具体指令和规范。
- 第三层：resources。如果任务需要更深入的知识（比如参考文档或示例代码），Claude会按需加载references/和examples/目录里的文件。
这种渐进式加载的设计很聪明：不是一股脑把所有Skill内容塞进上下文（那样会浪费token），而是按需加载，用多少取多少。这也意味着，你的Skill写得越结构化、层级越清晰，Claude的调用效率就越高。
为什么需要Skills
三个场景能说清楚：
第一，团队知识传承。
你团队里最好的工程师，他的代码审查方式、安全扫描逻辑、部署规范，都是靠多年经验积累的。如果只靠口口相传，每次换人都要重新教。有了Skill，这些经验可以固化成文件，新工程师加上项目CLAUDE.md，AI就能用团队的标准工作。
第二，复杂任务的决策框架。
一段prompt只能给出一个答案，一个Skill可以给出一个决策树。Claude遇到不同情况，应该走哪条分支，输出什么，都有明确的规范，而不是每次生成一段看似合理但不一致的内容。
这就是Skill和普通prompt的关键区别：prompt是"一问一答"，Skill是"一套决策系统"。你写给Claude的prompt，它这次理解了，下次换个措辞可能又是另一套做法。但Skill里定义的规则和分支，每次触发都是一致的。
第三，反复重写的确定性任务。
有些任务每次都要重新写差不多的代码，比如每次新建组件都要搭脚手架、每次做代码迁移都要处理同一套模式。把这些任务的"正确做法"写成Skill，Claude每次都能用最优方式执行，不会每次都从零推理。
Skills的真实结构：从官方源码看设计
SKILL.md的frontmatter
官方frontend-design插件的Skill文件是这样的：
yaml
---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications.
---
# Frontend Design Guidance
## Design Thinking
Before coding, understand the context and commit to a BOLD aesthetic direction...
## Technical Requirements
Implement production-grade...frontmatter只有两个字段是必须的：
| 字段 | 作用 | 限制 |
|---|---|---|
name | Skill的人类可读名称 | 最多64字符 |
description | 告诉Claude什么时候该用这个Skill | 最多200字符 |
还有一个可选字段：
| 字段 | 作用 | 示例 |
|---|---|---|
dependencies | Skill运行所需的软件包 | python>=3.8, pandas>=1.5.0 |
description是这个系统里最关键的字段。 它就是触发器——Claude用它来判断是否激活这个Skill。写得好，Claude精准触发；写得模糊，要么漏触发，要么乱触发。
Anthropic官方给了写description的原则：说清楚"这个Skill做什么"和"什么时候用"。比如：
❌ 差的description：Help with code review
✅ 好的description：Review Python code for security vulnerabilities, performance issues, and PEP 8 compliance. Use when the user asks for code review or submits Python code for review.区别很明显：好的description限定了语言（Python）、检查维度（安全/性能/规范）、触发场景（代码审查请求）。Claude拿到这个信息，就能准确判断什么时候该请出这个Skill。
Markdown body：核心指令区
frontmatter之后就是Markdown正文，这里是Skill的核心指令区。Claude加载Skill后，会按照这里的指令执行。
好的Skill正文通常包含这几个部分：
- 概述：这个Skill解决什么问题
- 工作流程：遇到任务时Claude应该怎么一步步执行
- 规则和约束：什么必须做、什么绝对不能做
- 输出格式：Claude应该以什么格式返回结果
这里有个设计原则：正文只放Claude执行任务时必须知道的信息。那些"可能有用但不是每次都需要"的内容，放到references/目录，让Claude按需读取。
references/目录：按需加载的知识库
references/目录放的是参考文档。Claude不会默认读取这里的内容，只有当任务需要时才会去翻。
这个设计解决了两个问题：
- 上下文窗口的效率。不是每个任务都需要所有知识。比如你的Skill既能做React组件审查，又能做Vue组件审查，用户当前只需要React的，那就只加载React的参考文档。
- 知识的模块化管理。你可以不断往references里加新的参考文档，而不用修改核心指令。Skill的主体保持稳定，知识库持续扩展。
examples/目录：工作示例
examples/放的是Claude可以参考的工作示例。和references不同，examples更偏重"照着做"——给Claude一个具体的示范，让它理解你期望的输出是什么样的。
好的examples应该覆盖不同的场景变体。比如一个代码审查Skill的examples，可以包含：
- 简单函数的审查示例
- 复杂类的审查示例
- 发现严重漏洞时的审查示例
这样Claude就能根据任务的复杂度，参考对应的示例来执行。
scripts/目录：可执行脚本
scripts/放的是Skill可以调用的脚本。这是Skills和纯prompt最大的区别——Skill不仅能告诉Claude"怎么想"，还能告诉Claude"怎么做"。
比如一个部署Skill，可以在scripts/里放部署脚本，Claude执行部署任务时直接调用。这比让Claude从头写部署命令要可靠得多。
Skills的触发机制
理解了结构，再来看Claude Code是怎么决定什么时候用哪个Skill的。
核心流程就三步：
步骤1：启动时扫描
Claude Code启动时，扫描skills/目录，读取每个子目录里SKILL.md的frontmatter（只读name和description），把这些信息缓存起来。
步骤2：用户输入匹配
当用户输入一段描述，Claude会把这段描述和所有Skill的description做语义匹配。如果用户的意图和某个Skill的description高度相关，就触发这个Skill。
步骤3：按需加载内容
触发后，Claude读取对应SKILL.md的完整内容（包括Markdown body），然后根据任务需要决定是否加载references和examples。
这个流程说明了一个关键点：Skill的触发完全依赖description的语义匹配质量。这就是为什么前面强调description是最关键字段——它直接决定了Skill能不能被正确激活。
实战：写一个代码审查Skill
光说不练假把式。来写一个完整的代码审查Skill，把上面的知识点串起来。
创建目录结构
code-review/
├── SKILL.md
├── references/
│ ├── security-checklist.md
│ └── performance-patterns.md
└── examples/
└── review-sample.md编写SKILL.md
yaml
---
name: code-review
description: Review code for security vulnerabilities, performance issues, and style consistency. Use when the user asks for code review, submits code for review, or wants feedback on code quality.
---
# Code Review Skill
## Overview
You are a senior code reviewer. When reviewing code, follow this systematic process:
## Workflow
1. **First Pass — Security**
- Check for injection vulnerabilities (SQL, XSS, command injection)
- Verify authentication and authorization logic
- Review data validation and sanitization
- Flag any hardcoded secrets or credentials
2. **Second Pass — Performance**
- Identify unnecessary loops or redundant computations
- Check for memory leaks (unclosed connections, missing cleanup)
- Review database query efficiency (N+1 queries, missing indexes)
- Assess caching strategy
3. **Third Pass — Style & Maintainability**
- Check naming conventions consistency
- Review function complexity (too many parameters, too long)
- Assess error handling completeness
- Verify test coverage expectations
## Rules
- Always explain WHY something is an issue, not just THAT it is
- Rate severity: 🔴 Critical / 🟡 Warning / 🔵 Suggestion
- Provide a fixed code example for every Critical issue
- Never skip security pass, even for "quick" reviews
## Output Format
For each issue found:
- **[Severity]** Issue title
- Location: `file:line`
- Problem: What's wrong
- Fix: How to fix it添加参考文档
references/security-checklist.md：
markdown
# Security Review Checklist
## Input Validation
- All user inputs must be validated on server side
- Use parameterized queries for database operations
- Escape output based on context (HTML, JS, URL, CSS)
## Authentication
- Never store passwords in plain text
- Use constant-time comparison for auth tokens
- Implement rate limiting on login endpoints
## Sensitive Data
- No hardcoded API keys or secrets
- Use environment variables for configuration
- Log sensitive data with masking添加工作示例
examples/review-sample.md：
markdown
# Code Review Example
## Input Code
```python
def get_user(user_id):
query = f"SELECT * FROM users WHERE id = {user_id}"
result = db.execute(query)
return resultReview Output
- 🔴 SQL Injection Vulnerability
- Location:
app.py:2 - Problem: String formatting in SQL query allows injection
- Fix:
python
def get_user(user_id):
query = "SELECT * FROM users WHERE id = ?"
result = db.execute(query, (user_id,))
return result
### 安装和测试
把整个`code-review/`目录放到项目的`.claude/skills/`下面：your-project/ ├── .claude/ │ ├── CLAUDE.md │ └── skills/ │ └── code-review/ │ ├── SKILL.md │ ├── references/ │ └── examples/ ├── src/ └── package.json
重启Claude Code，然后试试：请帮我审查 src/auth.py 的代码
Claude会自动匹配到code-review Skill的description（"Review code for security vulnerabilities..."），加载完整指令，然后按照你定义的工作流程执行审查。
## Skill设计的5个原则
根据Anthropic官方Help Center的最新指引，好的Skill应该遵循以下原则：
1. **解决一个特定的、可重复的任务**。不要试图做一个"万能Skill"，聚焦单一工作流。一个Skill管代码审查，另一个管部署，第三个管测试——而不是把三个揉在一起。
2. **给Claude清晰的指令**。Claude是执行者，不是猜谜者。你的指令越具体，执行效果越好。"检查安全问题"不如"第一步检查SQL注入，第二步检查XSS，第三步检查硬编码密钥"。
3. **包含示例**。example不是装饰，是Claude理解你期望输出的关键参照。好的示例能让Claude的输出一致性大幅提升。
4. **定义触发时机**。description要写清楚"什么时候用"，否则Claude不知道该不该激活。这也是Skill能被自动触发的前提。
5. **聚焦单一工作流**。这和第1点是一体两面——一个Skill解决一类问题，别贪多。Skill之间的边界清晰，才不会互相干扰。
**最常见的反模式是贪大求全。** 你觉得代码审查和测试生成关系密切，就塞进同一个Skill，结果Claude不知道什么时候该只做审查、什么时候该生成测试。分开两个Skill，各自有清晰的description，触发更精准，执行更一致。
## Skills和MCP的分工
很多人会把Skills和MCP搞混，这里做个澄清。
| 维度 | Skills | MCP |
|------|--------|-----|
| 定位 | 知识和决策框架 | 工具和数据通道 |
| 提供什么 | "怎么做"的指令 | "能做什么"的能力 |
| 类比 | 标准操作流程(SOP) | 工具箱 |
| 示例 | 代码审查的最佳实践 | 访问数据库、调用API |
简单说：**Skills管"脑子"，MCP管"手"**。Skill告诉Claude遇到代码审查任务应该按什么步骤、关注什么维度；MCP让Claude能够实际访问代码仓库、运行测试脚本。
两者不冲突，反而应该配合。比如一个代码审查Skill可以指示Claude"使用MCP的数据库工具查询最近的变更记录，然后按安全→性能→风格的顺序审查"。
## Skills的局限和注意事项
说了这么多好处，也要正视局限：
1. **触发不是100%精准**。Claude的语义匹配偶尔会误判。你写了"Python代码审查"的Skill，它可能对JavaScript代码也触发。解决办法是description尽量限定范围，并在Skill正文的规则里加上"如果代码不是Python，请告知用户"。
2. **Skill之间可能冲突**。如果你有多个description相近的Skill，Claude可能同时触发多个，导致指令混乱。解决办法是确保每个Skill的description有明确的边界。
3. **上下文窗口的竞争**。Skill内容要占用上下文窗口。如果你的Skill特别长，或者同时触发了多个Skill，可能挤占其他重要信息的空间。解决办法是善用references目录做渐进式加载，核心指令精简，细节知识按需加载。
4. **维护成本**。Skill是代码之外的"第二代码库"，需要持续更新。如果你的团队规范变了、技术栈换了，Skill也得跟着改，否则Claude会按过时的标准工作。
## 从零搭建团队Skills体系
如果你是一个团队的技术负责人，想用Skills构建团队级的AI知识体系，建议按这个顺序来：
**第一步：识别高频场景**
观察团队日常工作中，哪些任务和Claude Code配合最多、最需要一致性。通常是代码审查、组件创建、测试编写、部署这几类。
**第二步：从最痛的那个开始**
别一上来就写10个Skill。先解决最痛的那个场景，跑通一个完整的Skill，验证效果，再扩展。经验是：代码审查Skill通常是最佳起点，因为它规则明确、场景高频、效果可衡量。
**第三步：迭代优化**
Skill不是写完就完事。用了一周后，看看Claude的输出有没有偏差，description的触发准不准，references里的参考文档够不够用。根据实际效果调整。
**第四步：逐步扩展**
跑通第一个Skill后，用同样的模式扩展到其他场景。每个Skill都走"识别场景→编写→测试→迭代"的循环。
**第五步：纳入版本管理**
把skills/目录纳入Git版本管理。Skill的变更和代码变更一样需要review和追溯。这样团队每个人用的都是同一套Skill，知识不会因为换人而丢失。
整个过程的核心思想就一句话：**把团队最好的工程师的"隐性知识"变成"显性知识"，再变成Skill让AI用起来。** 这才是Skills系统的最大价值——不是让AI更聪明，而是让AI按你最优秀的人的标准工作。