02 - Skills 技能体系设计

1. 定位

Skills 是斜杠命令的现代替代品，用于固化重复性任务的最佳实践。

与 Prompt 的区别：Prompt 每次都要手写，Skill 写一次反复用。Prompt 技巧详见 15-Prompt 工程实战。与 Hooks 的区别：Hooks 是自动触发的确定性动作，Skill 是人主动调用的智能流程。

官方内置技能：Claude Code 自带 3 个捆绑技能 + 1 个内置命令，无需配置即可使用：

内置技能	用途
`/simplify`	并行启动 3 个代理审查代码复用、质量、效率，直接改代码
`/batch`	将大规模变更分解为 5-30 个独立单元，在独立 git worktree 中并行执行
`/debug`	读取会话调试日志排查问题
`/security-review`	扫描当前分支 git diff 的安全漏洞（注入、认证、数据泄露）

本文档的 Skills 体系为自定义技能，与内置技能互补。自定义技能放在 .claude/skills/ 目录下，按项目需求定制。

三阶段代码质量管线

内置技能与自定义 /review 构成分层质量管线，各司其职、零重叠：

Stage 1: /simplify     → 自动改代码（去冗余、提复用、优效率）
Stage 2: /review        → 出审查报告（正确性、性能、规格验收）
Stage 3: /security-review → 深度安全扫描（注入、认证、泄露）

阶段	工具	来源	动作	何时用
精简重构	`/simplify`	捆绑	改代码	功能写完后
质量审计	`/review`	自定义	出报告	提交前
安全扫描	`/security-review`	内置	出报告	涉及安全敏感变更时

`/simplify` 安全使用指南

/simplify 会直接修改代码（3 个并行子代理同时工作），使用不当有风险：

安全用法：在 commit 之后、下一步开发之前使用。有 commit 兜底，不满意 git checkout . 一键回退。

不安全用法：在大量未提交修改上运行——改坏后与你的修改混在一起难以分离。

✅ 安全的时序：
  编码 → commit → /simplify → 检查 diff → 满意则 commit / 不满意则 checkout .

❌ 危险的时序：
  编码（大量未提交修改）→ /simplify → 改坏了 → 无法分离你的修改和 AI 的修改

如需更安全的行为，可在项目级创建 .claude/skills/simplify/SKILL.md 覆盖捆绑版本（项目级优先于捆绑级），例如限制 allowed-tools 去掉 Edit/Write 变为纯报告模式。

2. 渐进式披露机制

Claude Code 在会话启动时只加载 Skill 的元数据（name + description，约 100 token），用户调用时才拉取完整指令（< 5K token）。

上下文预算：所有技能描述合计占上下文窗口的 2%，回退上限 16,000 字符。20 个技能可能在提问前就添加 1000+ tokens。用 /context 命令可检查是否有技能因超出预算被排除。

这意味着：

注册 10 个 Skills 只增加约 1000 token 的启动开销
完整指令只在需要时加载，不浪费上下文
description 必须写清做什么和何时使用，因为这是路由决策的依据
删除未使用的技能以节省上下文空间，避免无谓开销

3. SKILL.md 标准格式

每个 Skill 位于 .claude/skills/[skill-name]/SKILL.md：

markdown

---
name: skill-name
description: >
  一句话说明做什么。何时使用此技能的触发条件描述。
---

# Skill 标题

具体执行指令...

Frontmatter 参考表：

