Skills

目录

1. 什么是 Skills？
2. Skills vs 传统 Prompt vs Tools：核心区别
3. Skills 的核心结构：SKILL.md 详解
4. SKILL.md Frontmatter 字段完全参考
5. 进阶目录结构：scripts / references / assets
6. 底层实现原理：元工具架构（Meta-Tool Architecture）
7. 渐进式披露（Progressive Disclosure）机制
8. Skills 的应用场景
9. 常用设计模式（Patterns）
10. 完整实战示例：从需求到运行
11. 最佳实践与常见错误
12. Skills 与 MCP / Tools / System Prompt 的生态关系

一、什么是 Skills？

一句话定义：Skills 是封装了某类事情应该怎么专业做的可复用能力模块，以 Markdown 文件夹形式存在，AI Agent 按需加载，像调用函数一样反复使用。

在 AI Agent 时代，通用大语言模型（LLM）虽然能生成流畅的文字和代码，但它本质上是一个「无经验的聪明实习生」——它懂很多道理，但不知道你的公司规范是什么、你的项目流程是什么、遇到这个特定任务该走哪套 SOP。

Skills 解决的核心痛点：

• 每次执行相同任务都需要重新在 Prompt 里写一大段指令 → 浪费 token，且不稳定
• Agent 不知道在什么场景下调用哪套流程
• 领域知识、公司规范无法结构化地传递给 AI
• 复杂工作流无法被标准化复用

Skills 的出现，标志着 AI 应用从「对话交互」向「任务执行」的关键跃迁。

Skills 的核心特性

二、Skills vs 传统 Prompt vs Tools：核心区别

在理解 Skills 之前，需要先厘清它与相关概念的边界。

用「实习生培训」来类比

把 AI 想象成一个刚毕业的聪明但没经验的实习生：

• 普通 Prompt = 你每次都要从头教他怎么做事（今天教一遍，明天还得重新教）
• Rule / Memory（规则/记忆） = 你给他贴一张”公司行为守则”在工位上（一直生效，但只能管态度和格式）
• MCP / Tools = 你给他电脑装了一堆软件和 API（他能调用外部工具，但不知道什么时候该用、怎么组合用）
• Skills = 你直接给他一整套 **”岗位培训大礼包”**（PDF+流程图+SOP+话术模板+常用脚本），告诉他：”当老板让你做这类事情时，就按这个文件夹里的方法来做”

技术层面对比

Tools 扩展「能力」，Skills 扩展「能力运用的方式」

一个更精准的区分：

• Tools 让 Agent 能做某件事（比如能搜索网页）
• Skills 让 Agent 知道在什么情况下、按什么流程、用什么标准去做某件事

工具扩展 capability（能力），Skills 扩展 competence（胜任力）。

三、Skills 的核心结构：SKILL.md 详解

每个 Skill 就是一个文件夹，文件夹名即技能标识（推荐 kebab-case 小写+连字符）。文件夹中唯一必须存在的文件是 SKILL.md。

最简目录结构

1
2
3

~/.claude/skills/
└── my-skill/          ← 技能文件夹名
    └── SKILL.md       ← 唯一必填文件（必须全大写 + .md 小写）

SKILL.md 基本模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

---
name: your-skill-name
description: >-
  What it does and when Claude should use it.
  Trigger scenarios: when user asks to..., keywords like...
version: 1.0
author: yourname
---

# Skill Title

## Overview
[What this skill does and what problem it solves]

## Instructions

### Step 1: [First Action]
[Imperative, concrete instructions]

### Step 2: [Next Action]
[Imperative, concrete instructions]

## Output Format
[How to structure results]

## Examples
- Example 1: ...
- Example 2: ...

## Guidelines
- Guideline 1
- Guideline 2

SKILL.md 由两部分构成：

1. YAML Frontmatter（--- 之间的部分）：配置元数据，控制 Skill「如何被发现和运行」
2. Markdown 正文：Prompt 内容，控制 Claude「具体做什么」

