古法编程

Claude Code 的 Skill 是将领域专长和工作流打包成可复用模块的能力。本文将基于 Claude HowTo 教程指南 中的实际代码，详细拆解 6 个实用 Skill 示例：code-review-specialist 提供安全、性能、质量、可维护性四维审查；code-refactor 遵循 Fowler 方法论的 6 阶段安全重构工作流；blog-draft 实现了 10 步迭代写作与版本追踪。以下是它们的创建、配置与使用指南。

6 个实用 Skill 示例：代码审查、品牌一致性、文档生成、重构、CLAUDE.md 管理和博客草稿

Claude Code 的 Skills 功能允许你将可复用的领域知识、工作流和最佳实践打包为独立模块，让 Claude 在需要时自动加载，无需在每次对话中重复提供指令。下面我们将基于 Claude HowTo 项目 中的实际 skill 目录，深入分析 6 个各具特色的实用 Skill 示例。

1. 代码审查专家 (code-review-specialist)

这是一个结构化的四维审查框架，专注于发现代码中的深层问题。

核心能力

该 skill 将代码审查系统化为四个维度：

  • 安全分析：检查认证授权漏洞、数据泄露、注入攻击、弱加密和敏感信息日志记录。
  • 性能审查：分析算法效率（Big O）、内存优化、数据库查询、缓存机会和并发问题。
  • 代码质量：评估 SOLID 原则、设计模式、命名规范、文档和测试覆盖率。
  • 可维护性：关注代码可读性、函数长度（建议少于50行）、圈复杂度、依赖管理和类型安全。

目录结构与关键文件 

~/.claude/skills/code-review-specialist/
├── SKILL.md                           # 主指令文件
├── templates/
│   ├── review-checklist.md            # 结构化审查清单（关键模板）
│   └── finding-template.md            # 单个问题记录模板
└── scripts/
    ├── analyze-metrics.py             # 计算代码指标的脚本
    └── compare-complexity.py          # 比较重构前后复杂度的脚本

审查清单模板 (review-checklist.md) 是该 skill 的核心输出。它提供了一个包含 40 个检查项的标准化清单，确保审查不会遗漏任何类别。以下是其安全检查项的节选：

## Security Checklist
- [ ] No hardcoded credentials or secrets
- [ ] Input validation on all user inputs
- [ ] SQL injection prevention (parameterized queries)
- [ ] CSRF protection on state-changing operations
- [ ] XSS prevention with proper escaping
- [ ] Authentication checks on protected endpoints
...

问题记录模板 (finding-template.md) 则为每个发现的问题定义了标准化格式，包括严重等级、类别、位置、代码示例、影响分析和修复建议。

安装与使用

  1. 安装：将整个 code-review-specialist 目录复制到你的个人（~/.claude/skills/）或项目（.claude/skills/）技能目录。
  2. 调用：
    • 自动触发：当你的请求包含“审查代码”、“分析代码质量”、“评估PR”等关键词时，Claude 会自动识别并激活该 skill。
    • 手动调用：使用斜杠命令 /code-review-specialist，可附带文件名作为参数，如 /code-review-specialist src/auth/login.ts。
  3. 输出：Claude 会按照 SKILL.md 中定义的模板，输出包含总体评估、关键发现、按类别（安全/性能/质量/可维护性）划分的详细问题列表。

2. 品牌声音一致性 (brand-voice)

该 skill 确保所有对外内容符合统一的品牌声音和语调指南，适用于营销文案、客户沟通和公开内容创作。

目录结构 

~/.claude/skills/brand-voice/
├── SKILL.md                # 主指令文件，定义了品牌身份、写作指南和词汇表
└── tone-examples.md        # 不同场景下的语调示例（作为参考资源）