字段	类型	必填	说明
`name`	string	是	小写加连字符，最大 64 字符
`description`	string	是	最大 1024 字符，必须包含做什么 + 何时用（路由决策依据）
`allowed-tools`	string[]	—	限制可用工具列表，如 `Read, Grep, Glob, Bash`
`model`	string	—	指定运行模型
`context`	string	—	`fork` 在独立子代理中运行，不污染主会话（见 §7.3）
`agent`	string	—	指定子代理类型（如 `Explore` 只读），需配合 `allowed-tools`
`argument-hint`	string	—	`/skill-name` 后显示的参数提示（如 `<branch-name>`）
`disable-model-invocation`	bool	—	`true` 时禁止模型自动触发，仅允许用户 `/skill-name` 手动调用
`user-invocable`	bool	—	`false` 时用户无法 `/` 调用，仅作背景知识被 AI 自动参考。默认 `true`
`hooks`	object	—	Skill 专属 Hook 声明，参见 doc-04 §9.4

4. 核心 Skills 清单

精选 8 个高频 Skills，覆盖日常开发 90% 场景：

4.1 code-standards — 编码规范守卫

markdown

---
name: code-standards
description: >
  编码规范守卫。任何代码生成请求时自动参考。
  确保生成的代码符合项目约定的类型安全、错误处理和命名规范。
---

# 编码规范

生成代码前强制检查以下规则：

## TypeScript
- 所有函数必须有完整类型注解，禁止 any
- 使用 named export，禁止 default export

## API Route
- 所有输入用 zod schema 校验
- 统一响应格式：`{ data, error, meta }`
- 错误使用 AppError 类

## React 组件
- 函数式组件 + hooks，Props 定义为独立 type
- 状态管理优先级：useState → useReducer → Zustand → Server State

## 文件结构
- 单文件不超过 300 行，命名 kebab-case，组件 PascalCase
- 新增代码优先参考项目中已有的同类实现

4.2 tech-research — 技术调研

编码前的结构化调研，评估开源项目、调研行业标准、分析竞品方案、收集最佳实践。五步流程：界定调研范围 → 执行调研（Web Search）→ 综合整理 → 输出建议 → 等待确认。

调研覆盖 5 个维度（按需选取 2-3 个）：标准与规范、开源生态（Tier 1 深度 + Tier 2 概览）、最佳实践、竞品分析、性能与规模参考。

产物：docs/research/{topic-slug}.md，包含 TL;DR、分层开源项目评估、推荐路径、备选方案、开放问题。

使用 context: fork 隔离执行，避免大量 web search 占用主会话上下文。

下游衔接：tech-research → /spec → /plan。

完整提示词见 .claude/skills/tech-research/SKILL.md

4.4 spec — 需求分析与产品定义

将模糊想法转化为结构化产品规格文档。核心流程：苏格拉底提问（5 Whys + 6 维度探查）→ 清晰度评分（≥ 90 分）→ 策略探索（2-3 方案对比）→ 用户故事（Given/When/Then）→ 特性分解 → 多视角审查 → 生成 spec.md。

产物：docs/spec.md（或 docs/[feature]-spec.md），包含背景、目标、用户画像、策略选择、验收标准、数据模型、API 概要等。

下游衔接：spec.md → /product-design（有 UI）或 /plan。小功能（< 3 文件）可跳过 /spec 直接用 /plan。

完整提示词见 .claude/skills/spec/SKILL.md

4.5 product-design — 产品设计契约

基于已确认的需求（spec.md / prd.md），生成两份项目级契约文件：docs/product-spec.md（产品结构：信息架构、用户旅程、权限矩阵、埋点规格）和 docs/design-spec.md（设计规范：Token 系统、组件规范、交互模式、组合模式）。

核心流程：搜集上下文 → 生成 product-spec（结构先行）→ 生成 design-spec（视觉跟进）→ 双走查清单 → 等待确认。两份文件通过共享组件词汇表（product-spec §0.2）对齐。

下游衔接：product-spec + design-spec → /plan（工作量估计）+ /ui-page（页面生成有确定性输入）+ 美化阶段（Token 约束）。

完整提示词见 .claude/skills/product-design/SKILL.md 设计文档见 23-产品设计契约模板见 docs/templates/product-spec-template.md 和 docs/templates/design-spec-template.md

4.6 plan — 需求分析与方案设计

markdown

