Claude Code Skill逆向工程：从拆解改造到多Skill编排实战

.claude/skills/my-skill/
├── SKILL.md              # 核心指令文件（必需）
├── references/           # 参考文档目录（可选）
│   ├── api-docs.md       # API参考
│   └── examples.md       # 示例代码
├── templates/            # 模板文件（可选）
│   └── component.tsx     # 代码模板
└── tests/                # 测试用例（可选）
    └── test-cases.md     # 验证场景

---
# 第一层：元数据层（YAML Frontmatter）
# 决定"何时触发"和"用什么资源"
name: my-skill
description: >
  精确描述此Skill做什么。这段文字是模型判断
  是否激活此Skill的关键依据。
triggers:
  - "关键词或短语"
  - "另一组触发条件"
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
dependencies:
  - another-skill
model: sonnet
effort: high
---

# 第二层：指令层（Markdown Body）
# 决定"怎么执行"
# 这里是具体的执行指令、流程步骤、输出格式规范

# 列出项目级Skill
ls -la .claude/skills/

# 列出用户级Skill
ls -la ~/.claude/skills/

# 递归查看Skill目录结构
find ~/.claude/skills/ -type f -name "SKILL.md"

---
name: code-review
description: >
  Perform a comprehensive code review on changes. Use when the user
  asks to review code, check PR changes, or when completing tasks
  before requesting code review. Analyzes code quality, security
  vulnerabilities, performance issues, and adherence to project
  conventions.
tools:
  - Read
  - Glob
  - Grep
  - Bash
effort: high
model: sonnet
---

# 指令Body的典型结构（通用模板）

## 上下文
说明此Skill在什么场景下被激活，以及用户期望什么

## 执行流程
分步骤描述执行逻辑，每步有明确的输入/输出

## 输出格式
定义最终输出的格式规范（JSON、Markdown表格、代码等）

## 约束条件
列出不能做的事情、边界情况处理

## 示例（可选）
给出1-2个完整的输入→输出样例

flowchart TD
    A[Skill被激活] --> B{变更类型?}
    B -->|新功能| C[检查架构合理性]
    B -->|Bug修复| D[验证修复完整性]
    B -->|重构| E[评估行为等价性]
    C --> F[安全扫描]
    D --> F
    E --> F
    F --> G[生成Review报告]
    G --> H[输出格式化结果]

用户消息: "帮我审查一下最近的代码变更"
    ↓
模型解析意图: code review → 匹配description中的"review code"
    ↓
激活Skill → 读取完整Body → 执行指令

# 测试自动触发的不同表述
claude -p "check the recent changes for issues"
claude -p "review my code"
claude -p "find bugs in my latest commit"
claude -p "审计代码质量"   # 中文表述

flowchart LR
    A[发现目标Skill] --> B[复制到本地]
    B --> C[分析触发词]
    C --> D[修改description]
    D --> E[调整指令Body]
    E --> F[添加references]
    F --> G[测试触发率]
    G -->|触发率低| D
    G -->|触发率高| H[部署到团队]

