10 个 SKILL.md 模板——让 AI 按你的套路干活

写一次，永久生效。Codex 和 Claude Code 都认这个标准——这是 2026 年最被低估的功能。

3 个月前我每次让 AI 帮我写周报，都要把指令复制粘贴一遍：

"看 git log，按 feature/bugfix/refactor 分类..."
"突出业务价值，不要太技术..."
"用老板能看懂的话..."

20 行 prompt，写一次 5 分钟，每周写一次。

直到我发现了 Skills。

把那 20 行存成一个 周报.md，放在 ~/.claude/skills/weekly-report/SKILL.md。从此每周说一句"写周报"，AI 自动调用，输出比我自己写得还规整。

这就是 Skills——写一遍、永久生效的 AI 套路。Codex 2025-12 上线、Claude Code 同时支持、Cursor / Gemini CLI / GitHub Copilot 都认这个开放标准。

这篇把 3 个月调教下来的 10 个高频 SKILL.md 模板 拆给你看，拿走就能用。

一、Skills 到底是什么

一句话：Skills 是一份 SKILL.md 文件，告诉 AI"什么情况下、按什么步骤、产出什么格式"。AI 自动识别任务、自动调用、自动执行。

和它最容易搞混的三个东西：

你以为是	实际上是	关键区别
Prompt 模板	自动触发的 Prompt	不用每次贴 · AI 自己识别
Slash Command	默认包含 Slash + 还能自动调用	两种触发方式
Agent / Subagent	给 Agent 的指令包	Skill 是"怎么做"·Agent 是"谁来做"

Skills 的三大杀手锏：

跨工具兼容：Anthropic 和 OpenAI 都认同一份 SKILL.md 格式。一份文件，Claude Code / Codex / Cursor / Gemini CLI / Copilot 全都能用。
渐进式加载：AI 启动时只读 name + description，决定要用时才加载完整内容。100 个 skill 不会撑爆 context。
可以带脚本：scripts/ 子目录里放 Python / Bash，AI 直接执行。把不能用 LLM 做的事（精确计算、API 调用）交给脚本。

二、SKILL.md 最小模板 + 文件结构

最小模板（5 行就能跑）：

---
name: commit-writer
description: 根据 git 暂存区生成符合 Conventional Commits 规范的提交信息。当用户说"写 commit"、"提交信息"或在 git commit 前自动调用。
---

1. 跑 `git diff --staged` 看暂存改动
2. 判断主要类型：feat / fix / refactor / docs / chore / test
3. 输出格式：`type(scope): description`（祈使句，<72 字符）
4. 复杂改动加一段正文说明 why（不写 what）
5. 破坏性变更加 `BREAKING CHANGE:` 脚注

完整文件结构（按需扩展）：

weekly-report/
├── SKILL.md   # 必需：YAML frontmatter + 指令
├── scripts/   # 可选：可执行脚本
│    └── pull_git_log.sh
├── references/ # 可选：长文档（按需加载）
│    └── 业务术语表.md
└── assets/    # 可选：模板文件
     └── template.md

两个工具的存放路径：

范围	Claude Code	Codex
项目级	.claude/skills/<name>/SKILL.md	.agents/skills/<name>/SKILL.md
全局级	~/.claude/skills/<name>/SKILL.md	~/.codex/skills/<name>/SKILL.md

省事技巧：写一次同时给两个工具用，做个软链接：
ln -s ~/.codex/skills/weekly-report ~/.claude/skills/weekly-report

三、写好 description 的 4 条铁律

description 是 Skills 唯一被 AI 当作"判断要不要用"的依据。AI 装了 100 个 skill，它不会读完所有 SKILL.md 才决定用哪个——它只看 name + description。

description 写不好，再牛的 skill 也是死的。

铁律 1：用第三人称，不要"我"或"你"

description 会被注入到 AI 的系统提示里，第二人称会让 AI 错位。

❌ 错：帮你/我写一份周报...
✓ 对：生成基于 git log 的周报，按业务价值排序，输出 markdown 格式。

铁律 2：前面放触发词，后面放使用场景

description 经常会被截断，关键词必须在前面。

❌ 错：一个非常智能的工具，能帮你处理各种任务，特别是当你需要审计 SQL 时...
✓ 对：审计 SQL 注入和性能问题。当用户要求 review SQL、检查查询性能、或在 PR 涉及 .sql 文件时调用。

铁律 3：明确说"什么时候用"和"什么时候不用"

❌ 模糊：处理数据库相关任务（AI 不知道是不是该用）
✓ 清晰：仅在用户要写新 SQL 查询时使用 · 不用于查看现有表结构（用 schema-viewer skill）

铁律 4：写 3-5 个真实触发例句

放在 SKILL.md 正文开头：

## 触发示例
- "帮我审一下这个查询"
- "看看这个 SQL 有没有注入风险"
- "这个 join 怎么优化"

这是给 AI 看的"语义锚点"。没有例句，AI 经常该用的时候不用、不该用的时候乱用。