---
name: plan
description: >
  需求分析与方案设计。当开始新功能或大改动时使用。
  输出结构化的实现方案，等待人工审批后再执行。
---

# 需求分析与方案设计

## 步骤

1. **理解需求**（按规模分路径）
   使用 AskUserQuestion 向用户确认功能行为、边界、是否有类似功能可参考。
   - **小功能**（改动 < 3 文件，无新数据模型）：确认需求后直接进入步骤 2
   - **中大功能**（跨模块/新数据模型/新 API）：追加结构化提问：
     - 目标用户是谁？要解决什么问题？
     - 核心用户故事（3-7 条）
     - In scope / Out of scope
     - 验收标准（每条用户故事的 Given/When/Then）

2. **检查现有代码**
   搜索代码库中已有的类似功能或可复用模块。
   列出可复用的组件、工具函数、类型定义。

3. **输出实现方案**
   基础格式（所有功能）：

方案概述

[一句话描述实现思路]

影响范围

新建文件：[列出]
修改文件：[列出，标注改动点]
依赖变更：[列出新增/移除的包]

实现步骤

[步骤1 - 具体到文件和函数级别]
[步骤2] ...

风险点

[可能出问题的地方及应对措施]

中大功能额外在方案开头包含：
- **目标与非目标** + **用户故事与验收标准** + **范围边界**（精简 PRD，详见 06-文档体系）
- 当存在 API 变更时，先定义 API 契约（路径、方法、请求/响应 schema）
- 大功能附加实现顺序：Foundation（数据模型+类型）→ Core（业务逻辑）→ Integration（模块连接）→ Polish（错误处理+日志+文档）

4. **等待确认**
IMPORTANT：方案输出后必须等待用户确认，不要自行开始实现。

4.7 review — 代码审查

Commit 前的本地自检，覆盖 5 个审查维度：正确性（Must）、安全性（Must）、性能（Should）、规范（Should）、规格对照（有设计文档时）。

审查原则（借鉴 Anthropic 官方 code-review 插件的多 Agent 验证机制）：

只报高信号问题 — 每条标注置信度（确定/较可能/存疑），宁可漏报不误报
区分新旧问题 — 只审查本次 diff 引入的问题，必要时用 git blame 确认
假阳性过滤 — 不报已有问题、linter 能捕获的、已 suppress 的、主观偏好

输出按严重程度分类：必须修复 → 建议改进 → 小建议，每条含置信度、文件名:行号、修复建议。

完整提示词见 .claude/skills/review/SKILL.md

4.8 debug — 问题诊断

markdown

---
name: debug
description: >
  问题诊断。当遇到 Bug、报错或异常行为时使用。
  系统性定位根因，给出修复方案。
allowed-tools: Read, Grep, Glob, Bash, Edit
---

# 问题诊断

## 步骤

1. **收集信息**
   - 读取报错信息/日志
   - 找到相关源代码
   - 检查最近的 git 变更（`git log --oneline -10`）

2. **定位根因**
   - 从报错点沿调用链向上追踪
   - 检查输入数据是否符合预期
   - 检查是否有最近的代码变更引入了问题

3. **验证假设**
   - 阅读相关测试用例，确认测试是否覆盖了出错场景
   - 如果有多个可能原因，按概率排序，逐一排查

4. **给出修复方案**
   格式：

根因

[一句话描述]

修复方案

[具体修改内容]

验证方法

[如何确认修复有效]

防御措施

[如何防止类似问题再次发生]


5. **等待确认后执行修复**

IMPORTANT：如果不确定根因，明确告知用户你的不确定性，不要猜测性地修改代码。

4.9 commit — 智能提交

markdown

---
name: commit
description: >
  智能提交。完成功能并通过审查后使用。
  生成语义化的 commit message 并执行提交。
---

# 智能提交

## 步骤