四、SKILL.md Frontmatter 字段完全参考

这是整个 Skill 系统中最关键的部分，因为 Claude 正是靠这里的 description 来决定是否加载当前 Skill。

4.1 name（必填）

1

name: code-comment-expert

• 只能使用小写字母、数字和连字符
• 最多 64 个字符
• 同时也是 /slash 命令名（用户可以用 /code-comment-expert 手动触发）

4.2 description（必填 · 最关键字段！）

1
2
3
4

description: >-
  为代码添加专业、清晰的中英双语注释。
  适合缺少文档、可读性差、需要分享审查的代码。
  常见触发场景：加注释、注释一下、加文档、explain this、improve readability

• 这是 Claude 判断是否加载该 Skill 的唯一依据
• 最多 1024 个字符
• 建议明确写出：这个 Skill 做什么 + 什么时候用它 + 触发关键词

⚠️ 关键原则：description 写得越精准，Skill 被正确触发的概率越高。

4.3 trigger_keywords（强烈推荐）

1
2
3
4
5
6
7
8

trigger_keywords:
  - 加注释
  - 注释
  - 加文档
  - explain code
  - document
  - comment this
  - readability

4.4 allowed-tools（可选）

1
2
3
4
5

# 推荐：精确限定工具范围
allowed-tools: "Read,Write,Edit,Glob,Grep"

# 推荐：仅允许特定 bash 命令
allowed-tools: "Bash(git status:*),Bash(git diff:*),Read,Grep"

4.5 model（可选）

1
2
3

model: "claude-opus-4-20250514"   # 使用特定模型
# 或
model: "inherit"                   # 继承用户当前会话模型（默认）

4.6 version（可选）

1

version: "1.0.0"

4.7 disable-model-invocation（可选）

1

disable-model-invocation: true

设为 true 后，该 Skill 只能通过用户手动输入 /skill-name 触发，不会被自动调用。

4.8 mode（可选）

1

mode: true

将该 Skill 标记为”模式命令”，适合 debug-mode、review-mode 等全局行为修改 Skill。

五、进阶目录结构：scripts / references / assets

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

~/.claude/skills/react-component-review/
├── SKILL.md                    # 核心指令 + 元数据（建议控制在 400 行内）
│
├── templates/                  # 常用模板（Claude 按需读取）
│   ├── functional.tsx.md
│   └── class-component.md
│
├── examples/                   # 优秀/反例（给 Claude 看标准）
│   ├── good.md
│   └── anti-pattern.md
│
├── references/                 # 规范、规则、参考文档（加载进 Context）
│   ├── hooks-rules.md
│   └── naming-convention.md
│
└── scripts/                    # 可执行脚本
    ├── validate-props.py
    └── check-cycle-deps.sh

三个目录的核心区别

使用 {baseDir} 变量（必须！）

1
2

python {baseDir}/scripts/analyzer.py --path "$TARGET"
python /home/user/.claude/skills/my-skill/scripts/analyzer.py

六、底层实现原理：元工具架构（Meta-Tool Architecture）

6.1 Skills 本质上是什么？

Skills 不是可执行代码。它们不运行 Python 或 JavaScript，背后没有 HTTP Server。

Skills 的本质是：专门化的 Prompt 模板，通过注入对话上下文来修改 Claude 的推理方式。

当一个 Skill 被调用时，发生的事情是：

1. 将 SKILL.md 的内容加载为详细指令
2. 将这些指令作为新的 User Message 注入对话 Context
3. 修改执行环境（允许的工具列表、模型选择）
4. Claude 在这个被「增强」的 Context 下继续执行任务

6.2 Skill 元工具（Meta-Tool）设计

在 Claude Code 内部，所有 Skills 通过一个叫做 Skill（大写 S）的元工具来管理：

1
2
3
4
5
6
7
8

Claude 看到的工具列表：
├── Read          ← 普通工具
├── Write         ← 普通工具
├── Bash          ← 普通工具
└── Skill         ← 元工具（管理所有 skills）
    ├── pdf
    ├── xlsx
    └── code-comment-expert