四、10 个高频 SKILL.md 模板

下面 10 个都是我自己在用的，按使用频率排序。拿走，改个名字，今晚就能跑。

1️⃣ commit-writer——自动写 Conventional Commits

---
name: commit-writer
description: 根据 git 暂存改动生成符合 Conventional Commits 的提交信息。
---
1. git diff --staged 读暂存改动
2. 主类型：feat / fix / refactor / docs / chore / test / perf
3. scope 从改动文件推断（auth / api / ui / db）
4. 主标题：type(scope): 描述，祈使句，<72 字符
5. 复杂改动加 body 说明 why
6. 破坏性变更：BREAKING CHANGE: ...

2️⃣ weekly-report——基于 git log 写周报

---
name: weekly-report
description: 看最近一周的 git log 写给老板看的周报。
---
1. git log --since="last monday" --author=$(git config user.name)
2. 按 feature / bugfix / refactor / docs / 杂活分类
3. 每个项目用一句话突出业务价值（不写技术细节）
4. 末尾加"下周计划"3 条，从 TODO / FIXME 注释里提取
5. 输出 markdown，结构：本周完成 / 数据 / 下周计划

3️⃣ pr-review——按团队规范审 PR

---
name: pr-review
description: 按团队规范 review PR · 检查命名 / 错误处理 / 测试覆盖 / 破坏性变更。
---
1. git diff main..HEAD --stat 看改动范围
2. git diff main..HEAD 看实际改动
3. 按四个维度逐条审：命名 / 错误路径 / 测试 / 新增测试
4. 分三档输出：BLOCKER / SUGGEST / NIT
5. 每条带文件路径和行号

4️⃣ prd-writer——写产品需求文档

---
name: prd-writer
description: 基于一段需求描述写完整 PRD · 背景 / 用户故事 / 功能 / 数据模型 / 验收。
---
1. 追问 3 个缺失信息：用户是谁 / 主场景 / 成功指标
2. 输出结构：
  - 背景与目标（200 字内）
  - 用户故事（As a / I want / So that）
  - 功能列表（P0 / P1 / P2）
  - 数据模型 + 验收标准（Given / When / Then）
3. 末尾加风险与依赖

5️⃣ research-three-step——调研三步走

---
name: research-three-step
description: 写技术 / 产品 / 选型调研报告 · 调研→大纲→成稿，每步落盘。
---
第一步：候选 3-5 个 + 优劣对比 → research.md
第二步：背景 / 矩阵 / 推荐 / 路径 / 风险 → outline.md
第三步：按 outline 展开，具体数字 + 场景 → proposal.md
重要：每步必须落盘，下一步基于文件继续

6️⃣ stop-slop——去 AI 味儿润色

---
name: stop-slop
description: 把 AI 写的文章润色成人话 · 去废话 / 拆长句 / 改主动语态。
---
必须删：在当今 / 随着 X 的发展 / 总而言之 / 让我们一起 / 无疑
必须改：长句拆短句 · 排比改例子 · 被动改主动 · 抽象改具体
风格：一段≤4 行 · 每 2-3 段插例子 · 结尾不总结

7️⃣ sql-audit——SQL 注入与性能审计

---
name: sql-audit
description: 审计 SQL 注入和性能。PR 涉及 .sql 文件或 ORM 查询时调用。
---
必查 5 项：
1. 字符串拼接 SQL → 注入
2. SELECT * → 列爆炸
3. WHERE 缺索引 → 全表扫
4. JOIN 无条件 → 笛卡尔积
5. 循环里 SQL → N+1
输出：风险等级 + 文件:行 + 修复建议 + EXPLAIN 清单

8️⃣ bug-postmortem——线上事故复盘

---
name: bug-postmortem
description: 写线上事故 / 重大 Bug 的复盘报告。
---
1. 时间线（带时间戳）
2. 影响范围（用户 / 订单 / 钱）
3. 根因（5 个 why 法 · 至少挖 5 层）
4. 直接原因 vs 系统原因
5. 改进项（短期 / 中期 / 长期 · 带 owner + deadline）
6. 教训（不许写"加强测试"）

9️⃣ ship-it——一键发布流程

---
name: ship-it
description: 完整发布流程：测试→构建→打 tag→push→开 PR。
---
1. pnpm test 全过才继续
2. pnpm build 无 warning 才继续
3. 按 semver 升版本（feat→minor / fix→patch）
4. 更新 CHANGELOG.md
5. git tag + push
6. gh pr create 开 PR
绝对不许：跳测试 / --no-verify / 改测试让通过

🔟 daily-cleanup——每日代码体检

---
name: daily-cleanup
description: 找出当前分支的代码异味 · 未使用 import / dead code / TODO。
---
1. unimported（未使用 import）
2. unused-vars（未使用变量 / 函数）
3. 超过 3 个月没动过的 TODO
4. 注释和代码不一致
5. console.log / debugger 调试残留
不自动改，只列清单 + 自动修复命令

五、进阶——scripts / references / 嵌套

