如何手搓一个 Skill：适配 Claude Code、Codex、WorkBuddy

AI 编程助手越来越能「干活」，但真正稳定复用的，往往不是某次聊天里的临场发挥，而是一份可发现、可加载、可迭代的技能包——Skill。

你不需要等官方插件，也不用先学复杂 SDK。本质就一件事：

建一个文件夹，写好 SKILL.md，放到各工具约定的目录里。

本文讲清楚：Skill 是什么、怎么手搓、怎么在三端落地、怎样写得让模型真的会用。

---

一、Skill 到底是什么？

可以把 Skill 理解成「给 Agent 的专项操作手册」：

传统 Prompt	Skill
每次对话重新粘贴	写一次，长期复用
容易丢细节	目录化：说明 + 模板 + 脚本
靠人记得提	靠 description 自动匹配触发
难协作	可进仓库，团队共享

一次完整的工作流大致是：

1. 安装：把 skill 目录放到约定路径（没有注册表、没有编译）
2. 发现：启动时只读 frontmatter 里的 name / description
3. 触发：用户说相关需求，或显式调用（如 /skill-name、$skill-name）
4. 执行：读入完整 SKILL.md，必要时再读引用文件 / 跑脚本

这就是常说的 渐进式披露（Progressive Disclosure）：先轻量索引，需要时再展开，避免把上下文窗口一次性塞满。

---

二、最小可运行形态：一个目录 + SKILL.md

my-skill/
├── SKILL.md          # 必填：元数据 + 指令
├── references/       # 可选：细则、对照表、规范
├── scripts/          # 可选：校验/转换脚本
└── assets/           # 可选：模板、样例文件

SKILL.md 固定两段结构：

---
name: commit-helper
description: 根据 git diff 生成规范提交说明。在用户提到提交、commit message、写提交信息时使用。
---

# Commit Helper

## 步骤
1. 查看暂存区与未提交改动
2. 用约定格式写标题与正文
3. 指出风险点（机密、破坏性操作等）

## 输出格式
feat(scope): 一句话说明

为什么改；影响范围（可选）

必填字段怎么写才「能被发现」

• name：小写、数字、连字符；尽量短、可念、可搜
  • 好：commit-helper、api-changelog
  • 差：helper、utils、tmp
• description：同时写清 做什么（WHAT） 和 何时用（WHEN）
  • 用第三人称，像给系统目录写摘要
  • 把用户常说的词写进去（触发词）

反例：

「帮助处理文档」——太空，模型不知道何时加载。

正例：

「从 PDF 提取文本与表格、合并页面。在用户提到 PDF、表单填写、文档抽取时使用。」

---

三、手搓流程：从想法到能用

Step 1：先钉死「任务边界」

动笔前只回答四个问题：

1. 这个 Skill 只解决哪一类事？
2. 成功标准是什么？（输出长什么样）
3. 哪些步骤容易翻车？（必须写进禁令/检查清单）
4. 是「个人全局」还是「项目共享」？

Skill 越大越容易变成第二套系统提示词。宁可拆成两个小 Skill，也不要做一个万能包。

Step 2：先写能跑的最小版

第一版只保留：

• frontmatter
• 3～7 步操作顺序
• 1 个输出模板
• 2～3 条硬约束（禁止事项）

等真实对话里翻车了，再补 references/ 和 scripts/。

Step 3：把「细则」挪出主文件

主文件建议控制在可读范围内（实务上尽量别膨胀到「小说长度」）。细则用链接方式挂出去：

## 需要时再读
- 字段对照：[references/field-map.md](references/field-map.md)
- 验收清单：[references/checklist.md](references/checklist.md)

原则：一层引用。别让 Agent 从 A 跳到 B 再跳到 C，读一半就丢。

Step 4：该脚本就脚本

凡是「格式必须一致 / 容易写错 / 可重复校验」的，优先给脚本，而不是让模型每次现场发明：

python scripts/validate.py ./output

在 SKILL.md 里写清楚：是 执行 这个脚本，还是 阅读 它当参考。

Step 5：用真实任务回归

至少测三种触发：

1. 隐式：只说业务诉求，不点名 skill
2. 显式：/skill-name 或 $skill-name（看工具习惯）
3. 边界：相近但不该触发的请求（看会不会误召）

把误召/漏召反馈回 description 和步骤文案——Skill 的调参，大半发生在这里。

---

四、三端怎么放？（目录不同，心智相同）

核心格式高度一致：目录 + SKILL.md。差别主要在「放哪儿、怎么唤起」。

1）Claude Code

常见放置：

范围	路径
个人全局	~/.claude/skills/<skill-name>/SKILL.md
当前仓库	.claude/skills/<skill-name>/SKILL.md