1. 运行 `git status` 和 `git diff --staged` 查看变更
2. 如果没有 staged 文件，先 `git add` 相关文件（不要用 `git add .`）
3. 分析变更内容，生成 Conventional Commits 格式的 message：
   `type(scope): 描述`，type 为 feat/fix/refactor/docs/test/chore
4. scope 取模块名，描述用英文 50 字符以内，说明 why 而非 what

## 提交粒度：小步频繁提交

按逻辑单元提交，不按对话轮次提交：
- 完成一个功能点/修复一个 bug → 立即 commit
- 连续迭代同一功能（半成品状态）→ 积累到完成再 commit
- 探索性修改、方案未定 → 暂不 commit
- 判断标准：commit message 能一句话说清；不相关改动不混入同一 commit

IMPORTANT：
- 不要 `git add .`，逐个添加相关文件
- 不要提交 .env 或包含密钥的文件
- 如果变更太大（超过 10 个文件），建议拆分为多次提交

4.10 doc — 文档更新

markdown

---
name: doc
description: >
  文档更新。代码变更后使用，确保文档与代码同步。
  检查并更新 CLAUDE.md、README、API 文档等。
allowed-tools: Read, Write, Edit, Glob, Bash
---

# 文档更新

## 步骤

1. 运行 `git diff --name-only` 查看本次变更的文件列表

2. 检查以下文档是否需要更新：
   - 新增模块/目录 → CLAUDE.md "架构"章节
   - 新增命令 → CLAUDE.md "命令"章节
   - 新增/修改 API → README
   - 新增依赖 → docs/approved-deps.md
   - 重大决策 → docs/adr/ 新增 ADR
3. 执行必要的更新，不需要更新时明确告知用户

IMPORTANT：只更新确实需要更新的文档，不要过度补充。

5. 持续合规 Skills（脚本做不到的深度检查）

脚本的 check 模式只能做确定性检查（文件存不存在、行数超没超）。以下 Skill 处理需要 AI 理解代码语义或文档结构的检查，是脚本的互补层。

5.1 check — 项目合规体检

脚本 check 的智能补充层，处理需要 AI 理解代码语义的检查项。覆盖 4 个维度：CLAUDE.md 健康度（结构一致性、过时条目）、代码规范深度检查（抽查 5 个文件的类型完整性）、依赖合规（对比白名单）、测试覆盖评估。输出按合规 / 需要关注 / 必须修复分类。

完整提示词见 .claude/skills/check/SKILL.md

5.2 docaudit — 文档体系审计

检查文档完整性、索引一致性和规范合规性。五步流程：索引一致性 → 编号连续性 → CHANGELOG 时效性 → 文档行数 → 交叉引用。输出按通过 / 警告 / 错误分类。

完整提示词见 .claude/skills/docaudit/SKILL.md

5.3 takeover — 接管现有项目

全面分析代码库，生成 CLAUDE.md 和体系配置。五步流程：

全局扫描 — Explore Agent 遍历项目结构，理解架构模式和依赖关系
文档盘点 — 检查 README/CLAUDE.md/API 文档等，标注 Current/Stale/Outdated 状态
技术栈识别 — 从 package.json/tsconfig/Dockerfile 等提取技术栈
代码质量快照 — 测试覆盖、代码风格、TODO/FIXME 数量、超长文件
生成配置 — CLAUDE.md + settings.json + approved-deps.md + 分析报告

产物包含置信度标注 [HIGH]/[MEDIUM]/[LOW]，配置是草稿须人工审阅。

完整提示词见 .claude/skills/takeover/SKILL.md

6. 可靠性 Skills

详见 10-可靠性保障体系，以下为清单：

Skill	用途	使用时机
`/impact`	改动影响分析	修改现有功能、重构、改共享类型前
`/test`	测试生成与验证	新功能完成后、Bug 修复时
`/health-report`	项目健康度报告	每两周定期运行

加上之前的 Skills，完整清单为 22 个：