10 个模板看完，你已经能写 90% 的 skill 了。剩下 10% 是这三个进阶玩法。

玩法 1：scripts/ 把脏活让脚本干

LLM 不擅长精确计算、文件批处理、API 调用。让脚本干。SKILL.md 里指挥："跑 scripts/pull_git_log.sh 拉本周 git log，把脚本输出按 feature/bugfix/refactor 分类。"

脚本输出的 token 数远少于让 AI 自己解析整段 git log。省 token 又准。

玩法 2：references/ 长文档按需加载

技术文档、术语表、品牌指南放 references/，只有 AI 真需要时才加载。SKILL.md 里这样写：

## 资源
- 写品牌内容前，先读 [品牌术语表](./references/品牌术语表.md)
- 调性把握用 [调性规范](./references/调性规范.md)
- 仿写老文案风格参考 [历史样本](./references/历史样本.md)

AI 只在需要时加载，平时这些字根本不进 context。

玩法 3：嵌套调用 / 组合 skill

一个 skill 里调用另一个 skill：

---
name: ship-feature
description: 完整 feature 上线流程
---
1. 用 pr-review skill 自审一遍
2. 用 commit-writer skill 写最后的 commit
3. 用 ship-it skill 发布
4. 用 weekly-report skill 写进本周周报

把单点 skill 组合成 workflow。比写一个大的 monolithic skill 好维护 10 倍。

🎯 Skill Creator——用 AI 写 AI 的套路

Anthropic 官方 meta-skill：/plugin install skill-creator@anthropic-agent-skills。它会问你 3-5 个问题（触发词、输入、输出、约束），然后生成完整 skill 目录。第一个 skill 不会写没关系，让 AI 教你写。

六、Claude vs Codex Skills 横向对比

维度	Claude Code	Codex
上线时间	2025-11	2025-12
项目级路径	.claude/skills/	.agents/skills/
全局级路径	~/.claude/skills/	~/.codex/skills/
Slash 调用	`/skill-name`	`$skill-name`
隐式调用	✓ 按 description	✓ 按 description
Skills 列表预算	系统提示开头	~2% context（≤8000 字符）
动态注入	!`git diff` 反引号	通过 scripts/ 调用
子代理隔离	`context: fork` + agent	默认共享上下文
官方目录	anthropics/skills	openai/skills

互通秘籍：name + description + markdown body 这三件套是跨工具开放标准。任何只用这三件套的 skill，两个工具都能跑。Claude 特有的 context: fork、Codex 特有的 scripts: 字段，对方会忽略不报错。

七、5 个常见坑

坑 1：description 写成"营销文案"，AI 根本不调用

❌ "一个超级强大的 SQL 助手，能帮你处理各种数据库相关的复杂场景"
✓ "审计 SQL 注入和性能。当用户要求 review SQL、PR 涉及 .sql 文件、或修改 ORM 查询时调用。"

触发词 + 使用场景，开门见山。不是广告词。

坑 2：SKILL.md 塞太满，单文件超过 5000 字

AI 加载 SKILL.md 是全量加载。一个 1 万字的 SKILL.md 比 prompt 还贵。

✓ SKILL.md 只放核心步骤（<1000 字），长文档塞 references/ 按需加载。

坑 3：装了 100 个 skill，开头 list 撑爆

Codex 给 skills 列表分配 ~2% context（≤8000 字符）。装的 skill 太多会被截断，靠后的 skill 永远不会被调用。

✓ 每个 description 控制 80 字符内 · 项目级 skill 只装当前项目用得到的。

坑 4：name 用了大写或下划线，skill 直接不加载

name 字段只能是小写字母、数字、连字符。
Weekly_Report ❌ 不加载 · weekly-report ✓ 正确
myorg/weekly ❌ 静默失败 · weekly-report-v2 ✓ 版本号用连字符

坑 5：来历不明的 skill 直接装，等于把家门钥匙给陌生人

Skill 可以调用工具、执行脚本、读写文件。装一个恶意 skill 等于让 AI 帮坏人干坏事。

✓ 装前必读 SKILL.md 全文 + scripts/ 每个脚本。陌生 skill 比陌生 npm 包还危险。

写在最后

你每次重复贴的 prompt，都该变成一个 SKILL.md。

3 个月前我跟身边人都说"Skills 没什么用，就是个 prompt 模板"。

3 个月后我所有重复活儿都进了 skill 库，每周省下来的时间够多看一场电影。

Skills 真正的价值不是"省个 prompt"，是这三件事：

沉淀经验：脑子里的"我每次都这么干"变成可以被复用、被分享、被版本管理的文件
跨工具迁移：今天用 Codex 明天换 Claude，skill 库整个搬过去就行
教 AI 你的套路：每个老板都该有一套 skill 集，让 AI 按自己的风格干活，而不是按通用风格

10 个模板拿走
今晚就写第一个

从 commit-writer 开始最简单 · 5 分钟见效

有用才会用 · 会用才有用

—— 有用AI · 2026.05.26