常见唤起：

• 自动：description 匹配当前对话
• 手动：/skill-name（目录名通常即命令名）

写作提示：指令用祈使句（「先读 X，再做 Y」），比客套话更稳。

2）OpenAI Codex

常见放置：

范围	路径
个人	~/.agents/skills/<skill-name>/（也可见到 ~/.codex/skills/ 一类约定，以你本机文档为准）
仓库	.agents/skills/<skill-name>/

Codex 同样靠 name + description 做发现；完整正文按需加载。
仓库里若还有 AGENTS.md，它更像「项目总规矩」；Skill 更像「可插拔专项流程」。两者互补，不要把所有细节都塞进一个文件。

常见唤起：对话里 $skill-name，或工具内的 skills 面板/命令。

3）WorkBuddy（及相近产品线）

WorkBuddy 一类助手同样采用「Skill = 目录 + SKILL.md」思路；仓库内常见落点类似：

• 项目级：工作区下的 skills 目录（具体名称以产品文档为准，常见是 .xxx/skills/）
• 也支持 frontmatter 里的可选字段，例如工具白名单、是否允许模型自动调用等

实用策略：

• 默认允许自动发现（靠 description）
• 对「危险/昂贵/必须人工确认」的流程，设为仅手动触发

---

五、一份 Skill，多端复用：推荐「单源 + 软链」

三端目录不同，但内容可以只有一份真源：

~/agent-skills/
└── commit-helper/
    ├── SKILL.md
    ├── references/
    └── scripts/

然后在各工具目录做符号链接（示意）：

# macOS / Linux 示意
ln -s ~/agent-skills/commit-helper ~/.claude/skills/commit-helper
ln -s ~/agent-skills/commit-helper ~/.agents/skills/commit-helper
# WorkBuddy / 其他工具：链到其文档规定的 skills 目录

Windows 可用开发者模式 / mklink /J 做目录联接。
这样你改一处，三端同步；也避免「Claude 版已经修了、Codex 版还是旧文案」。

若团队要进 Git：把真源放仓库（例如 skills/），各工具目录用相对路径软链或文档约定「启动前同步」，比复制三份更不容易漂移。

---

六、把 Skill 写「好用」的几条硬经验

1. 上下文很贵，废话很贵

默认假设：模型已经很强。
只写它不知道、且做错代价高的信息：你们的命名、验收闸门、禁止事项、输出模板。

2. 自由度要匹配任务脆弱度

任务类型	写法
风格类（文案、评审意见）	原则 + 样例即可
结构类（报告、变更说明）	给模板
高风险类（发布、迁移、批量改库）	逐步清单 + 脚本校验 + 明确停止条件

3. 先给默认路径，少给平行选项

差：

你可以用 A，也可以 B，也可以 C……

好：

默认用 A。仅当出现 X 情况时改用 B。

4. 术语只留一套

全文统一「提交说明 / 变更摘要 / PR 描述」之一，不要混用三个近义词，模型会跟着漂。

5. description 是产品入口，不是备注

很多「Skill 明明写了却从不触发」，根因都在 description：

• 缺触发词
• 写得太像内部黑话
• WHAT 有了、WHEN 没有

把它当成应用商店的一句话介绍来写。

---

七、可直接复制的脚手架

---
name: your-skill-name
description: （做什么）。在用户提到（关键词1 / 关键词2 / 场景）时使用。
---

# 标题

## 何时启用
- 场景 A
- 场景 B
- 不要用于：场景 C（防误召）

## 强制流程
1. …
2. …
3. …

## 输出模板
（贴上你希望每次都长成的样子）

## 验收清单
- [ ] …
- [ ] …

## 需要时再读
- [references/xxx.md](references/xxx.md)

## 脚本（如有）
- 校验：`python scripts/validate.py <path>`

---

八、上线前 10 分钟自检

• name 合法且好记
• description 含 WHAT + WHEN + 触发词
• 主文件短，细则外置
• 有输出模板或检查清单
• 禁止事项写清楚
• 路径用正斜杠相对路径（跨平台）
• 在目标工具目录放对位置
• 测过自动触发 + 手动触发 + 误触发
• 若多端使用：确认只有一份真源

---

结语

手搓 Skill 的门槛很低：Markdown 就够。难的是产品化——

• 边界清晰：一事一 Skill
• 发现准确：description 写成人话触发器
• 执行可靠：步骤、模板、脚本、闸门齐全
• 多端一致：单源维护，目录适配各工具

当你把团队里反复口述的「潜规则」落成 Skill，Agent 才真正从「会聊天」变成「会按你们的方式交付」。

从今天起，挑一个你每周至少说三遍的流程，手搓第一个 SKILL.md 吧。