技术调研：  /tech-research（编码前选型调研，context:fork 隔离执行）
产品定义：  /spec（需求分析+产品定义，中大功能的起点）
产品设计：  /product-design（产品结构契约 + 设计规范契约，有 UI 的功能必经）
日常开发：  /plan → /features → /review → /test → /commit → /doc → /debug
可靠性：    /impact → /health-report
持续合规：  /check → /takeover → /docaudit
脚手架：    /ui-page → /docs-site
会话管理：  /checkpoint → /handoff
进化闭环：  /retro（会话回顾） → /absorb（外部知识吸收）
编码规范：  code-standards（自动参考，不需手动调用）

典型工作流：

小功能：                                  /plan → 编码 → /review → /commit
中大功能（无 UI）：               /spec → /plan → 编码 → /commit
中大功能（有 UI）：  /spec → /product-design → /plan → /ui-page → 编码 → /commit
技术选型：            /tech-research → /spec → /plan → 编码
接手项目：            /takeover → /spec → /plan → 编码
会话切换：            /checkpoint → （新会话） → /handoff → 继续工作

7. 进阶

7.1 路由表模式

单个 Skill 知识量大时，用路由表引用外部参考文件（200-400 行/篇），按需加载。

7.2 要素配合

Skill 内部可调度 SubAgent（并行）、调用 MCP（外部数据）；输出受 Hooks 约束；遵循 CLAUDE.md 规则。

7.3 context:fork — 隔离执行

在 frontmatter 中添加 context: fork，Skill 在独立子代理中运行，不占用主会话上下文。可选 agent 字段指定子代理类型（Explore、Plan 等）。

适用场景：重型分析（/impact、/health-report）、研究类 Skill（/tech-research）
权衡：隔离后 Skill 无法访问主会话的对话历史

7.4 动态注入 — !`command`