元工具 Skill 的描述中包含了所有可用 Skills 的 name 和 description 列表，Claude 用自身的语言理解能力来判断是否匹配。

重要：技能选择没有算法路由，没有意图分类器，没有 Embedding 匹配。这是纯粹的 LLM 推理——决策发生在 Transformer 的前向传播中。

6.3 实际 API 请求结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "model": "claude-sonnet-4-5",
  "messages": [
    {"role": "user", "content": "帮我给这段代码加上注释"}
  ],
  "tools": [
    {
      "name": "Skill",
      "description": "Execute a skill...\n\n<available_skills>\n\"code-comment-expert\": 为代码添加专业注释...\n</available_skills>",
      "input_schema": {
        "type": "object",
        "properties": {
          "command": {"type": "string", "description": "The skill name"}
        }
      }
    },
    {"name": "Bash"},
    {"name": "Read"}
  ]
}

6.4 Skill 执行时的双消息注入机制

当 Claude 决定调用某个 Skill，系统会注入两条消息：

消息一：用户可见的状态提示（isMeta: false）

1
2

<command-message>The "code-comment-expert" skill is loading</command-message>
<command-name>code-comment-expert</command-name>

消息二：完整 Skill 指令（isMeta: true，用户不可见）

1
2
3
4
5
6
7
8

你现在是「专业代码注释专家」。

## 核心原则
- 只在缺少注释或可读性明显不足处添加
- 优先使用英文 JSDoc / TSDoc 风格
...（完整的 SKILL.md 正文）

Base directory: /home/user/.claude/skills/code-comment-expert

6.5 消息流对比

1
2
3
4
5
6
7
8
9
10

普通工具（如 Read）：
  assistant → tool_use (Read file.txt)
  user      → tool_result (file contents...)

Skill 工具：
  assistant → tool_use (Skill: code-comment-expert)
  user      → tool_result (success)
  user      → <command-message>...</command-message>     [可见]
  user      → [完整 SKILL.md 指令, isMeta: true]        [隐藏]
  user      → [权限消息 command_permissions]             [隐藏]

七、渐进式披露（Progressive Disclosure）机制

三层渐进式披露

1
2
3
4
5

第一层：元数据（name + description）约 200 tokens
    ↓ Claude 判断匹配
第二层：完整 SKILL.md 内容加载进 Context，约 1500-5000 tokens
    ↓ Claude 开始执行，发现需要更多信息
第三层：按需加载 scripts/ references/ assets/ 中的文件

Token 消耗对比

当用户只用到 1 个 Skill 时，节省约 18,000 tokens。

八、Skills 的应用场景

8.1 企业内部规范沉淀

1
2
3
4
5

.claude/skills/
├── commit-convention/     ← Git 提交规范
├── code-review-standard/  ← 代码审查标准
├── api-doc-generator/     ← API 文档生成规范
└── pr-template/           ← PR 描述模板

8.2 复杂文档处理工作流

• PDF Skill：调用 pdftotext 工具提取文本，按特定格式整理
• Excel Skill：读取数据、分析结构、生成可视化报告
• 技术文章转公众号 Skill：总结→翻译→调整风格→加标题→输出 Markdown

8.3 领域专家系统

• 安全审计 Skill：按 OWASP Top 10 逐一检查代码漏洞
• 性能优化 Skill：按特定框架的最佳实践审查代码性能
• 财务分析 Skill：按公司财务建模规范分析数据

8.4 多步骤向导流程

复杂的初始化、配置、部署流程可以封装为 Skills：

• 新项目初始化向导
• 数据库迁移助手
• CI/CD 配置生成器

8.5 跨项目知识共享

个人全局 Skills（~/.claude/skills/）可以在所有项目中使用：

• 个人写作风格 Skill
• 常用代码模板 Skill
• 个人调试流程 Skill

九、常用设计模式（Patterns）

