Claude Code 配置完全指南（四）：Skill 技能系统的 4 种设计模式

系列第 4 篇 | 2026-07-22
配套仓库：C:\Users\zhang\.claude\skills\（27 个 Skill）

---

前言

Skill 是 Claude Code 扩展体系中最灵活的一层。一个 Skill 就是一个 Markdown 文件，不需要定义工具权限、不需要管理会话状态——它只是在你调用时注入一段领域知识或操作指令。

我在 .claude/skills/ 下积累了 27 个 Skill，经过反复迭代，总结出 4 种通用设计模式。每种模式解决一类问题，学会之后你也能在 30 分钟内写出自己的 Skill。

---

一、Skill 的底层机制

在你理解设计模式之前，先搞清楚 Skill 是怎么工作的：

1. 你在 Claude Code 中输入 /skill my-skill 或用自然语言触发
2. Claude Code 读取 skills/my-skill.md 的全部内容
3. 将内容作为 System Prompt 的追加段注入当前对话
4. LLM 在接下来的对话中严格遵守 Skill 中的指令

所以 Skill 本质上是一段临时追加的 System Prompt。它不改变 Claude Code 的任何全局行为，只影响当前对话轮次。

---

二、设计模式一：领域知识注入

适用场景：让 Claude Code 理解某个特定领域的规范、术语、最佳实践。

模板：

# [领域名称] Skill

## 领域背景
[简要说明这个领域是什么]

## 核心规则
1. [规则 1]
2. [规则 2]
3. [规则 3]

## 常见陷阱
- [陷阱 1]：[为什么容易犯错 + 正确做法]
- [陷阱 2]：[为什么容易犯错 + 正确做法]

## 检查清单
- [ ] [检查项 1]
- [ ] [检查项 2]

实例：API 文档校验 Skill

# API 文档校验 Skill

## 领域背景
你正在校验一份 RESTful API 文档，需要确保它符合 OpenAPI 3.0 标准。

## 核心规则
1. 所有路径必须以 `/api/` 开头
2. 每个端点必须有 `summary` 和 `description`
3. 响应必须声明 `content-type: application/json`
4. 分页接口必须包含 `page`、`page_size`、`total` 三个字段
5. 错误响应必须包含 `code`、`message`、`detail` 三个字段

## 常见陷阱
- 路径参数写了但没在 parameters 中声明：检查所有 `{xxx}` 格式的路径段
- 枚举值只写了英文没写中文说明：每个 enum 必须有 description
- 时间字段没声明时区：所有日期时间必须标注 UTC+8

## 检查清单
- [ ] 路径命名是否符合 RESTful 规范
- [ ] 请求/响应 Schema 是否完整
- [ ] 错误码定义是否覆盖所有异常场景
- [ ] 分页参数是否标准化
- [ ] 认证方式是否在文档中说明

---

设计模式二：操作流程固化

适用场景：将一系列固定操作步骤封装成 Skill，避免每次重复描述。

模板：

# [操作名] Skill

## 触发条件
当用户说 [触发词] 时执行此流程。

## 执行步骤

### 步骤 1：[步骤名]
- 动作：[具体做什么]
- 验证：[如何确认步骤成功]

### 步骤 2：[步骤名]
- 动作：[具体做什么]
- 验证：[如何确认步骤成功]

## 异常处理
- 如果 [情况 A]：则 [处理方式]
- 如果 [情况 B]：则 [处理方式]

## 完成标准
- [ ] [标准 1]
- [ ] [标准 2]

实例：项目初始化 Skill

# 项目初始化 Skill

## 触发条件
当用户说"初始化项目"、"创建新项目"、"搭建项目"时执行。

## 执行步骤

### 步骤 1：环境检查
- 动作：检查 Python 版本 >= 3.11、Node.js >= 18
- 验证：`python --version` 和 `node --version` 输出符合要求

### 步骤 2：后端脚手架
- 动作：创建 backend/ 目录结构，写入 main.py、database.py、models.py、requirements.txt
- 验证：`cd backend && python -c "import fastapi"` 成功

### 步骤 3：前端脚手架
- 动作：执行 `npm create vite@latest frontend -- --template vue-ts`，安装依赖
- 验证：`cd frontend && npm run dev` 成功启动

### 步骤 4：联调验证
- 动作：同时启动前后端，确认前端能请求到后端的 /api/health
- 验证：浏览器打开前端页面，健康检查返回 200

## 异常处理
- 如果 Python 版本过低：提示用户升级，推荐使用 anaconda 创建新环境
- 如果 npm 安装失败：自动切换到清华镜像源重试

## 完成标准
- [ ] 前后端目录结构符合规范
- [ ] requirements.txt 和 package.json 已生成
- [ ] 后端健康检查端点可用
- [ ] 前端能成功启动并代理 API 请求

---

设计模式三：行为约束

适用场景：在特定场景下限制 Claude Code 的行为，防止它"越权"。

模板：