SKILL.md 正文中可使用 !`shell command`` 语法，在技能内容发送给 Claude 之前执行 shell 命令并将输出内联，Skill 获得实时项目状态。

示例：

!`git log --oneline -5`` — 加载时展开为最近 5 次提交
!`gh pr diff`` — 注入当前 PR 的完整 diff，非常适合 PR 审查技能

适用场景：/review 需要当前 diff、/commit 需要 staged 文件等需要动态上下文的技能。

7.5 参数与变量替换

Skills 支持位置参数：$ARGUMENTS（完整字符串）、$ARGUMENTS[0]（第一个，也可用 $1）。

示例：SKILL.md 中写 将组件 $ARGUMENTS[0] 从 $ARGUMENTS[1] 迁移到 $ARGUMENTS[2]，调用 /migrate-component SearchBar React Vue 时自动展开。

此外支持环境变量替换：${CLAUDE_SESSION_ID} 展开为当前会话 ID，可用于生成唯一标识或日志追踪。

8. Plugin 生态与资源导航

Plugin 是 Skills 的上层封装，将 skills + hooks + subagents + MCP servers 打包为单一可安装单元。Anthropic 官方 Marketplace 已上线，企业也可托管自有 Marketplace。

安装范围：User（默认，全局生效）/ Project（仅当前项目）/ Local（本地开发用）。

安全提醒：安装第三方 Plugin 前应审查其代码，Plugin 拥有 Skills + Hooks 的全部权限。

8.1 官方资源

资源	地址	说明
官方插件仓库	anthropics/claude-code/plugins	13 个官方插件（code-review、feature-dev、security-guidance 等）
官方插件市场	anthropics/claude-plugins-official	默认启用的插件目录，`/plugin` → Discover 标签浏览
Skills 官方文档	code.claude.com/docs/en/skills	Skill 编写规范与 Agent Skills 开放标准
插件发现指南	code.claude.com/docs/en/discover-plugins	市场添加、插件安装的完整流程

8.2 社区市场与精选列表

资源	地址	说明
Claude Code Templates	aitmpl.com	400+ 组件（agents/commands/hooks），支持一键安装
Build with Claude	buildwithclaude.com	应用商店式聚合站，按分类浏览插件
Awesome Agent Skills	VoltAgent/awesome-agent-skills	800+ 跨平台 Agent Skills（Anthropic、Vercel、Stripe 等官方团队贡献）
Awesome Claude Code	hesreallyhim/awesome-claude-code	Skills/Hooks/CLI 工具精选列表
Composio Awesome Skills	ComposioHQ/awesome-claude-skills	侧重外部应用集成（GitHub/Slack/Jira）

8.3 功能增强套件

资源	地址	说明
Superpowers (Obra)	obra/superpowers	完整开发方法论：TDD、调试、计划、子代理驱动开发
Claude Skills Collection	alirezarezvani/claude-skills	53 个领域专家 Skill（工程/产品/运维/架构）

8.4 快速安装

bash

# 添加官方市场（默认已启用）
/plugin marketplace add anthropics/claude-plugins-official

# 添加社区市场
/plugin marketplace add obra/superpowers-marketplace
/plugin marketplace add davepoon/buildwithclaude

# 查看可用插件
/plugin   # → Discover 标签浏览、安装

02 - Skills 技能体系设计 ​

1. 定位 ​

三阶段代码质量管线 ​

/simplify 安全使用指南 ​

2. 渐进式披露机制 ​

3. SKILL.md 标准格式 ​

4. 核心 Skills 清单 ​

4.1 code-standards — 编码规范守卫 ​

4.2 tech-research — 技术调研 ​

4.4 spec — 需求分析与产品定义 ​

4.5 product-design — 产品设计契约 ​

4.6 plan — 需求分析与方案设计 ​

方案概述 ​

影响范围 ​

实现步骤 ​

风险点 ​

4.7 review — 代码审查 ​

4.8 debug — 问题诊断 ​

根因 ​

修复方案 ​

验证方法 ​

防御措施 ​

4.9 commit — 智能提交 ​

4.10 doc — 文档更新 ​

5. 持续合规 Skills（脚本做不到的深度检查） ​

5.1 check — 项目合规体检 ​

5.2 docaudit — 文档体系审计 ​

5.3 takeover — 接管现有项目 ​

6. 可靠性 Skills ​

7. 进阶 ​

7.1 路由表模式 ​

7.2 要素配合 ​

7.3 context:fork — 隔离执行 ​

7.4 动态注入 — !command ​

7.5 参数与变量替换 ​

8. Plugin 生态与资源导航 ​

8.1 官方资源 ​

8.2 社区市场与精选列表 ​

8.3 功能增强套件 ​

8.4 快速安装 ​

02 - Skills 技能体系设计

1. 定位

三阶段代码质量管线

`/simplify` 安全使用指南

2. 渐进式披露机制

3. SKILL.md 标准格式

4. 核心 Skills 清单

4.1 code-standards — 编码规范守卫

4.2 tech-research — 技术调研

4.4 spec — 需求分析与产品定义

4.5 product-design — 产品设计契约

4.6 plan — 需求分析与方案设计

方案概述

影响范围

实现步骤

风险点

4.7 review — 代码审查

4.8 debug — 问题诊断

根因

修复方案

验证方法

防御措施

4.9 commit — 智能提交

4.10 doc — 文档更新

5. 持续合规 Skills（脚本做不到的深度检查）

5.1 check — 项目合规体检

5.2 docaudit — 文档体系审计

5.3 takeover — 接管现有项目

6. 可靠性 Skills

7. 进阶

7.1 路由表模式

7.2 要素配合

7.3 context:fork — 隔离执行

7.4 动态注入 — !`command`

7.5 参数与变量替换

8. Plugin 生态与资源导航

8.1 官方资源

8.2 社区市场与精选列表

8.3 功能增强套件

8.4 快速安装