关键配置与使用

  • 主要作用：这是一个“背景知识型” skill。在 SKILL.md 的前端元数据中，它被配置为 user-invocable: false，意味着用户无法通过 / 菜单直接调用它，但 Claude 在创建任何面向用户的文本时会自动参考其中的指南。
  • 核心指南：它定义了品牌使命、价值观、语调（友好专业、清晰简洁、自信、有同理心）以及具体的“该做”与“不该做”列表，例如优先使用“Claude”而非“the Claude AI”，避免使用“leverage”、“utilize”等企业术语。

安装

将 brand-voice 目录复制到技能目录即可。它会在后台默默工作，提升所有内容输出的品牌一致性。

3. API 文档生成器 (doc-generator)

此 skill 用于从源代码生成全面、准确的 API 文档。

目录结构 

~/.claude/skills/doc-generator/
└── SKILL.md    # 定义了文档结构和生成逻辑

功能与模板

SKILL.md 中明确定义了文档生成的标准化结构。对于每一个 API 端点，它都会要求 Claude 生成：

  1. 端点描述。
  2. 参数表格（名称、类型、必需、描述）。
  3. 不同状态码（如 200 Success, 404 Not Found）的 JSON 响应示例。
  4. 多语言（cURL, JavaScript, Python）的调用示例。

安装与调用

安装后，通过描述你的需求（如“为 /api/v1/users/:id 端点生成文档”）或使用 /api-documentation-generator 命令来调用。它适合快速生成 OpenAPI 规范或 SDK 使用示例。

4. 代码重构 (refactor)

这是一个基于 Martin Fowler 《重构》方法论的系统性重构指南，强调安全、增量式的变更，并以测试作为安全网。

核心：Fowler 6 阶段工作流

SKILL.md 定义了一个必须与用户逐步确认的 6 阶段工作流：

  1. 研究与分析：理解代码库，明确重构范围和目标。
  2. 测试覆盖评估：检查现有测试，这是安全重构的前提。
  3. 代码异味识别：系统化地识别代码中的问题。
  4. 重构计划创建：为每个“异味”选择并规划具体的重构技术。
  5. 增量实现：遵循“变更 -> 测试 -> 通过？ -> 提交”的黄金法则，每次只做一个微小改动。
  6. 审查与迭代：对比重构前后的指标，评估改进效果。

目录结构与关键资源 

~/.claude/skills/refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md             # 代码异味完整目录（关键参考）
│   └── refactoring-catalog.md     # 重构技术目录
├── templates/
│   └── refactoring-plan.md        # 重构计划模板
└── scripts/
    ├── analyze-complexity.py      # 分析代码复杂度的脚本
    └── detect-smells.py           # 自动检测代码异味的脚本

代码异味目录 (code-smells.md) 是该 skill 的核心知识库。它将代码异味分为 5 大类，并提供了识别标志、危害解释、推荐的重构技术和代码示例：

  1. 膨胀者 (Bloater)：过大的代码。如过长方法、过大类、基本类型偏执、过长参数列表、数据泥团。
  2. 面向对象滥用者 (OO Abuser)：对 OOP 的误用。如开关语句、临时字段、被拒绝的馈赠、异曲同工的类。
  3. 变革阻止者 (Change Preventer)：阻碍修改的代码。如发散式变化、散弹式修改、平行继承体系。
  4. 可有可无者 (Dispensable)：冗余代码。如过多注释、重复代码、冗赘类、死代码、夸夸其谈未来性。
  5. 耦合过度者 (Coupler)：过度耦合的代码。如特性依恋、不当亲密、消息链、中间人。

安装与使用

安装后，当你说“重构这段代码”、“减少技术债务”时，Claude 会激活此 skill。它将引导你完成一个严谨的、以对话推进的重构过程，每一步都需要你的明确批准，确保外部行为不变。

5. CLAUDE.md 管理 (claude-md)

该 skill 专注于创建和优化 CLAUDE.md 文件——Claude Code 最重要的项目上下文入口。

黄金规则与执行流程

