Claude Code 自定义技能开发指南

概述

Claude Code 的 Skills（技能）系统允许开发者将重复性的工作流程、决策框架和操作规范编码为可复用的结构化指令。每个技能本质上是一份精心设计的 Markdown 文档，定义了一个特定场景下的"AI 行为规范"——什么时候激活、按照什么流程执行、输出什么格式。

这份笔记基于我在 myskills 仓库中实际开发的两个自定义技能，系统梳理 Skills 的设计理念和开发经验。

一、什么是 Claude Code Skill

核心概念

Skill 是一个包含 SKILL.md 文件的目录，通过 Markdown frontmatter 声明元信息，正文定义行为规范。安装后，用户通过斜杠命令（如 /workflow-recorder）即可激活。

myskills/
├── recording/
│   └── workflow-recorder/
│       ├── SKILL.md              ← 技能定义文件（核心）
│       └── templates/
│           └── report-template.md ← 辅助资源
└── maintenance/
    └── github-project-maintenance/
        └── SKILL.md

SKILL.md 的结构

每个 SKILL.md 由三部分组成：

技能的安装与使用

# 安装到 Claude Code 技能目录
Copy-Item -Path "recording/workflow-recorder" `
  -Destination "$env:USERPROFILE\.claude\skills\workflow-recorder" `
  -Recurse -Force

# 安装后在 Claude Code 中直接调用
/workflow-recorder

二、技能设计原则

通过开发两个技能，我总结出以下设计原则：

原则 1：决策树优于平铺描述

AI 需要明确的判断路径。用决策树代替长篇描述：

需要修改 GitHub 项目
├── 这是我自己的项目？
│   └── 是 → 流程 A：直接在 main 修改
└── 这是别人的项目？
    └── 是 → 流程 B：分支 → rebase → PR

这比"根据项目归属选择合适的流程"这种模糊指令有效得多。

原则 2：异常场景必须有退出路径

每个分支都要考虑失败情况。例如 github-project-maintenance 中，rebase 冲突章节提供了四种退出策略：

• 自动解决（规则明确时）
• 询问用户（不确定时）
• git rebase --abort（想放弃时）
• 改用 git merge（rebase 太痛苦时）

没有退出路径的流程 = 遇到问题就会卡死的流程。

原则 3：模板驱动输出

为 AI 提供精确的输出模板，而不是"生成一个报告"。workflow-recorder 的 report-template.md 定义了完整的 Markdown 结构——时间戳格式、章节层级、状态标记（✅/❌/🔄）。这让每次输出都保持一致。

原则 4：简洁记录，事后聚合

workflow-recorder 的核心设计理念是：

每条记录 2-5 行，不写日记。报告写到磁盘，不常驻上下文。

这避免了记录本身成为上下文的负担。详细的回顾和模式提取留给 continuous-learning-v2 等后续技能处理。

三、实战技能拆解

技能一：workflow-recorder（工作流程记录器）

解决的问题：在 Claude Code 协作中，操作步骤、关键决策和错误排查过程很容易在一次会话后就丢失。这个技能将隐性知识显性化。

四阶段工作流：

阶段一：开始记录     阶段二：持续记录      阶段三：手动补充      阶段四：生成报告
    │                    │                    │                    │
创建 reports/        每当完成操作/         用户说"决策:"        补充总结章节
目录和报告文件        做出决策/遇到         用户说"问题:"        检查格式一致性
写入报告头部          问题时自动追加        自动归类写入         呈现报告摘要

三大追踪维度：

最关键的细节：错误信息必须贴原文，不要自己总结。因为三个月后你搜索这个错误时，需要的是原始报错信息，不是总结。

技能二：github-project-maintenance（GitHub 项目维护）

解决的问题：每次给开源项目提 PR 都要回忆一遍 rebase → 冲突解决 → force-with-lease 的流程。这个技能将 Git 操作规范化为可执行的决策树。

两大核心场景：

分支命名规范：

冲突解决策略表（技能中最有价值的精华）：

这比 git 文档中的通用建议实用得多，因为它直接映射到具体场景。

四、技能的组织与分类

按功能类型分组

随着技能数量增长，按类型分组比平铺好：

myskills/
├── recording/         ← "记录与追踪"类
├── maintenance/       ← "维护与管理"类
├── development/       ← 未来可能添加
└── quality/           ← 未来可能添加

每个分类目录有自己的 README.md，说明该分类的定位和所含技能。

分类的维度

选择分类维度时，我考虑过：

• 按功能类型（记录/维护/开发/测试）→ ✅ 直观，易扩展
• 按使用频率（日常/偶尔/一次性的）→ ❌ 随时间变化，不稳定
• 按技术栈 → ❌ 很多技能是跨技术栈的

最终选择了功能类型分类，因为它稳定且符合"找技能"的心智模型。

五、技能开发的最佳实践

1. 从真实痛点出发

两个技能都来自实际使用中的摩擦：

• 经常忘记 rebase 的正确步骤 → github-project-maintenance
• 排查完 bug 后什么都不记得 → workflow-recorder

不要为了写技能而写技能。 最好的技能是你已经手动做了三次以上的重复流程。

2. 先写流程骨架，再补异常处理

github-project-maintenance 的开发顺序：

1. 先写出"一切正常"的流程（A.1 → A.3, B.1 → B.5）
2. 然后补充"出问题了怎么办"（B.4 冲突解决 + 三个异常场景）
3. 最后加"快速参考"卡片（方便 AI 快速定位）

3. 引用关系显式声明

在 SKILL.md 末尾标注相关技能：

## 相关技能
- `workflow-recorder` — 在维护过程中记录操作流程和关键决策
- `git-workflow` rules — Git 提交规范和工作流约定

这让 AI 知道何时该激活另一个技能，形成技能之间的协作网络。

4. 用实战报告验证技能设计

workflow-recorder 的 template 是否好用？看实际生成的报告：

reports/
├── workflow-2026-06-05-2228.md  ← myskills 仓库初始化的完整记录
└── workflow-2026-06-06-0042.md  ← github-project-maintenance 技能的开发记录

这两份报告本身就是 workflow-recorder 的"自举测试"——用这个技能记录它自己所在项目的开发过程。如果报告读起来有用，说明技能设计是对的。

六、技能与 Rules 的关系

Skills 和 Rules 是 Claude Code 配置体系的两个层级：

Skills 告诉你怎么做一件事，Rules 告诉你做任何事时要遵守什么标准。两者互补：

• Rules 定义"Commit 必须用 conventional commits 格式"
• Skills 定义"如何正确执行一次 rebase + 冲突解决 + 提交 PR 的完整流程"

关键经验

1. Skills 的核心价值在于决策树，不在于信息量。 一个 50 行的精准决策树比 500 行的平铺说明更有效。
2. 异常处理比正常流程更重要。 正常流程 AI 大概率能猜对，异常处理才是技能不可替代的地方。
3. 模板驱动输出一致性。 如果希望 AI 的输出有固定格式，给它一个 Markdown 模板比描述十句更有效。
4. 从三个以内的技能开始。 不要一上来就建复杂的分类体系。两个技能已经足够验证分类方案是否合理。
5. 用自己开发的技能记录开发过程。 自举测试是验证技能设计最诚实的方式。
6. Skills 是可以持续迭代的。 每次实际使用后发现不足，直接修改 SKILL.md，git push，就完成了升级。