Pattern 1：脚本自动化（Script Automation）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: dependency-audit
description: 审计项目依赖安全漏洞，适合发布前检查或定期安全审查
allowed-tools: "Bash(npm audit:*),Read,Write"
---

# 依赖安全审计

## 执行流程

1. 运行安全审计脚本：
   python {baseDir}/scripts/audit.py --path "." --output audit-report.json
2. 读取生成的 audit-report.json
3. 按严重程度分类展示漏洞
4. 给出修复建议

Pattern 2：读取-处理-输出（Read-Process-Write）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
name: tech-to-wechat
description: 将技术文章转换为公众号风格，适合需要发布技术内容的场景
allowed-tools: "Read,Write"
---

# 技术文章公众号化

## 处理步骤

1. 用 Read 工具读取原始文章
2. 执行转换：简化术语、拆分长段、增加过渡句
3. 生成 3-5 个候选标题（包含数字或疑问句式）
4. 用 Write 工具输出最终 Markdown 文件

Pattern 3：搜索-分析-报告（Search-Analyze-Report）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

---
name: dead-code-finder
description: 检测项目中未被使用的代码，适合代码库清理和重构前使用
allowed-tools: "Grep,Read,Glob"
---

# 死代码检测

## 分析流程

### Pass 1：广泛扫描
1. 用 Glob 获取所有 .ts/.tsx/.js/.jsx 文件列表
2. 用 Grep 提取所有 export 的函数/类/变量名

### Pass 2：引用验证
对每个已导出符号，用 Grep 搜索引用，引用数为 0 则标记为疑似死代码

### Pass 3：报告生成
输出表格：文件路径、符号名称、类型、建议（删除/保留/待确认）

Pattern 4：向导式多步骤工作流（Wizard-Style Workflow）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
name: new-feature-wizard
description: 新功能开发向导，引导完成从需求分析到代码生成的完整流程
allowed-tools: "Read,Write,Bash(git:*)"
---

## Step 1：需求澄清
询问：功能名称、用户故事、技术约束，等待用户确认后继续。

## Step 2：技术方案设计
读取现有代码，设计接口，输出技术方案，等待用户确认。

## Step 3：代码生成
按照确认的方案生成代码，参考 references/coding-standards.md

十、完整实战示例：从需求到运行

场景：Python 代码规范强制 Skill

需求：团队规定所有 Python 内部辅助函数必须以 _internal_ 前缀命名。

Step 1：创建目录结构

1
2

cd my-project
mkdir -p .claude/skills/python-naming-standard

Step 2：编写 SKILL.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

---
name: python-naming-standard
description: >-
  当用户要求重构、审查或编写 Python 代码时，请参考此内部命名规范。
  适用场景：写代码、重构、code review、命名建议、代码审查
trigger_keywords:
  - 写代码
  - 重构
  - code review
  - 命名
  - Python 函数
version: 1.0
allowed-tools: "Read,Write,Edit"
---

# Python 内部命名规范

## 核心规则

1. **所有内部辅助函数**必须以 `_internal_` 前缀命名
2. **公共 API 函数**不使用下划线前缀
3. **私有方法**（类内部）使用 `__` 双下划线前缀

## 命名示例

正确：内部辅助函数
def _internal_calculate_risk(score: float) -> float: ...

正确：公共 API
def calculate_user_discount(user_id: str) -> float: ...

错误：内部函数缺少 _internal_ 前缀
def _calculate_risk(score: float) -> float: ...

## 执行要求

- 生成新代码时，自动按此规范命名
- 审查现有代码时，发现违规立即指出并给出重命名建议

Step 3：Claude 自动生成符合规范的代码

输入：帮我写一个计算用户折扣的函数

Claude 自动加载 Skill，输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

def calculate_user_discount(user_id: str, score: int, total_spent: float) -> float:
    """计算用户折扣率。"""
    risk_factor = _internal_calculate_risk_factor(score)
    loyalty_bonus = _internal_get_loyalty_bonus(total_spent)
    return min(0.3, risk_factor + loyalty_bonus)


