Skills 技能扩展

Skill 是一段按需加载的指令包：平时不占上下文，只有当你的请求跟它相关时才被读进来。适合封装「每次都要按固定流程做」的事。

和 CLAUDE.md 的区别：

	CLAUDE.md	Skill
加载时机	每次会话都加载	相关时才加载
成本	常驻，乘以每一轮	只在用到时付一次
适合放	项目通用约定	特定任务的详细流程

规则 → CLAUDE.md；流程 → Skill。

目录结构

.claude/skills/
└── release/
    ├── SKILL.md          # 必需
    ├── checklist.md      # 可选，被 SKILL.md 引用
    └── scripts/
        └── bump.sh

个人级放 ~/.claude/skills/，项目级放 <项目根>/.claude/skills/。

SKILL.md 写法

---
name: release
description: 发布新版本。当用户说「发版」「release」「打 tag」「出个新版本」时使用。
---

# 发布流程

## 前置检查
1. `git status` 必须是干净的
2. 当前分支必须是 `main`
3. `pnpm test` 必须全绿

## 步骤
1. 读 `package.json` 里的当前版本
2. 按语义化版本递增（问用户是 patch / minor / major）
3. 更新 `CHANGELOG.md`，从上一个 tag 到 HEAD 的 commit 里提取变更
4. `git commit -m "chore: release vX.Y.Z"`
5. `git tag vX.Y.Z`
6. **停下来让用户确认后**再 `git push --follow-tags`

## 禁止
- 不要在没跑通测试的情况下发版
- 不要自动 push，必须等用户点头

description 是最重要的一行

模型靠 description 判断「这次要不要加载这个 skill」。

写「发布相关」→ 模型不知道什么时候算相关，可能永远不触发。 写「当用户说『发版』『release』『打 tag』时使用」→ 精准命中。

把用户可能说的原话写进去。

渐进式加载

SKILL.md 本身要短（建议 < 100 行），细节放到附属文件里，需要时让模型自己读：

---
name: db-migration
description: 数据库迁移。当用户要加表、加字段、改索引时使用。
---

# 数据库迁移

## 快速流程
1. 在 `migrations/` 下新建文件，命名 `YYYYMMDDHHMM_描述.sql`
2. 必须同时写 up 和 down
3. 跑 `make migrate-test` 在三种数据库上验证

## 详细规范
写 SQL 前**先读 `references/sql-compat.md`**——里面有 MySQL / PostgreSQL / SQLite 的
方言差异对照表和禁用特性清单。

这样：平时只加载这 15 行，真要写 SQL 时才把几百行的兼容表读进来。

内置可用的 Skill

Claude Code 自带一些 skill，直接用 / 触发。用 /help 或在交互模式里输入 / 看当前可用列表。

什么该做成 Skill

场景	适合吗
「发版流程」「上线检查单」	✅ 步骤固定，偶尔用
「生成 API 文档的格式规范」	✅ 细节多，不是每次都需要
「代码风格约定」	❌ 每次都要遵守 → 放 CLAUDE.md
「怎么跑测试」	❌ 高频 → 放 CLAUDE.md
「排查生产事故的 SOP」	✅ 长、结构化、低频

验证 Skill 是否被加载

在交互模式里直接问：

现在有哪些 skill 可用？

或者说一句触发词，观察它是否按 skill 里写的流程走。没触发的话，八成是 description 写得太抽象。

成本影响

Skill 的价值就是省钱：

• 一份 800 行的完整发布 SOP 如果塞进 CLAUDE.md，你每一轮对话都在为它付费
• 做成 Skill，一个月发一次版才加载一次

配合 Prompt Cache，效果更明显。

配套阅读

• CLAUDE.md 项目规范
• Subagents 子代理
• Hooks 钩子
• 成本优化策略