# [约束场景] Skill

## 适用范围
此 Skill 在 [场景描述] 时生效。

## 行为约束

### 禁止操作
- 禁止 [操作 A]
- 禁止 [操作 B]

### 必须操作
- 必须 [操作 C]
- 必须 [操作 D]

## 违规处理
如果 AI 试图执行禁止操作，立即停止并提示用户。

实例：只读代码审查 Skill

# 只读代码审查 Skill

## 适用范围
当用户要求代码审查、代码检查、代码评审时自动生效。

## 行为约束

### 禁止操作
- 禁止修改任何文件
- 禁止执行任何命令
- 禁止运行代码
- 禁止创建新文件

### 必须操作
- 必须逐文件检查代码规范
- 必须对每个问题给出具体行号和修改建议
- 必须区分"必须修改"和"建议优化"
- 必须用 Markdown 表格输出审查结果

## 违规处理
如果试图执行 Write、Edit、Bash 等操作，立即停止并提示："当前为只读审查模式，不能执行写操作。"

## 输出格式

| 文件 | 行号 | 严重程度 | 问题描述 | 修改建议 |
|------|------|---------|---------|---------|
| xxx.py | 42 | 严重 | SQL 注入风险 | 使用参数化查询 |
| xxx.py | 78 | 建议 | 函数过长 | 拆分为 3 个子函数 |

---

设计模式四：模板生成

适用场景：需要 Claude Code 按固定格式生成输出（如周报、会议纪要、Commit Message）。

模板：

# [模板名] Skill

## 触发条件
用户要求生成 [模板用途] 时使用。

## 输出模板

[完整的模板结构]

## 填充规则
- [字段 A]：[从哪里获取 / 如何生成]
- [字段 B]：[从哪里获取 / 如何生成]

## 示例

[一个完整的示例输出]

实例：Commit Message 生成 Skill

# Commit Message 生成 Skill

## 触发条件
用户说"写 commit"、"生成 commit message"、"提交信息"时触发。

## 输出模板

():

填充规则

• type：根据变更内容自动判断

  • feat：新功能 → 有新的文件或函数
  • fix：修 Bug → 修改了错误逻辑
  • refactor：重构 → 改了结构但没改功能
  • docs：文档 → 只改了 .md 文件
  • chore：杂项 → 依赖更新、配置修改

• scope：从修改的文件路径中提取

  • backend/routers/ → api
  • frontend/src/views/ → ui
  • database/ → db

• subject：一句话概括变更，50 字以内，中文

• body：列出具体变更（每条一行，以 - 开头）

• footer：如果有关联 Issue，写 Closes #xxx

示例

feat(api): 新增用户管理 CRUD 接口

- 新增 User 数据模型（id, name, email, created_at）
- 实现 GET/POST/PUT/DELETE /api/users 路由
- 添加用户邮箱唯一性校验
- 前端新增用户列表页和编辑弹窗

Closes #42

---

## 三、Skill 的存放位置与命名规范

.claude/skills/
├── api-doc-validator.md # 领域知识型
├── project-init.md # 操作流程型
├── readonly-code-review.md # 行为约束型
├── commit-message.md # 模板生成型
└── …

**命名规范**：
- 全部小写 + 连字符
- 文件名暗示用途：`api-doc-validator` 比 `skill-1.md` 好一百倍
- 不需要编号前缀（Claude Code 用文件名匹配，不用顺序）

---

## 四、Skill 开发的三要三不要

**要做**：
1. 每个 Skill 只做一件事——不要写"万能 Skill"
2. 给出具体示例——LLM 对示例的理解远好于抽象规则
3. 在末尾加一个"常见错误"段落——预防比纠错更高效

**不要做**：
1. 不要在 Skill 里写"请务必"、"请注意"等礼貌用语——它们占用 Token 且不影响 LLM 行为
2. 不要让 Skill 超过 200 行——超过说明你在写 Agent，应该升级为 Agent
3. 不要在 Skill 里引用其他 Skill——Skill 之间不共享上下文

---

## 五、我的 27 个 Skill 分类

出于篇幅原因不逐个展示，但可以透露分类：

| 类别 | 数量 | 典型 Skill |
|------|------|-----------|
| 代码质量 | 6 | 代码审查、命名检查、复杂度分析 |
| 文档生成 | 5 | API 文档、README 模板、变更日志 |
| 工作流 | 7 | 项目初始化、发版流程、部署检查 |
| 格式化 | 4 | JSON/YAML/Markdown 格式校验 |
| 工具集成 | 5 | Git 操作、Docker 编排、数据库迁移 |

---

## 下一篇预告

下篇我们回到 `settings.local.json` 的 `permissions` 字段，深入探索 Claude Code 的安全模型——权限白名单的精确写法、MCP 工具的授权粒度、以及如何在"安全"和"便利"之间找到平衡点。

---

**你写的第一个 Skill 是什么？用了哪种设计模式？评论区分享。**