Claude Code Skill架构深度剖析：从渐进式加载到自动化评估

传统模式（CLAUDE.md全量加载）：
┌─────────────────────────────────────┐
│  用户消息 + CLAUDE.md(5000 tokens)   │
│  + 对话历史 + Skill全量文本          │  → 每轮都消耗完整Token
│  → 200K上下文窗口很快被填满          │
└─────────────────────────────────────┘

Skill渐进式加载：
┌──────────┐    ┌──────────┐    ┌──────────────┐
│ 名称索引  │ →  │ 描述匹配  │ →  │ 按需加载正文  │
│ ~100 tkn │    │ ~50 tkn  │    │ 完整内容      │
└──────────┘    └──────────┘    └──────────────┘
第一阶段         第二阶段          第三阶段

---
name: api-doc-writer
description: "根据OpenAPI规范自动生成API文档，支持REST和GraphQL端点描述"
---

用户说："帮我写API文档"
         ↓
Claude扫描索引：
  api-doc-writer: "根据OpenAPI规范自动生成API文档..."  ← 匹配度 0.92
  db-migrator: "数据库迁移工具..."                      ← 匹配度 0.31
  test-gen: "测试生成工具..."                            ← 匹配度 0.15
         ↓
选中 api-doc-writer，进入第三阶段

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

---
name: release-workflow
description: "标准化发版流程：代码审查→测试→版本号更新→Changelog→打Tag→推送"
---

---
name: accessibility-auditor
description: "WCAG 2.2 AA级无障碍审查专家，支持React/Vue/Angular组件的自动化无障碍检测与修复建议"
---

问自己：这个Skill是在告诉Claude"怎么做"还是"做什么"？

"怎么做"（How） → 工作流型
  示例：部署流程、发版检查清单、PR审查清单

"做什么"（What） → 能力增强型
  示例：安全审计、代码风格审查、特定框架最佳实践

---
name: my-skill              # 必填，唯一标识符
description: "简洁描述"       # 必填，决定触发匹配质量
---

# 好的description
description: "PostgreSQL数据库迁移规划器。当用户需要修改数据库Schema、添加列、创建索引或进行数据迁移时使用。支持生成可逆迁移脚本。"

# 坏的description
description: "数据库工具"

---
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
---

# 精准触发（推荐）
triggers:
  - "扫描API安全"
  - "安全审查API"
  - "OWASP检查"

# 过度触发（不推荐）
triggers:
  - "安全"
  - "API"
  - "检查"
  - "扫描"
  - "漏洞"
  - "测试"
  # 这些词太宽泛，会导致误触发

# 严格只读模式——适合审查类Skill
subagent:
  allowedTools:
    - Read
    - Grep
    - Glob
    - Bash
  blockedTools:
    - Edit
    - Write

# 受限写入模式——适合代码生成类Skill
subagent:
  allowedTools:
    - Read
    - Grep
    - Glob
    - Bash
    - Edit
  blockedTools:
    - Write       # 不允许创建新文件

graph LR
    subgraph "Skills 2.0 评估体系"
        A["eval.json<br/>测试用例定义"]
        B["Benchmark<br/>基准测试运行器"]
        C["A/B Testing<br/>版本对比"]
    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

{
  "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
        }
      ]
    }
  ]
}

# .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. **格式要求**：`<type>(<scope>): <subject>`
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. 输出结构化的检查报告

## 输出格式

{
  "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}
      ]
    }
  ]
}

# 在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评估报告：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"

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["等待模型更新<br/>或新test case"]
    J --> A

.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

# 查看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%）

# 在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

# 低触发率
description: "API安全审查工具"

# 高触发率
description: "REST API安全扫描器，检测OWASP Top 10漏洞包括SQL注入、XSS、CSRF。当用户需要安全审计、漏洞扫描、渗透测试建议时使用。"

triggers:
  - "扫描API安全"        # 直接动作
  - "安全审查接口"        # 变体表述
  - "OWASP检查"          # 技术术语
  - "这个API有漏洞吗"     # 自然语言

# 在SKILL.md正文中加入边界声明
# 不适用于以下场景：
# - 前端UI组件审查
# - 数据库Schema设计
# - 性能优化
# 如果用户请求以上任务，不要使用本Skill。

{
  "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
    }
  ]
}

mkdir -p .claude/skills/complexity-auditor/references

---
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
---

# 代码复杂度审查专家

## 审查标准

### 圈复杂度阈值
| 复杂度 | 等级 | 建议 |
|--------|------|------|
| 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的函数给出具体重构方案

## 输出格式

对每个被审查的函数，输出：

最后输出汇总表：

## 重构策略参考

见 references/refactoring-patterns.md

<!-- references/refactoring-patterns.md -->
# 常用重构模式

## 降低圈复杂度

### 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;
}

**第四步：编写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}
      ]
    }
  ]
}

# 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被正确加载和激活

# .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的结果，生成综合审查报告

graph TD
    Hub["Hub Skill<br/>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/<br/>owasp-top10.md"]
    S2 --> R2["references/<br/>refactoring.md"]
    S3 --> R3["references/<br/>style-rules.md"]
    S4 --> R4["references/<br/>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中使用subagent配置控制执行策略
subagent:
  model: "sonnet"
  max_turns: 30
  allowedTools:
    - Read
    - Grep
    - Glob
    - Bash
    - Task        # 允许创建子Agent，实现并行审查

# 1. Fork仓库
# 2. 将Skill目录复制到skills/目录下
# 3. 确保包含eval.json（通过所有测试）
# 4. 提交PR

# Skill目录要求：
skills/
└── your-skill-name/
    ├── SKILL.md          # 必填
    ├── eval.json         # 推荐（通过评估才容易被接受）
    └── references/       # 可选

# 使用openskills工具打包和安装
npx openskills install @scope/skill-name

# 或直接从GitHub安装
npx openskills install github:user/repo

# 团队Skill仓库
git clone https://github.com/your-org/claude-skills.git ~/.claude/skills/

# 或使用符号链接
ln -s /path/to/shared-skills/* ~/.claude/skills/