Claude Code Skill 的编写

从零基础到生产级，系统掌握 Claude Code Skill 的编写。本文从最小可用技能开始，逐步叠加知识、权限、模板、脚本、决策树，最终构建一个资深级的复杂技能。

一、核心概念基础

1.1 什么是 Skill

Skill 是一个上下文注入包。激活后，Claude Code 会将指定文件夹中的指令、知识、权限配置注入对话上下文，使模型在限定范围内表现出专业行为。

1.2 最小技能结构

my-skill/
└── SKILL.md # 唯一必需文件

SKILL.md 包含两部分：

• YAML 前置元数据：定义技能名称、描述、权限等。
• Markdown 正文：写给 Claude 的系统指令。

1.3 SKILL.md 示例（入门）

—
name: hello
description: 一个示例技能
—

# Hello 技能
当我提问时，请先回答“你好，我是由技能驱动的助手”。

这就是一个可工作的技能。安装后，每次激活时 Claude 都会加上这句问候。

二、核心知识点逐层展开

2.1 元数据字段（必知必会）

• name：技能唯一标识，用 kebab-case。
• description：描述技能功能，显示在 /skills 列表中。
• allowed-tools：工具白名单，强烈推荐。不设则继承当前会话全部权限。
• model：锁定模型，如 claude-sonnet-4-20250514。
• files：激活时预加载的文件列表，很少用，改用 {{ include }} 更灵活。

2.2 工具权限（安全核心）

allowed-tools 语法：工具名(限定)，逗号分隔。