SKILL.md 明确提出了管理 CLAUDE.md 的四条黄金规则：

  1. 少即是多：保持少于 300 行（理想情况低于 100 行）。
  2. 普遍适用：只包含适用于 每次 会话的信息。
  3. 勿当代码检查工具：不要包含代码风格规则，使用 prettier、eslint 等专用工具。
  4. 切勿自动生成：必须手动精心制作。

它的执行流程包括：项目分析（检查现有 CLAUDE.md 和项目结构）、内容策略（围绕 WHAT-技术结构、WHY-目的背景、HOW-工作流公约三维度组织）、渐进式披露策略（对于复杂项目，建议将细节放在 agent_docs/ 目录，并在 CLAUDE.md 中引用）。

目录与使用 

~/.claude/skills/claude-md/
└── SKILL.md    # 定义了创建、更新、审计 CLAUDE.md 的完整流程

你可以用 /claude-md create、/claude-md update 或 /claude-md audit 命令来调用它，分别用于创建新文件、优化现有文件或只生成质量报告。

6. 博客草稿 (blog-draft)

该 skill 提供了一套从想法到成稿的 10 步结构化写作流程，并内置了版本控制。

10 步迭代工作流

SKILL.md 中定义的流程确保了写作的质量和可追溯性： 0. 创建项目文件夹。

  1. 研究与资源收集：将用户提供的 URL、文件等资料摘要并存入 resources/ 目录。
  2. 头脑风暴与澄清：基于研究提炼主题、角度和要点，并向用户提问。
  3. 提出大纲：生成结构化大纲（含元信息、钩子、各章节要点、结论、引用来源）。
  4. 保存并提交大纲。
  5. 撰写初稿：基于大纲写作，并严格要求所有数据和比较都必须有内联引用。
  6. 提交初稿。
  7. 呈现初稿供审阅。
  8. 迭代或定稿：根据反馈修改，版本号递增（v0.2, v0.3…），或确认最终版本。

版本跟踪机制

所有草稿都以递增版本号保存（draft-v0.1.md, draft-v0.2.md …），使得写作过程的演变清晰可查，并支持回退。

目录结构

安装后，所有博客项目都会遵循以下文件结构：

blog-posts/
└── YYYY-MM-DD-topic-name/
    ├── resources/          # 研究资料摘要
    ├── OUTLINE.md          # 审核通过的大纲
    ├── draft-v0.1.md       # 初稿
    └── draft-v0.2.md       # 迭代稿（如有）

通用安装步骤与验证

安装所有 skill 的步骤一致：

  1. 从 Claude HowTo 项目仓库中，找到对应的 skill 目录（如 03-skills/code-review-specialist）。
  2. 将其完整复制到你的技能目录：
    • 个人级：~/.claude/skills/ （仅你可用）
    • 项目级：.claude/skills/ （通过 Git 共享给团队）
  3. 对于包含 scripts/ 目录的 skill（如 code-review-specialist, refactor），可能需要赋予脚本执行权限：chmod +x ~/.claude/skills/your-skill/scripts/*.py。

验证安装：

  • 启动新的 Claude Code 会话。
  • 输入 “What Skills are available?”，Claude 应列出你安装的 skill。
  • 尝试触发：例如，粘贴一段代码并说 “请帮我进行代码审查”，观察 Claude 是否加载了四维框架和检查清单。

FAQ

Q: Skill 和之前的自定义斜杠命令 (.claude/commands/) 有什么关系？ A: 自定义斜杠命令的功能已经合并到 Skills 中。旧的 .claude/commands/ 文件仍然兼容，但新功能推荐使用 Skills 的 SKILL.md 格式。如果同一路径下存在两者，Skill 会优先被加载。

Q: 我可以限制某个 Skill 只能手动调用，不让 Claude 自动触发吗？ A: 可以。在 SKILL.md 的前端元数据中设置 disable-model-invocation: true。这样，该 skill 只能通过 /skill-name 命令手动调用，Claude 不会根据你的描述自动激活它。这对于有副作用的工作流（如部署）非常有用。