mkdir -p .claude/skills/ts-react-review
cp -r ~/.claude/skills/code-review/* .claude/skills/ts-react-review/

---
name: ts-react-review
description: >
  TypeScript + React项目专用代码审查。当用户要求审查React组件、
  检查TypeScript类型安全、验证Hook使用规范、或审查Next.js路由时
  自动激活。覆盖：组件设计模式、性能优化(useMemo/useCallback)、
  类型安全(strict mode)、可访问性(aria属性)、测试覆盖率。
tools:
  - Read
  - Glob
  - Grep
  - Bash
effort: high
model: sonnet
---

mkdir -p .claude/skills/ts-react-review/references

# 项目约定

## 组件命名
- PascalCase for components
- camelCase for utilities
- kebab-case for file names

## Hook规则
- 自定义Hook必须以 use 开头
- useEffect依赖数组必须显式声明
- 禁止在条件语句中调用Hook

## 类型规范
- 禁止使用 any，使用 unknown + 类型守卫
- Props必须定义interface，不用type
- 泛型参数命名 T开头 (TData, TError)

## 审查流程

1. **定位变更文件**
   使用 Bash 运行 `git diff --name-only` 获取变更列表

2. **分类审查**
   - `.tsx` 文件 → 执行React组件审查
   - `.ts` 文件 → 执行TypeScript类型审查
   - `.test.*` 文件 → 执行测试质量审查

3. **React组件审查清单**
   - 组件是否拆分合理（<200行）
   - 状态管理是否使用正确Hook
   - 是否存在不必要的re-render
   - JSX可读性和可访问性

4. **TypeScript审查清单**
   - 类型覆盖率（无 any/unknown）
   - 泛型使用是否合理
   - 类型导出是否完整

5. **输出格式**
   按严重级别分类输出：
   - 🔴 Critical: 类型安全漏洞、安全漏洞
   - 🟡 Warning: 性能隐患、不良模式
   - 🟢 Suggestion: 改善建议、最佳实践

# 测试1：显式触发
claude -p "/ts-react-review"

# 测试2：隐式触发（不同表述）
claude -p "review my React components"
claude -p "检查TypeScript类型是否安全"
claude -p "这个组件有没有性能问题"

# 测试3：边界情况
claude -p "review this Python file"  # 不应触发

flowchart TB
    subgraph 链式编排
        A1[Skill A] --> A2[Skill B] --> A3[Skill C]
    end

    subgraph 并行编排
        B1[Skill A] --> B3[汇总]
        B2[Skill B] --> B3
    end

    subgraph 条件编排
        C1[Skill A] --> C2{条件判断}
        C2 -->|满足| C3[Skill B]
        C2 -->|不满足| C4[Skill C]
    end

---
name: release-pipeline
description: >
  执行完整的发布流水线：代码审查 → 测试 → 变更日志 → 版本发布。
  当用户说"发布新版本"、"准备release"、"执行发布流程"时激活。
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
dependencies:
  - code-review
effort: high
---

## 发布流水线

按顺序执行以下步骤，每步必须通过才继续：

### Step 1: 代码审查
运行 /code-review 审查所有未提交变更。
如果发现 Critical 级别问题，暂停并报告，不继续。

### Step 2: 测试验证
运行项目测试套件：
- 单元测试: npm test
- 类型检查: npm run typecheck
- Lint: npm run lint
任何测试失败都暂停流水线。

### Step 3: 生成变更日志
分析 git log --oneline 自上次tag以来的所有commit：
- 按feat/fix/breaking分类
- 生成 CHANGELOG.md 新条目

### Step 4: 版本号更新
根据变更类型决定版本号：
- breaking → major
- feat → minor
- fix → patch
更新 package.json 中的版本号。

### Step 5: Git标签
创建版本标签并推送。

### 输出
发布总结报告，包含版本号、变更列表、测试结果。

---
name: health-check
description: >
  项目全方位健康检查。同时执行代码质量、依赖安全、测试覆盖率、
  文档完整性四个维度的检查。当用户说"项目健康检查"、"全面审查
  项目"、"检查项目质量"时激活。
tools:
  - Read
  - Bash
  - Glob
  - Grep
effort: high
---

## 项目健康检查

同时启动四个维度的检查：

### 维度1: 代码质量
- 统计代码行数和文件数
- 检查是否存在超大文件(>500行)
- 分析圈复杂度热点

### 维度2: 依赖安全
- 运行 npm audit
- 检查过时的依赖 (npm outdated)
- 识别未使用的依赖

### 维度3: 测试覆盖率
- 运行 npm test -- --coverage
- 分析覆盖率趋势
- 识别未测试的关键模块

### 维度4: 文档完整性
- 检查 README.md 是否存在
- API文档覆盖率
- CHANGELOG维护状态

### 输出格式

| 维度 | 状态 | 评分 | 关键发现 |
|------|------|------|----------|
| 代码质量 | ✅/⚠️/❌ | A-F | ... |
| 依赖安全 | ✅/⚠️/❌ | A-F | ... |
| 测试覆盖 | ✅/⚠️/❌ | A-F | ... |
| 文档完整 | ✅/⚠️/❌ | A-F | ... |

最终给出综合健康评分和改善优先级列表。

---
name: auto-fixer
description: >
  智能问题诊断与自动修复。分析错误类型后自动选择合适的修复策略。
  当用户报告bug、测试失败、或构建错误时激活。
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
dependencies:
  - code-review
effort: high
---

## 智能修复流程

### Step 1: 错误分类

分析用户提供的错误信息或测试输出，判断类型：

- **Type Error** → 执行TypeScript修复流程
- **Import Error** → 执行模块解析修复
- **Runtime Error** → 执行逻辑调试
- **Test Failure** → 执行测试驱动修复
- **Build Error** → 执行构建配置修复

### Step 2: 定位根因

根据错误类型使用不同策略：
- Type Error: 读取相关 .ts/.tsx 文件，追踪类型链
- Import Error: 检查 tsconfig paths、package.json exports
- Runtime Error: 添加调试日志，分析调用栈
- Test Failure: 读取测试文件，理解期望行为
- Build Error: 检查构建配置、环境变量

### Step 3: 实施修复

应用修复后必须：
1. 重新运行失败的测试/构建
2. 确认修复未引入新问题
3. 如果修复失败，回退变更并尝试方案B

### 输出
修复报告，包含：错误类型、根因分析、修复方案、验证结果。

flowchart TD
    subgraph 触发层
        T1[/review-full 斜杠命令]
        T2["自然语言触发"]
    end

    subgraph 编排层
        ORCH[review-orchestrator<br/>主编排Skill]
    end

    subgraph 执行层
        S1[ts-react-review<br/>TypeScript审查]
        S2[security-scan<br/>安全扫描]
        S3[perf-audit<br/>性能审计]
    end

    subgraph 汇总层
        AGG[review-report<br/>报告生成]
    end

    T1 --> ORCH
    T2 --> ORCH
    ORCH --> S1
    ORCH --> S2
    ORCH --> S3
    S1 --> AGG
    S2 --> AGG
    S3 --> AGG
    AGG --> OUT[结构化Review报告]

mkdir -p .claude/skills/review-orchestrator

---
name: review-orchestrator
description: >
  全方位代码审查编排器。协调TypeScript审查、安全扫描和性能审计
  三个专业Skill，生成综合审查报告。当用户说"全面审查"、"完整
  review"、"代码评审"时激活。也可通过 /review-full 显式调用。
tools:
  - Read
  - Bash
  - Glob
  - Grep
dependencies:
  - ts-react-review
  - security-scan
  - perf-audit
effort: high
---

## 全方位代码审查编排

### 阶段1: 变更收集

运行以下命令获取待审查的代码变更：

```bash
git diff --name-only HEAD~1

# 代码审查报告

## 概要
- 审查文件数: X
- Critical: X 🔴
- Warning: X 🟡
- Suggestion: X 🟢

## TypeScript审查结果
[ts-react-review的输出]

## 安全扫描结果
[security-scan的输出]

## 性能审计结果
[perf-audit的输出]

## 修复优先级
1. [最关键的修复建议]
2. [次关键的修复建议]
3. ...

### 5.3 创建安全扫描子Skill

```bash
mkdir -p .claude/skills/security-scan

---
name: security-scan
description: >
  代码安全扫描。检查OWASP Top 10漏洞、敏感信息泄露、
  不安全的依赖版本。当用户提到安全审计、漏洞扫描、
  security review时自动激活。
tools:
  - Read
  - Bash
  - Grep
effort: high
---

## 安全扫描流程

### 检查项

1. **敏感信息泄露**
   搜索以下模式：
   - API keys (grep -r "api_key\|apiKey\|API_KEY")
   - 密码硬编码 (grep -r "password\|passwd" --include="*.ts")
   - JWT secrets
   - .env文件是否被git追踪

2. **注入漏洞**
   - SQL注入: 检查原始SQL查询
   - XSS: 检查 dangerouslySetInnerHTML
   - 命令注入: 检查 child_process 使用

3. **依赖安全**
   运行 npm audit --json，分析结果

4. **认证/授权**
   - 检查路由是否有权限守卫
   - Token存储方式是否安全
   - CORS配置是否合理

### 输出格式
按严重级别分类，每项包含：
- 🔴/🟡/🟢 严重级别
- 文件路径:行号
- 问题描述
- 修复建议（含代码示例）

mkdir -p .claude/skills/perf-audit

---
name: perf-audit
description: >
  前端性能审计。分析React组件渲染性能、Bundle大小、
  网络请求优化、图片资源优化。当用户提到性能优化、
  页面加载慢、性能审查时激活。
tools:
  - Read
  - Bash
  - Glob
  - Grep
effort: medium
---

## 性能审计流程

1. **Bundle分析**
   检查 package.json 依赖大小：
   ```bash
   npx bundlephobia-client
   ```

2. **React渲染优化**
   - 搜索缺少 key 的列表渲染
   - 检查是否滥用 useState 导致不必要渲染
   - 查找缺少 React.memo 的纯展示组件
   - 检查 useEffect 缺少依赖数组

3. **资源优化**
   - 图片是否使用现代格式(WebP/AVIF)
   - 是否有懒加载 (lazy loading)
   - CSS是否按需引入

4. **网络优化**
   - API调用是否有去重/缓存
   - 是否使用 SWR/React Query
   - 是否有不必要的瀑布请求

### 输出
每个发现附带性能影响评估(高/中/低)和具体优化方案。

# 验证目录结构
find .claude/skills/ -name "SKILL.md" | sort

.claude/skills/review-orchestrator/SKILL.md
.claude/skills/ts-react-review/SKILL.md
.claude/skills/security-scan/SKILL.md
.claude/skills/perf-audit/SKILL.md

# 测试编排器显式触发
claude -p "/review-orchestrator"

# 测试自然语言触发
claude -p "请全面审查一下最近的代码变更"

# 测试子Skill独立触发
claude -p "检查代码里有没有安全漏洞"
claude -p "分析一下前端性能问题"

## 动态路由

首先判断项目类型：

1. 如果存在 `package.json` 且包含 "next" → 这是Next.js项目
   → 调用 nextjs-specific 审查规则
   → 检查 App Router vs Pages Router

2. 如果存在 `Cargo.toml` → 这是Rust项目
   → 调用 rust-specific 审查规则
   → 检查 unsafe 代码块

3. 如果存在 `go.mod` → 这是Go项目
   → 调用 go-specific 审查规则
   → 检查 goroutine 泄漏

.claude/
├── skills/
│   ├── review-orchestrator/
│   │   └── SKILL.md
│   ├── ts-react-review/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── ts-conventions.md
│   └── security-scan/
│       ├── SKILL.md
│       └── references/
│           └── owasp-checklist.md
└── rules/
    └── project-standards.md   ← 全局规则文件

# 项目规则

所有Skill执行时参考:
- @rules/project-standards.md
- 编码规范遵循 Airbnb Style Guide
- 提交信息遵循 Conventional Commits

## 错误处理策略

### 子Skill失败时的降级方案

1. 如果 ts-react-review 执行失败（如文件格式不支持）
   → 降级为通用代码审查，不丢失功能

2. 如果 security-scan 的 npm audit 超时
   → 跳过依赖检查，仅报告代码层面的安全问题
   → 在报告中标注"[依赖安全检查已跳过]"

3. 如果 perf-audit 无法分析bundle大小
   → 仅报告代码层面的性能建议
   → 标注"[Bundle分析不可用]"

### 硬性约束
- 所有Critical级别的发现必须报告，即使其他检查被跳过
- 最终报告必须明确标注哪些检查被跳过及原因

# 错误写法 — 太抽象
description: "Code review for TypeScript projects"

# 正确写法 — 覆盖多种表述
description: >
  TypeScript React项目代码审查。当用户要求审查代码、
  review PR、检查TypeScript类型、审查React组件、
  code review、代码评审时激活。覆盖类型安全、Hook
  规范、组件设计、性能优化、安全漏洞检查。

## 执行步骤

1. 首先执行 /ts-react-review 审查代码质量
2. 然后执行 /security-scan 检查安全漏洞
3. 最后执行 /perf-audit 审计性能
4. 汇总三个结果生成报告

## 输出格式（必须严格遵守）

```json
{
  "skill_name": "ts-react-review",
  "findings": [
    {
      "severity": "critical|warning|info",
      "file": "path/to/file",
      "line": 42,
      "message": "问题描述",
      "suggestion": "修复建议"
    }
  ],
  "summary": "总体评价"
}

### Q4: Skill执行时上下文溢出

**原因**：references目录中放了大量文件，全部加载超出上下文窗口。

**解决方案**：

1. 将references文件控制在500行以内
2. 使用分层references：`references/essential.md`（核心）+ `references/extended.md`（扩展）
3. 在Body中明确指示"仅在需要时读取extended.md"

---

## Skill编排工作流总结

```mermaid
flowchart TB
    START[开始] --> DISCOVER[发现/搜索Skill]
    DISCOVER --> ANALYZE[逆向分析Skill结构]
    ANALYZE --> DECIDE{是否满足需求?}
    DECIDE -->|是| INTEGRATE[直接集成使用]
    DECIDE -->|部分满足| FORK[Fork并改造]
    DECIDE -->|不满足| CREATE[从零创建]
    FORK --> TEST1[测试触发与输出]
    CREATE --> TEST1
    INTEGRATE --> TEST1
    TEST1 --> MULTIPLE{需要多Skill协作?}
    MULTIPLE -->|是| ORCHESTRATE[设计编排模式]
    MULTIPLE -->|否| DEPLOY[部署使用]
    ORCHESTRATE --> TEST2[端到端测试]
    TEST2 --> DEPLOY
    DEPLOY --> ITERATE[持续迭代优化]
    ITERATE --> DISCOVER