• 读工具通常全开：Read, Grep, Glob
• 写工具必须限定路径：Write(templates/*.ts), Edit(src/**)
• Bash 必须限定命令：Bash(git:status, git:diff, npm:run:lint)
• 权限是替换式，激活时覆盖当前会话权限。

2.3 {{ include }} 指令

将技能目录下的文件内容注入到指令正文中，减少 SKILL.md 体积，方便管理。

请遵守以下编码规范：
{{ include "knowledge/style-guide.md" }}

2.4 技能目录组织约定

my-skill/
├── SKILL.md
├── templates/ # 代码模板
├── knowledge/ # 规范、知识
├── scripts/ # 受控执行脚本
├── examples/ # 示例输入输出
└── schemas/ # JSON Schema 等

这不是强制的，但随着复杂度增长，合理的目录结构是技能可维护性的基础。

三、案例一：Git 辅助技能（入门级）

目标：生成 Conventional Commits，并执行安全的 Git 操作。

目录结构

git-helper/
└── SKILL.md

SKILL.md

—
name: git–helper
description: 根据暂存变更生成规范的 Git 提交信息，并执行安全提交。
allowed-tools: Read, Bash(git:status, git:diff, git:add, git:commit)
—

# Git Helper

## 角色
你是一个严格遵守 Conventional Commits 的 Git 助手。

## 流程
1. 执行 `git status –porcelain` 和 `git diff –staged` 获取暂存区变化。
2. 根据变更内容生成一条提交信息，格式：
– `feat: 描述` 新功能
– `fix: 描述` 修复
– `refactor: 描述` 重构
– `test: 描述` 测试
– `docs: 描述` 文档
3. 将生成的提交信息展示给用户确认，再执行 `git commit -m "…"`。

## 禁止
– 不得执行 force push。
– 不得修改暂存区以外的文件。

知识点总结

• 权限锁定在 git status/diff/add/commit，绝对安全。
• 指令结构化：角色 + 流程 + 禁止项。
• 简单清晰，一个文件搞定。

四、案例二：代码审查技能（进阶级）

目标：结合 lint 工具、团队规范和模板，输出分级审查报告。

目录结构

code-reviewer/
├── SKILL.md
├── templates/
│ └── review-checklist.md
└── scripts/
└── run_lint.sh

SKILL.md

—
name: code–reviewer
description: 基于团队规范与 Lint 结果的代码审查，输出分级报告。
allowed-tools: Read, Grep, Glob, Bash(git:diff, bash:./scripts/run_lint.sh)
model: claude–sonnet–4–20250514
—

# 代码审查技能

## 角色
你是一位前端审查员，遵守团队规范。

## 审查清单
以下是必须逐条核对的标准：
{{ include "templates/review-checklist.md" }}

## 工作流
1. 获取暂存区 diff：`git diff –staged`
2. 运行 lint：`bash ./scripts/run_lint.sh`
3. 结合 diff 和 lint 结果，依据审查清单给出分级：
– 🔴 错误：必须修复
– 🟡 警告：应该修复
– 🔵 建议：可忽略
4. 输出表格报告：

| 级别 | 类别 | 文件:行号 | 描述 | 修复建议 |
|——|——|———–|——|———-|
| … | … | … | … | … |

## 禁止
– 不得直接修改任何源文件。
– 不要建议推翻整个架构。

templates/review-checklist.md

– 类型安全：所有函数必须注明参数和返回值类型。
– 命名规范：变量 camelCase，组件 PascalCase。
– 错误处理：禁止空 catch。
– 副作用：React 组件 render 内不能有数据请求。

scripts/run_lint.sh

#!/bin/bash
npx eslint –format json "${@:-.}" || true

知识点总结

• 使用 {{ include }} 加载外部规范文件，SKILL.md 保持简洁。
• 通过封装脚本 run_lint.sh 运行 lint，获得确定性 JSON 输出，Claude 解析结构化数据。
• 权限包含脚本调用，限制了直接 Bash 的风险。
• 指定模型保证输出质量。

五、案例三：全栈重构智能体（资深级）

目标：构建一个对全栈 TypeScript 单体仓库进行安全、分阶段重构的复杂技能。涵盖前端（React）、后端（Express）、数据库（TypeORM），要求生成回滚、更新 API 契约、保证测试通过。

5.1 技能架构设计

此技能将遵循分层架构：

• 调度层：SKILL.md 作为中央调度器，根据阶段动态加载工作流。
• 知识层：团队规范、设计模式、反模式、术语表。
• 资源层：代码模板、数据库迁移模板、API 契约 Schema。
• 执行层：受控脚本（lint、测试、迁移安全检查）。
• 示例层：历史成功重构案例，用作少样本教学。

5.2 完整目录结构

fullstack-refactor/
├── SKILL.md
├── .claude/
│ └── rules/
│ ├── security.md
│ └── architecture.md
├── core/
│ ├── workflows/
│ │ ├── assess.md
│ │ ├── plan.md
│ │ ├── execute.md
│ │ └── verify.md
│ └── decision-trees/
│ └── db-strategy.md
├── knowledge/
│ ├── conventions/
│ │ ├── backend.md
│ │ ├── frontend.md
│ │ └── database.md
│ ├── patterns/
│ │ ├── approved.md
│ │ └── anti-patterns.md
│ └── glossary.md
├── templates/
│ ├── migration/
│ │ └── typeorm.template.ts
│ ├── component/
│ │ └── functional.template.tsx
│ └── api/
│ └── controller.template.ts
├── schemas/
│ └── api-contract.schema.json
├── scripts/
│ ├── run_lint.sh
│ ├── run_tests.sh
│ └── check_migration_safety.py
├── examples/
│ └── rename-field/
│ ├── request.md
│ └── result.md
└── VERSION

5.3 核心指令：SKILL.md

—
name: fullstack–refactor
description: 全栈重构智能体，分阶段安全地重构 React、Node.js、TypeORM 项目。
allowed-tools: Read, Write(apps/*,packages/*), Edit(apps/*,packages/*), Grep, Glob,
Bash(git:status,git:diff,git:add,git:commit,
npm:run:lint, npm:test,
bash:scripts/run_lint.sh, bash:scripts/run_tests.sh,
python:scripts/check_migration_safety.py)
model: claude–opus–4–20250514
—

# 全栈重构智能体

## 角色
你是资深全栈架构师，精通 React、Node.js、TypeORM、PostgreSQL。
你的使命：安全地执行用户提出的重构请求。

## 全局约束
– 必须遵循 `knowledge/conventions/` 下所有规范。
– 使用 `knowledge/glossary.md` 中的术语。
– 数据库变更必须经过 `scripts/check_migration_safety.py` 验证。
– API 变更需同步更新 `schemas/api-contract.schema.json`。
– 前端组件重构不得破坏现有测试。

## 分阶段执行
严格按照以下阶段进行，每阶段结束必须获得用户确认才能继续。

### 阶段 1: 评估
{{ include "core/workflows/assess.md" }}

### 阶段 2: 规划
{{ include "core/workflows/plan.md" }}

### 阶段 3: 执行
{{ include "core/workflows/execute.md" }}

### 阶段 4: 验证
{{ include "core/workflows/verify.md" }}

## 决策支持
当涉及数据库变更时，必须依据决策树：
{{ include "core/decision-trees/db-strategy.md" }}

## 示例参考
理想的重构行为应参考 `examples/rename-field/`，学习其回滚策略和前后端协调。

## 禁止
– 绝不直接修改生产配置 (`*.prod.*`)。
– 绝不跳过安全检查。
– 绝不删除现有测试。

5.4 工作流文件（部分示例）

core/workflows/assess.md

## 评估阶段
### 行动
1. 运行 `git status` 和 `git log –oneline -10` 理解上下文。
2. 与用户沟通明确重构目标。
3. 使用 Grep/Glob 定位所有受影响模块。
4. 列出所有相关测试文件。
5. 若涉及数据库实体，读取对应 Entity 文件。

### 输出
生成影响分析报告：
– 受影响模块 (前端/后端/数据库)
– 风险等级 (高/中/低)
– 建议策略 (渐进式/大爆炸)

等待用户确认进入规划阶段。

core/decision-trees/db-strategy.md

## 数据库变更策略决策树
– 添加可空列 → 直接添加
– 添加非空列 → 1) 先添加为可空 2) 回填数据 3) 添加 NOT NULL
– 重命名列 → 保留旧列，新增列，复制数据，标记旧列为 @deprecated，待前端适配后移除
– 删除列 → 先标记 @deprecated，至少一个大版本后删除

5.5 知识层文件示例

knowledge/conventions/backend.md

### 错误处理
– 异步操作必须 try/catch，抛出 AppError。
– 禁止 console.log，使用 winston。

### 数据库
– 使用 TypeORM QueryBuilder，禁止拼接 SQL。

knowledge/patterns/anti-patterns.md

1. 在 React 组件内直接调 API → 使用自定义 hook。
2. 迁移文件中做复杂数据转换 → 移至服务层。

5.6 模板示例

templates/migration/typeorm.template.ts

import { MigrationInterface, QueryRunner } from "typeorm";

export class Migration{{Timestamp}} implements MigrationInterface {
name = 'Migration{{Timestamp}}'

public async up(queryRunner: QueryRunner): Promise<void> {
// UP: {{Description}}
{{UpStatements}}
}

public async down(queryRunner: QueryRunner): Promise<void> {
// DOWN: {{Description}}
{{DownStatements}}
}
}

指令中要求：生成迁移时必须读取此模板，替换占位符，然后写入 migrations/ 目录。

5.7 脚本层

scripts/check_migration_safety.py 应输出 JSON：

{"safe": true, "issues": []}

在 execute 工作流中强制要求：“生成迁移文件后，立即运行 python scripts/check_migration_safety.py <迁移文件路径>，分析 JSON 输出，如果 safe 不为 true，则中止并报告问题。”

5.8 示例层

examples/rename-field/request.md 和 result.md 提供完整的对话转录，展示成功重命名数据库列的全过程。Claude 会将其作为理想行为模式参考。

5.9 动态加载与自省

在 SKILL.md 中虽然没有条件 include，但可通过引导实现伪动态：

根据重构类型，主动使用 Read 工具加载以下文件：
– 若涉及后端：加载 `knowledge/conventions/backend.md`
– 若涉及前端：加载 `knowledge/conventions/frontend.md`
– 若涉及数据库：加载 `knowledge/conventions/database.md`

Claude 会根据指令自行调用 Read 工具按需加载，避免上下文浪费。

5.10 验证和 CI 集成

VERSION 文件记录版本，tests/ 目录可放验证脚本，例如检查所有 include 路径是否存在，YAML 格式是否正确，权限是否过度开放。可集成到 GitHub Actions，确保技能质量。

六、资深级技能的设计原则

七、总结

从单文件问候技能，到带权限、模板的审查器，再到全栈重构智能体，复杂度逐步递增，但底层逻辑不变：技能 = 受限上下文 + 结构化知识 + 受控执行。掌握这一模式后，任何工程领域的重复或规范敏感工作都可以封装为可靠、可共享的技能。