# Claude Code Skill架构深度剖析：从渐进式加载到自动化评估
## 概述
本教程面向已掌握Claude Code基础使用的开发者，深入剖析Skill系统的内部运行机制——包括渐进式上下文加载（Progressive Context Loading）、两层索引架构、Token成本模型、两种Skill范式（工作流型 vs 能力增强型）以及Skills 2.0引入的自动化评估体系。学完本教程，你将理解Skill系统"为什么这样设计"以及"如何编写高质量、低Token消耗的Skill"。
**适用人群**：有Claude Code使用经验、已创建过简单Skill、希望深入理解Skill内部机制并进行品质工程的中高级开发者。
**前置条件**：
- Claude Code ≥ 1.0.21（支持Skills 2.0评估体系）
- 熟悉YAML和Markdown语法
- 理解LLM上下文窗口和Token的基本概念
- 至少创建过一个SKILL.md文件
---
## 第一章：Skill架构全景——四层渐进式加载
### 1.1 为什么需要渐进式加载
传统做法是将所有指令塞进CLAUDE.md，每轮对话都要承载全部文本的Token开销。当你的项目规范超过5000字，Token消耗变得不可忽视。Anthropic在2025年12月发布Agent Skills时，核心设计目标就是解耦"知识存储"与"推理时加载"。
```
传统模式（CLAUDE.md全量加载）：
┌─────────────────────────────────────┐
│ 用户消息 + CLAUDE.md(5000 tokens) │
│ + 对话历史 + Skill全量文本 │ → 每轮都消耗完整Token
│ → 200K上下文窗口很快被填满 │
└─────────────────────────────────────┘
Skill渐进式加载：
┌──────────┐ ┌──────────┐ ┌──────────────┐
│ 名称索引 │ → │ 描述匹配 │ → │ 按需加载正文 │
│ ~100 tkn │ │ ~50 tkn │ │ 完整内容 │
└──────────┘ └──────────┘ └──────────────┘
第一阶段 第二阶段 第三阶段
```
### 1.2 三层加载机制详解
Skill的加载并非"一次性注入全部文本"，而是经过三个阶段：
**第一阶段：名称索引（Metadata Loading）**
Claude Code启动时，扫描`.claude/skills/`、`~/.claude/skills/`以及已安装插件的skills目录。它只读取每个SKILL.md的YAML frontmatter中的`name`和`description`字段，构建一个轻量级的名称-描述索引。这个阶段每个Skill只消耗约50-100个Token。
```yaml
---
name: api-doc-writer
description: "根据OpenAPI规范自动生成API文档，支持REST和GraphQL端点描述"
---
```
这个简短的YAML就是第一阶段Claude"看到"的全部信息。一个包含50个Skill的目录，索引阶段总共只消耗约3000-5000个Token。
**第二阶段：相关性匹配（Relevance Matching）**
当用户发送消息时，Claude根据消息语义与第一阶段索引中的name/description进行匹配。匹配算法不是简单的关键词搜索，而是基于语义相似度的判断。这就是为什么`description`字段的质量如此关键——它决定了Skill能否被正确触发。
```
用户说："帮我写API文档"
↓
Claude扫描索引：
api-doc-writer: "根据OpenAPI规范自动生成API文档..." ← 匹配度 0.92
db-migrator: "数据库迁移工具..." ← 匹配度 0.31
test-gen: "测试生成工具..." ← 匹配度 0.15
↓
选中 api-doc-writer，进入第三阶段
```
**第三阶段：按需注入（On-Demand Injection）**
只有被选中的Skill，其完整SKILL.md内容（包括Markdown正文、所有instructions、references目录下的文件引用）才会被注入到当前上下文窗口中。这就是"渐进式"的核心——你拥有100个Skill，但每轮对话只加载被触发的1-2个。
### 1.3 四层架构总览
```mermaid
graph TB
subgraph "Layer 0: 扫描层 Scan"
S1[".claude/skills/"]
S2["~/.claude/skills/"]
S3["插件 skills/"]
end
subgraph "Layer 1: 索引层 Index"
I1["name + description"]
I2["每个Skill ~100 tokens"]
end
subgraph "Layer 2: 匹配层 Match"
M1["用户消息语义分析"]
M2["description相似度评分"]
M3["触发阈值判定"]
end
subgraph "Layer 3: 注入层 Inject"
N1["完整SKILL.md正文"]
N2["references/目录文件"]
N3["scripts/目录脚本"]
N4["注入到上下文窗口"]
end
S1 --> I1
S2 --> I1
S3 --> I1
I1 --> M1
M1 --> M2
M2 --> M3
M3 --> N1
N1 --> N2
N2 --> N3
N3 --> N4
```
### 1.4 实测Token消耗对比
| 场景 | CLAUDE.md全量 | Skill渐进式 | 节省比例 |
|------|--------------|-------------|---------|
| 50个Skill目录，激活1个 | ~25,000 tokens/轮 | ~2,500 tokens/轮 | 90% |
| 10个Skill，激活2个 | ~8,000 tokens/轮 | ~3,000 tokens/轮 | 62% |
| 3个Skill，全部激活 | ~4,000 tokens/轮 | ~4,000 tokens/轮 | 0% |
| 100个Skill，激活1个 | ~50,000 tokens/轮 | ~3,000 tokens/轮 | 94% |
**关键洞察**：Skill数量越多，渐进式加载的优势越明显。这是Skill系统优于CLAUDE.md全量方案的根本原因。
---
## 第二章：两种Skill范式——工作流型 vs 能力增强型
### 2.1 范式定义
Anthropic在Skills 2.0中明确区分了两种Skill类型，理解这个区分是编写高质量Skill的基础：
**工作流型Skill（Workflow Skills）**
定义一个多步骤的执行流程，Claude按照固定步骤依次执行。像一个"配方"——它告诉Claude"先做什么、再做什么、最后做什么"。
```yaml
---
name: release-workflow
description: "标准化发版流程：代码审查→测试→版本号更新→Changelog→打Tag→推送"
---
```
**特征**：
- 有明确的步骤顺序
- 每个步骤有具体的输入和预期输出
- 成功标准明确（版本号正确、Tag存在、Changelog完整）
- 适合用checklist式Markdown编写
**能力增强型Skill（Capability Uplift Skills）**
赋予Claude一个它原本不擅长的新能力。像一个"知识手册"——它教会Claude如何处理一类特定问题。
```yaml
---
name: accessibility-auditor
description: "WCAG 2.2 AA级无障碍审查专家，支持React/Vue/Angular组件的自动化无障碍检测与修复建议"
---
```
**特征**：
- 没有固定步骤，而是提供知识和判断框架
- 需要Claude根据具体情况灵活应用
- 成功标准较难量化（"审查是否全面"）
- 适合用参考文档+示例式Markdown编写
### 2.2 两种范式对评估策略的影响
这个区分直接决定了你的测试策略：
| 维度 | 工作流型 | 能力增强型 |
|------|---------|-----------|
| 测试重点 | 步骤是否按序执行 | 知识是否被正确应用 |
| 评估方式 | 结构化断言（JSON eval） | 语义评估（人工+自动混合） |
| 通过标准 | 二元判断（是/否） | 梯度评分（1-5分） |
| 回归风险 | 低（步骤明确） | 高（模型更新可能改变行为） |
| eval.json设计 | 每步一个test case | 端到端场景test case |
### 2.3 识别你的Skill属于哪种类型
一个简单的判断方法：
```
问自己：这个Skill是在告诉Claude"怎么做"还是"做什么"？
"怎么做"（How） → 工作流型
示例：部署流程、发版检查清单、PR审查清单
"做什么"（What） → 能力增强型
示例：安全审计、代码风格审查、特定框架最佳实践
```
很多Skill实际上是混合型的——外层是工作流，内层步骤可能包含能力增强。这种情况下，建议将核心能力拆分为独立的能力增强型Skill，然后在工作流型Skill的references中引用。
---
## 第三章：SKILL.md Frontmatter完整参考
### 3.1 核心字段（必填）
```yaml
---
name: my-skill # 必填，唯一标识符
description: "简洁描述" # 必填，决定触发匹配质量
---
```
**name字段规范**：
- 使用kebab-case命名
- 长度建议3-30个字符
- 应反映Skill的核心功能，避免过于通用
- 好的例子：`react-component-auditor`、`db-migration-planner`
- 坏的例子：`helper`、`tool1`、`my-awesome-skill-that-does-everything`
**description字段规范**：
- 控制在1-2句话（50-150个字符）
- 包含核心关键词（用于语义匹配）
- 明确说明触发场景："当用户需要..."
- 包含技术限定词（如框架名、语言名）
```yaml
# 好的description
description: "PostgreSQL数据库迁移规划器。当用户需要修改数据库Schema、添加列、创建索引或进行数据迁移时使用。支持生成可逆迁移脚本。"
# 坏的description
description: "数据库工具"
```
### 3.2 扩展字段（可选但推荐）
```yaml
---
name: api-security-scanner
description: "REST API安全扫描器，自动检测OWASP Top 10漏洞"
# 触发控制
triggers: # 显式定义触发条件
- "扫描API安全"
- "检查接口漏洞"
- "OWASP"
# 元数据
metadata:
version: "2.1.0"
author: "security-team"
tags: ["security", "api", "owasp"]
min_claude_version: "1.0.21"
# 子Agent控制
subagent:
model: "sonnet" # 子Agent使用的模型
max_turns: 15 # 最大交互轮次
allowedTools: # 允许使用的工具白名单
- Read
- Grep
- Glob
- Bash
blockedTools: # 禁止使用的工具
- Edit
- Write
# 参考文件
references:
- owasp-top-10-checklist.md
- common-vulnerabilities.md
---
```
### 3.3 高级字段详解
**triggers字段**：
显式触发条件是对description的补充。当用户的消息匹配到trigger关键词时，Skill的激活概率显著提升。注意不要过度使用——3-5个精准的trigger远好于20个模糊的。
```yaml
# 精准触发（推荐）
triggers:
- "扫描API安全"
- "安全审查API"
- "OWASP检查"
# 过度触发（不推荐）
triggers:
- "安全"
- "API"
- "检查"
- "扫描"
- "漏洞"
- "测试"
# 这些词太宽泛，会导致误触发
```
**subagent配置**：
当Skill需要Claude创建子Agent（通过Task工具）来执行任务时，这些配置控制子Agent的行为边界。这是Skill安全模型的核心。
```yaml
# 严格只读模式——适合审查类Skill
subagent:
allowedTools:
- Read
- Grep
- Glob
- Bash
blockedTools:
- Edit
- Write
# 受限写入模式——适合代码生成类Skill
subagent:
allowedTools:
- Read
- Grep
- Glob
- Bash
- Edit
blockedTools:
- Write # 不允许创建新文件
```
---
## 第四章：Skill品质工程——评估体系实战
### 4.1 Skills 2.0评估体系架构
2026年3月，Anthropic为skill-creator插件引入了完整的评估系统。这个系统包含三个核心组件：
```mermaid
graph LR
subgraph "Skills 2.0 评估体系"
A["eval.json
测试用例定义"]
B["Benchmark
基准测试运行器"]
C["A/B Testing
版本对比"]
end
A -->|"提供test cases"| B
B -->|"生成评分"| C
C -->|"版本决策"| D["生产发布"]
style A fill:#4a90d9,color:#fff
style B fill:#7b68ee,color:#fff
style C fill:#20b2aa,color:#fff
style D fill:#ff6b6b,color:#fff
```
### 4.2 eval.json格式规范
eval.json是Skill的"单元测试文件"，定义了一组测试用例来验证Skill的行为是否符合预期。
**基本结构**：
```json
{
"skill": "api-security-scanner",
"version": "2.1.0",
"evals": [
{
"name": "detect-sql-injection",
"description": "检测SQL注入漏洞",
"input": "扫描以下API端点的安全性：POST /api/users/login",
"context": {
"files": {
"api/login.ts": "app.post('/login', (req, res) => {\n const query = `SELECT * FROM users WHERE email = '${req.body.email}'`;\n db.query(query);\n})"
}
},
"assertions": [
{
"type": "contains",
"value": "SQL注入",
"required": true
},
{
"type": "contains",
"value": "参数化查询",
"required": true
},
{
"type": "not_contains",
"value": "没有安全问题",
"required": true
}
]
},
{
"name": "detect-xss-stored",
"description": "检测存储型XSS",
"input": "审查这个用户资料更新接口的安全性",
"context": {
"files": {
"api/profile.ts": "app.put('/profile', (req, res) => {\n const bio = req.body.bio;\n db.query('UPDATE users SET bio = ? WHERE id = ?', [bio, req.user.id]);\n})"
}
},
"assertions": [
{
"type": "contains",
"value": "XSS",
"required": true
},
{
"type": "contains_any",
"value": ["sanitize", "escape", "DOMPurify", "消毒"],
"required": true
}
]
}
]
}
```
**断言类型完整参考**：
| 断言类型 | 含义 | 示例 |
|---------|------|------|
| `contains` | 输出必须包含指定文本 | `"value": "SQL注入"` |
| `not_contains` | 输出不得包含指定文本 | `"value": "没有安全问题"` |
| `contains_any` | 输出至少包含列表中的一个 | `"value": ["sanitize", "escape"]` |
| `contains_all` | 输出必须包含列表中的全部 | `"value": ["OWASP", "A03"]` |
| `matches_regex` | 输出匹配正则表达式 | `"value": "CVSS.*[0-9]\\.[0-9]"` |
| `json_path` | 从JSON输出中提取值验证 | `"path": "$.vulnerabilities.length()"` |
| `semantic_match` | 语义相似度匹配 | `"value": "建议使用参数化查询"` |
### 4.3 创建你的第一个eval体系
以一个"Git Commit Message规范检查"Skill为例，演示完整的eval创建流程：
**第一步：定义Skill**
```yaml
# .claude/skills/commit-linter/SKILL.md
---
name: commit-linter
description: "Git提交消息规范检查器。根据Conventional Commits规范验证提交消息格式，支持Angular、Vue等不同风格预设。"
triggers:
- "检查commit消息"
- "提交消息格式"
- "commit规范"
metadata:
version: "1.0.0"
author: "devops-team"
---
# Git提交消息规范检查器
## 规范规则
根据Conventional Commits v1.0.0规范验证提交消息：
1. **格式要求**：`(): `
2. **允许的type**：feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
3. **subject限制**：
- 不超过72个字符
- 不以句号结尾
- 使用祈使语气（"add feature"而非"added feature"）
4. **body要求**（如存在）：
- 与subject空一行
- 每行不超过100个字符
5. **Breaking Change**：在type后加`!`或在body中包含`BREAKING CHANGE:`
## 检查流程
1. 解析提交消息的结构
2. 验证type是否在允许列表中
3. 检查scope格式（如有）
4. 验证subject长度和格式
5. 检查body格式（如有）
6. 输出结构化的检查报告
## 输出格式
```
✅/❌ [规则名]: 描述
建议: 修复建议（如适用）
```
```
**第二步：编写eval.json**
```json
{
"skill": "commit-linter",
"version": "1.0.0",
"evals": [
{
"name": "valid-feat-commit",
"description": "标准feat提交应通过检查",
"input": "检查这个commit消息：feat(auth): add JWT token refresh support",
"assertions": [
{"type": "contains", "value": "✅", "required": true},
{"type": "not_contains", "value": "❌", "required": true}
]
},
{
"name": "invalid-type-detected",
"description": "不合法的type应被检测出",
"input": "检查这个commit消息：added(auth): 新增JWT刷新功能",
"assertions": [
{"type": "contains", "value": "❌", "required": true},
{"type": "contains_any", "value": ["type", "类型", "不合法", "invalid"], "required": true}
]
},
{
"name": "subject-too-long",
"description": "超过72字符的subject应被标记",
"input": "检查这个commit消息：feat: this is an extremely long commit message subject that definitely exceeds the seventy-two character limit we have set",
"assertions": [
{"type": "contains", "value": "❌", "required": true},
{"type": "contains_any", "value": ["72", "长度", "length", "字符"], "required": true}
]
},
{
"name": "breaking-change-format",
"description": "Breaking Change标记应被正确识别",
"input": "检查这个commit消息：feat(api)!: change authentication endpoint response format",
"assertions": [
{"type": "contains_any", "value": ["BREAKING", "breaking change", "破坏性"], "required": true}
]
},
{
"name": "multi-rule-violation",
"description": "多个规则违反应全部列出",
"input": "检查这个commit消息：Added a really really long subject line that violates multiple rules at once.",
"assertions": [
{"type": "contains", "value": "❌", "required": true},
{"type": "contains_any", "value": ["type", "类型"], "required": true},
{"type": "contains_any", "value": ["长度", "length", "字符", "72"], "required": true},
{"type": "contains_any", "value": ["句号", "period", "结尾"], "required": true}
]
}
]
}
```
**第三步：运行评估**
使用skill-creator插件运行评估：
```bash
# 在Claude Code中调用skill-creator
# 方法一：直接请求评估
> 请使用skill-creator评估 commit-linter skill 的质量
# 方法二：指定eval文件
> 运行 .claude/skills/commit-linter/eval.json 中的所有测试用例
# 方法三：A/B对比
> 对比 commit-linter v1.0.0 和 v1.1.0 的评估结果
```
**第四步：解读评估报告**
评估运行后，skill-creator会生成类似以下格式的报告：
```
📊 Skill评估报告：commit-linter v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
总通过率: 4/5 (80%)
✅ valid-feat-commit 通过 (3/3 assertions)
✅ invalid-type-detected 通过 (2/2 assertions)
✅ subject-too-long 通过 (2/2 assertions)
⚠️ breaking-change-format 部分通过 (1/2 assertions)
✅ multi-rule-violation 通过 (3/3 assertions)
失败断言详情：
⚠️ breaking-change-format:
- expected: 包含 "破坏性" 或 "BREAKING CHANGE"
- actual: 输出中使用了 "major change" 而非标准术语
- 建议: 在Skill指令中明确要求使用标准术语 "BREAKING CHANGE"
```
### 4.4 Carpathy式改进循环
Andrej Karpathy提出的"eval驱动开发"循环在Skill开发中同样适用：
```mermaid
graph TD
A["编写/更新SKILL.md"] --> B["运行eval.json"]
B --> C{"全部通过?"}
C -->|"是"| D["发布新版本"]
C -->|"否"| E["分析失败用例"]
E --> F["修改Skill指令"]
F --> G["重新运行eval"]
G --> H{"通过率提升?"}
H -->|"是"| D
H -->|"否"| I["回滚 + 调整策略"]
I --> A
D --> J["等待模型更新
或新test case"]
J --> A
```
**实操步骤**：
1. **先写eval再写Skill**（测试驱动开发）：定义5-10个典型test case，覆盖正常路径和边界情况
2. **运行基线评估**：记录初始通过率
3. **迭代改进**：每次只修改SKILL.md的一处指令，重新运行评估
4. **达到80%+通过率后发布**：不必追求100%，因为模型行为有天然的不确定性
5. **定期回归测试**：每次Claude模型更新后重新运行评估
### 4.5 eval.json设计原则
**覆盖矩阵**：
| 测试维度 | 占比 | 说明 |
|---------|------|------|
| 正常路径（Happy Path） | 30% | 验证核心功能正常工作 |
| 边界条件 | 25% | 空输入、超长输入、特殊字符 |
| 错误处理 | 20% | 无效输入、矛盾指令 |
| 否定测试 | 15% | 验证Skill不会产生错误输出 |
| 回归测试 | 10% | 针对之前修复的Bug添加的用例 |
**每个test case的设计检查清单**：
- [ ] `name`清晰描述测试意图
- [ ] `input`模拟真实用户消息
- [ ] `context`提供必要的文件内容（如涉及代码分析）
- [ ] `assertions`至少包含一个正向断言和一个负向断言
- [ ] 断言值具体且可验证，避免过于宽泛
- [ ] 没有与其他test case重复
---
## 第五章：Skill目录结构与文件组织
### 5.1 推荐目录结构
```
.claude/skills/
├── commit-linter/ # 一个Skill = 一个目录
│ ├── SKILL.md # 主文件（必填）
│ ├── eval.json # 评估用例（推荐）
│ ├── references/ # 参考文档
│ │ ├── conventional-commits.md # 规范原文摘要
│ │ └── common-mistakes.md # 常见错误模式
│ └── scripts/ # 辅助脚本
│ └── validate.sh # 外部验证脚本
│
├── api-security-scanner/
│ ├── SKILL.md
│ ├── eval.json
│ └── references/
│ ├── owasp-top-10.md
│ └── severity-matrix.md
│
└── release-workflow/
├── SKILL.md
├── eval.json
└── references/
├── semver-rules.md
└── changelog-template.md
```
### 5.2 references目录的作用
references目录中的文件不会被索引阶段加载，只有在Skill被激活时才会注入。这意味着你可以在references中放置大量详细文档，而不用担心影响索引阶段的Token消耗。
**什么内容应该放在references中**：
| 放在SKILL.md正文中 | 放在references/中 |
|-------------------|------------------|
| 核心执行步骤 | 详细规范文档 |
| 关键决策规则 | 完整的错误码列表 |
| 输出格式要求 | 第三方API参考 |
| 少量示例（2-3个） | 大量示例集合 |
### 5.3 从CLAUDE.md迁移到Skill
当你发现CLAUDE.md膨胀到超过2000字时，是时候拆分了：
```bash
# 查看CLAUDE.md大小
wc -w CLAUDE.md
# 如果超过2000字，考虑按主题拆分为独立Skill
# 步骤：
# 1. 识别CLAUDE.md中的独立主题
# 2. 每个主题创建一个Skill目录
# 3. 将核心规则移入SKILL.md
# 4. 将详细参考移入references/
# 5. 精简CLAUDE.md只保留全局规则
```
**迁移前后对比**：
```
迁移前（单一CLAUDE.md）：
CLAUDE.md (3500字)
├── 全局编码规范
├── Git提交规范
├── API设计规范
├── 测试策略
└── 部署流程
迁移后（CLAUDE.md + Skills）：
CLAUDE.md (400字) ← 只保留全局规则
├── 项目概述
├── 技术栈声明
└── 通用编码风格
.claude/skills/
├── commit-linter/SKILL.md ← Git提交规范
├── api-designer/SKILL.md ← API设计规范
├── test-strategy/SKILL.md ← 测试策略
└── deploy-flow/SKILL.md ← 部署流程
每轮Token消耗：3500 → 400 + 激活Skill ≈ 1200（节省66%）
```
---
## 第六章：Skill触发率优化实战
### 6.1 触发率诊断
Skill的触发率（Activation Rate）是衡量description质量的核心指标。使用`/context`命令查看当前上下文中加载了哪些Skill：
```bash
# 在Claude Code中查看当前激活的上下文
> /context
# 输出示例：
# Context loaded:
# CLAUDE.md (412 tokens)
# Skills indexed: 12 (not loaded)
# Skills activated: api-security-scanner (1,847 tokens)
# Total: 2,259 tokens
```
### 6.2 提升触发率的技术
**技术一：description关键词嵌入**
在description中自然地嵌入用户可能使用的词汇：
```yaml
# 低触发率
description: "API安全审查工具"
# 高触发率
description: "REST API安全扫描器，检测OWASP Top 10漏洞包括SQL注入、XSS、CSRF。当用户需要安全审计、漏洞扫描、渗透测试建议时使用。"
```
**技术二：显式triggers字段**
```yaml
triggers:
- "扫描API安全" # 直接动作
- "安全审查接口" # 变体表述
- "OWASP检查" # 技术术语
- "这个API有漏洞吗" # 自然语言
```
**技术三：负面触发控制**
避免Skill在不相关场景被误触发：
```yaml
# 在SKILL.md正文中加入边界声明
# 不适用于以下场景：
# - 前端UI组件审查
# - 数据库Schema设计
# - 性能优化
# 如果用户请求以上任务，不要使用本Skill。
```
### 6.3 触发率量化测试
创建一个简单的触发率测试脚本：
```json
{
"skill": "api-security-scanner",
"version": "2.1.0",
"trigger_tests": [
{
"input": "帮我检查这个API有没有安全问题",
"should_activate": true
},
{
"input": "扫描/api/users接口的安全性",
"should_activate": true
},
{
"input": "这段代码有SQL注入吗",
"should_activate": true
},
{
"input": "帮我写一个React组件",
"should_activate": false
},
{
"input": "优化数据库查询性能",
"should_activate": false
}
]
}
```
运行这些测试用例，统计实际激活率与预期激活率的偏差，据此调整description和triggers。
---
## 第七章：完整实战——构建一个生产级Skill
### 7.1 场景：代码复杂度审查Skill
我们将构建一个`complexity-auditor` Skill，它能分析代码的圈复杂度（Cyclomatic Complexity），识别过度复杂的函数，并提供重构建议。
**第一步：创建目录结构**
```bash
mkdir -p .claude/skills/complexity-auditor/references
```
**第二步：编写SKILL.md**
```yaml
---
name: complexity-auditor
description: "代码复杂度审查专家。分析函数圈复杂度、认知复杂度、嵌套深度，识别过度复杂的代码并提供重构方案。支持JavaScript、TypeScript、Python、Java、Go。"
triggers:
- "代码复杂度"
- "函数太复杂"
- "圈复杂度"
- "代码质量审查"
- "重构建议"
metadata:
version: "1.0.0"
author: "code-quality-team"
tags: ["quality", "complexity", "refactoring"]
subagent:
model: "sonnet"
max_turns: 20
allowedTools:
- Read
- Grep
- Glob
- Bash
blockedTools:
- Edit
- Write
---
```
```markdown
# 代码复杂度审查专家
## 审查标准
### 圈复杂度阈值
| 复杂度 | 等级 | 建议 |
|--------|------|------|
| 1-5 | 简单 | 无需处理 |
| 6-10 | 中等 | 建议关注 |
| 11-20 | 复杂 | 建议重构 |
| 21-50 | 高危 | 必须重构 |
| >50 | 极端 | 立即拆分 |
### 认知复杂度阈值
| 复杂度 | 等级 |
|--------|------|
| 0-15 | 可接受 |
| 16-30 | 需关注 |
| >30 | 需重构 |
## 审查流程
1. **扫描阶段**：使用Glob和Grep定位目标文件中的所有函数/方法
2. **分析阶段**：对每个函数计算：
- 圈复杂度（if/elif/else/for/while/case/try-catch/and/or 的数量+1）
- 最大嵌套深度
- 函数行数
- 参数数量
3. **评级阶段**：根据阈值表给出评级
4. **建议阶段**：对复杂度>10的函数给出具体重构方案
## 输出格式
对每个被审查的函数，输出：
```
函数: `functionName` (文件路径:行号)
圈复杂度: X (等级)
认知复杂度: Y
嵌套深度: Z
函数行数: N
⚠️/✅ 评级说明
💡 重构建议（如适用）
```
最后输出汇总表：
```
📊 复杂度审查汇总
总函数数: X
简单: X (X%) 中等: X (X%) 复杂: X (X%) 高危: X (X%)
需要重构的函数:
1. functionName (复杂度: X) - 简要说明
```
## 重构策略参考
见 references/refactoring-patterns.md
```
**第三步：编写references**
```markdown
# 常用重构模式
## 降低圈复杂度
### 1. 提取函数（Extract Function）
将复杂的条件判断提取为独立的布尔函数：
```javascript
// 重构前（复杂度 8）
function getDiscount(user, order) {
if (user.isPremium && order.total > 100) {
if (user.yearsActive > 5) return 0.25;
else if (user.yearsActive > 2) return 0.15;
else return 0.10;
} else if (user.isRegular && order.total > 50) {
return 0.05;
}
return 0;
}
// 重构后（复杂度 3）
function getDiscount(user, order) {
if (isEligibleForPremiumDiscount(user, order)) {
return getPremiumDiscountRate(user);
}
if (isEligibleForRegularDiscount(user, order)) {
return 0.05;
}
return 0;
}
```
### 2. 以多态替代条件（Replace Conditional with Polymorphism）
### 3. 策略模式（Strategy Pattern）
### 4. 提前返回（Guard Clauses）
### 5. 查表法（Table-Driven Approach）
```
**第四步：编写eval.json**
```json
{
"skill": "complexity-auditor",
"version": "1.0.0",
"evals": [
{
"name": "detect-high-complexity-function",
"description": "检测高复杂度函数",
"input": "审查以下代码的复杂度",
"context": {
"files": {
"auth.ts": "function validateUser(user, req, config) {\n if (!user) return null;\n if (user.banned) {\n if (user.banExpiry > Date.now()) return null;\n else user.banned = false;\n }\n if (config.requireEmail && !user.email) return null;\n if (config.require2FA) {\n if (!user.twoFactorEnabled) return null;\n if (!req.headers['x-2fa-token']) return null;\n if (!verifyToken(req.headers['x-2fa-token'], user.secret)) return null;\n }\n if (config.ipWhitelist && config.ipWhitelist.length > 0) {\n const clientIp = req.headers['x-forwarded-for'] || req.connection.remoteAddress;\n if (!config.ipWhitelist.includes(clientIp)) return null;\n }\n return user;\n}"
}
},
"assertions": [
{"type": "contains", "value": "validateUser", "required": true},
{"type": "contains_any", "value": ["复杂", "高危", "重构"], "required": true},
{"type": "contains_any", "value": ["提取函数", "提前返回", "guard", "重构"], "required": true},
{"type": "contains_any", "value": ["📊", "汇总"], "required": true}
]
},
{
"name": "simple-function-passes",
"description": "简单函数应获得好评级",
"input": "分析这个函数的复杂度",
"context": {
"files": {
"utils.ts": "function add(a: number, b: number): number {\n return a + b;\n}"
}
},
"assertions": [
{"type": "contains_any", "value": ["简单", "✅", "无需处理"], "required": true},
{"type": "not_contains", "value": "高危", "required": true}
]
},
{
"name": "summary-report-format",
"description": "应生成格式正确的汇总报告",
"input": "审查src/目录下所有TypeScript文件的代码复杂度",
"assertions": [
{"type": "contains", "value": "📊", "required": true},
{"type": "contains", "value": "总函数数", "required": true}
]
}
]
}
```
**第五步：安装、测试、迭代**
```bash
# 1. 确认Skill已就位
ls -la .claude/skills/complexity-auditor/
# 2. 在Claude Code中测试触发
> 这个函数太复杂了，帮我分析一下
# 3. 使用skill-creator运行评估
> 请用skill-creator评估 .claude/skills/complexity-auditor/ 的质量
# 4. 根据评估结果迭代改进
# - 调整SKILL.md中的审查流程描述
# - 增加eval.json中的边界测试用例
# - 优化description提升触发率
# 5. 验证最终效果
> /context
# 确认Skill被正确加载和激活
```
---
## 第八章：高级模式——Skill组合与多Skill编排
### 8.1 Skill引用链
通过在SKILL.md的正文中引用其他Skill，可以构建Skill组合：
```yaml
# .claude/skills/full-review/SKILL.md
---
name: full-code-review
description: "完整代码审查流程，自动串联安全扫描、复杂度审查和风格检查"
---
# 完整代码审查流程
按以下顺序执行多Skill审查：
1. 首先调用 `api-security-scanner` Skill 进行安全审查
2. 然后调用 `complexity-auditor` Skill 进行复杂度审查
3. 最后调用 `style-checker` Skill 进行代码风格审查
4. 汇总三个Skill的结果，生成综合审查报告
```
### 8.2 Hub-and-Spoke架构
对于大型项目，推荐Hub-and-Spoke模式：
```mermaid
graph TD
Hub["Hub Skill
full-code-review"]
S1["Spoke: security-scanner"]
S2["Spoke: complexity-auditor"]
S3["Spoke: style-checker"]
S4["Spoke: test-coverage"]
Hub --> S1
Hub --> S2
Hub --> S3
Hub --> S4
S1 --> R1["references/
owasp-top10.md"]
S2 --> R2["references/
refactoring.md"]
S3 --> R3["references/
style-rules.md"]
S4 --> R4["references/
coverage-matrix.md"]
style Hub fill:#ff6b6b,color:#fff
style S1 fill:#4a90d9,color:#fff
style S2 fill:#4a90d9,color:#fff
style S3 fill:#4a90d9,color:#fff
style S4 fill:#4a90d9,color:#fff
```
Hub Skill作为编排器，不包含具体审查逻辑，只负责调用各个Spoke Skill并汇总结果。这种架构的优势：
- 每个Spoke Skill可以独立评估和迭代
- Token消耗可控（Hub只加载，Spoke按需触发）
- 新增审查维度只需添加新的Spoke Skill
### 8.3 Skill与Subagent的配合
```yaml
# 在Hub Skill中使用subagent配置控制执行策略
subagent:
model: "sonnet"
max_turns: 30
allowedTools:
- Read
- Grep
- Glob
- Bash
- Task # 允许创建子Agent，实现并行审查
```
通过允许Task工具，Hub Skill可以并行启动多个子Agent分别执行不同的审查任务，大幅缩短总审查时间。
---
## 第九章：Skill发布与分发
### 9.1 发布到Anthropic官方仓库
Anthropic维护了[anthropics/skills](https://github.com/anthropics/skills)公共仓库，接受社区贡献：
```bash
# 1. Fork仓库
# 2. 将Skill目录复制到skills/目录下
# 3. 确保包含eval.json（通过所有测试）
# 4. 提交PR
# Skill目录要求：
skills/
└── your-skill-name/
├── SKILL.md # 必填
├── eval.json # 推荐（通过评估才容易被接受）
└── references/ # 可选
```
### 9.2 使用npm包分发
```bash
# 使用openskills工具打包和安装
npx openskills install @scope/skill-name
# 或直接从GitHub安装
npx openskills install github:user/repo
```
### 9.3 团队内部分发
将Skill放在团队共享的Git仓库中，团队成员通过克隆到`~/.claude/skills/`来使用：
```bash
# 团队Skill仓库
git clone https://github.com/your-org/claude-skills.git ~/.claude/skills/
# 或使用符号链接
ln -s /path/to/shared-skills/* ~/.claude/skills/
```
---
## 第十章：常见问题与排查
### Q1：Skill没有被触发
**排查步骤**：
1. 检查Skill目录是否在正确位置：`.claude/skills/`或`~/.claude/skills/`
2. 运行`/context`确认Skill是否出现在索引中
3. 检查description是否包含用户消息中的关键词
4. 尝试使用`/skill-name`手动调用
### Q2：Skill触发但不按预期执行
**排查步骤**：
1. 检查SKILL.md正文是否足够具体，避免模糊指令
2. 增加具体的示例到references中
3. 使用eval.json进行结构化评估
4. 考虑将复杂步骤拆分为子步骤
### Q3：Token消耗过高
**排查步骤**：
1. 检查references目录是否包含不必要的文件
2. 精简SKILL.md正文，移除冗余说明
3. 考虑使用Hub-and-Spoke架构拆分大Skill
4. 使用`/compact`命令压缩对话历史
### Q4：评估结果不稳定
**排查步骤**：
1. 增加断言的容错范围（使用`contains_any`替代`contains`）
2. 避免对输出格式做过于严格的断言
3. 使用`semantic_match`替代精确匹配
4. 多次运行评估取平均通过率
---
## 延伸阅读
- [Anthropic官方Skill文档](https://code.claude.com/docs/en/skills) — Anthropic官方Skill系统完整文档
- [SKILL.md格式规范](https://deepwiki.com/anthropics/skills/2.2-skill.md-format-specification) — YAML frontmatter所有字段详解
- [Skill品质最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic官方Skill编写最佳实践指南
- [Equipping Agents for the Real World](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic工程博客，Skill系统设计哲学
- [skill-creator评估指南](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills) — eval.json与基准测试使用教程
---
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| 适合训练营类型 | 中高级开发者训练营、AI工程化训练营 |
| 预计教学时长 | 4-5小时（含实操） |
| 前置要求 | Claude Code基础使用经验、至少创建过一个Skill |
| 实操环节占比 | 60%（第四至七章为纯实操） |
| 学员产出 | 每人完成一个带eval.json的生产级Skill |
| 建议分组 | 2-3人小组，每组负责不同类型的Skill |
| 硬件要求 | 无特殊要求，需网络连接 |
---
## 参考来源
1. [Claude Code Skills Architecture: 4 Layers That Keep Your AI Agent Fast](https://www.mindstudio.ai/blog/claude-code-skills-architecture-progressive-context-loading) — 渐进式上下文加载四层架构详解
2. [Improving skill-creator: Test, measure, and refine Agent Skills](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills) — Anthropic官方Skill评估体系发布说明
3. [SKILL.md Format Specification](https://deepwiki.com/anthropics/skills/2.2-skill.md-format-specification) — SKILL.md格式规范完整参考
4. [Claude Code Skills 2.0: Evals, Benchmarks and A/B Testing](https://pasqualepillitteri.it/en/news/341/claude-code-skills-2-0-evals-benchmarks-guide) — Skills 2.0评估与基准测试指南
5. [Claude Code Skills vs MCP Servers: When to Use Each](https://skillsplayground.com/guides/claude-code-skills-vs-mcp/) — Skill与MCP架构对比与选择指南
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