def _internal_calculate_risk_factor(score: int) -> float:
    """内部：根据积分计算风险系数。"""
    if score >= 1000:
        return 0.15
    elif score >= 500:
        return 0.10
    return 0.05


def _internal_get_loyalty_bonus(total_spent: float) -> float:
    """内部：根据历史消费计算忠诚度奖励。"""
    if total_spent >= 10000:
        return 0.10
    elif total_spent >= 5000:
        return 0.05
    return 0.0

所有内部函数自动带上 _internal_ 前缀，无需任何手动提示。

Step 4：添加验证脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# .claude/skills/python-naming-standard/scripts/validate_naming.py
import ast, sys
from pathlib import Path

def check_file(filepath: str) -> list:
    violations = []
    tree = ast.parse(Path(filepath).read_text())
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            name = node.name
            if name.startswith('_') and not name.startswith('__') and not name.startswith('_internal_'):
                violations.append({
                    'line': node.lineno,
                    'current': name,
                    'suggested': f'_internal_{name.lstrip("_")}'
                })
    return violations

if __name__ == '__main__':
    filepath = sys.argv[1]
    violations = check_file(filepath)
    if violations:
        print(f"发现 {len(violations)} 处命名违规：")
        for v in violations:
            print(f"  第 {v['line']} 行: {v['current']} → 建议改为: {v['suggested']}")
    else:
        print("命名规范检查通过")

十一、最佳实践与常见错误

最佳实践

1. Description 写清楚触发场景

1
2
3
4
5
6
7

# 好的 description
description: >-
  为 React 组件进行 code review，检查性能、可维护性和最佳实践。
  触发关键词：code review, 审查, 组件, react, 优化

# 差的 description
description: React component reviewer

2. 使用命令式语言，而非第二人称

1
2

分析代码中的安全漏洞...
你应该分析代码中的安全漏洞...

3. 控制 SKILL.md 长度：建议 400-800 行，超出内容放 references/ 按需加载

4. 最小权限原则

1
2

allowed-tools: "Read,Grep,Glob"
allowed-tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch"

5. 始终使用 {baseDir} 而非绝对路径

常见错误排查

十二、Skills 与 MCP / Tools / System Prompt 的生态关系

完整的 Agent 能力层次

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

┌─────────────────────────────────────────────────────────┐
│                    用户意图                              │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│              Skills（能力运用层）                        │
│  · 什么时候用什么工具   · 按什么流程执行任务             │
│  · 按什么标准产出结果                                    │
└──────┬───────────────────────────────────┬──────────────┘
       │                                   │
┌──────▼──────┐                   ┌───────▼──────────────┐
│   Tools     │                   │   MCP Servers        │
│ (能力执行层)│                   │   (能力扩展层)        │
│ Read/Write  │                   │  Database/API/etc.   │
└─────────────┘                   └──────────────────────┘

各层能力定位

四者缺一不可，各司其职。Skills 的价值在于把分散的 Tools 和 MCP 能力组织成有意义的、可复用的工作流。

附录：Skills 快速参考卡

必填字段

1
2
3
4
5
6
7

---
name: skill-name              # 小写字母+数字+连字符，≤64字符
description: >-               # 关键！Claude靠它决定是否加载，≤1024字符
  What it does.
  When to use it.
  Trigger scenarios: ...
---

目录结构速查

1
2
3
4
5

my-skill/
├── SKILL.md          # 必须
├── scripts/          # 可执行脚本（Bash/Python）
├── references/       # 参考文档（加载进 Context）
└── assets/           # 模板文件（按路径引用）

Skills 加载位置优先级

1
2
3
4

.claude/skills/           (项目级，最高优先级)
~/.claude/skills/         (用户全局)
~/.config/claude/skills/  (系统配置)
内置 Skills               (最低优先级)

Path 引用规范

1
2
3

python {baseDir}/scripts/process.py
参考 {baseDir}/references/standards.md
python /home/user/.claude/skills/my-skill/scripts/process.py