用 Skills 辅助开发

Skill 是什么

Skill(Agent Skill) 是一份打包好的"操作手册":一个目录,核心是 SKILL.md,可附带脚本、模板、参考资料。它告诉 Agent 在某类任务上应该怎么做——团队的发布流程、代码评审清单、特定框架的最佳实践、内部系统的操作步骤。

.claude/skills/
└── deploy-checklist/
    ├── SKILL.md          # 必需:说明 + 步骤
    ├── scripts/
    │   └── preflight.sh  # 可选:可执行脚本
    └── references/
        └── rollback.md   # 可选:深入文档,按需再读

SKILL.md 的格式:

---
name: deploy-checklist
description: 部署生产环境前的检查与发布流程。当用户要求部署、发版、上线时使用。
---

# 部署流程

1. 运行 `scripts/preflight.sh`,全部通过才继续;
2. 确认 CHANGELOG 已更新;
3. `git tag` 按 `vX.Y.Z` 规范打标;
4. 回滚预案见 references/rollback.md。

为什么 Skills 是"上下文友好"的

Skills 的关键设计是渐进式披露(progressive disclosure),这让它和"把所有规范都塞进 CLAUDE.md"有本质区别:

层级	何时进入上下文	大小
1. name + description	会话开始就常驻	每个 Skill 仅几十 token
2. SKILL.md 正文	Agent 判断任务相关时才加载	几百~几千 token
3. 附带文件/脚本	正文引用、确实需要时才读取/执行	不设限

也就是说,你可以沉淀 50 个 Skill,常驻成本只有 50 条一句话的目录索引;而 CLAUDE.md 里的每个字都是每轮全量常驻的。经验法则:

• CLAUDE.md:少而精,只放"永远适用"的项目事实(构建命令、目录结构、硬性约定);
• Skills:放"特定场景才需要"的流程和知识(部署、迁移、性能排查、PDF 处理……)。

脚本是 Skills 的另一半威力:确定性的步骤写成脚本让 Agent 直接执行,比让模型每次"现场发挥"更可靠、更省 token。

在 Claude Code 中使用

• 存放位置:项目级 .claude/skills/<name>/SKILL.md(随仓库共享给团队)、用户级 ~/.claude/skills/(个人通用),也可通过插件(plugin)分发;
• 触发方式:两种——Agent 根据 description 自动判断调用;或用户显式输入 /<skill-name> 手动触发(即斜杠命令,自定义 slash command 与 skill 已是同一套机制);
• 编写要点:description 是唯一的"检索线索",要写清做什么 + 什么时候用("当用户要求部署、发版时使用"),否则 Agent 不知道何时该用它;
• 调试:如果 Skill 没被触发,先检查 description 是否含用户会说的关键词;claude skills list 可查看已加载的 Skills。

Codex 及其他 Agent 生态中对应的做法是 AGENTS.md + 可执行脚本/prompts 目录,思路一致:把流程性知识放在文件系统里按需取用,而不是常驻提示词。

适合做成 Skill 的场景

1. 重复的多步流程:发版、数据库迁移、生成周报——写一次,团队每个人的 Agent 都会做;
2. 有既定规范的产出:提交信息格式、PR 描述模板、组件脚手架;
3. 领域知识包:公司内部 API 的调用惯例、特定文件格式的处理(官方就内置了 pdf、docx、xlsx、pptx 等文档处理 Skills);
4. 带工具的工作流:SKILL.md 说明 + 配套脚本,例如"性能排查"Skill 附带火焰图采集脚本。

反模式

• ❌ 把整本风格指南贴进 SKILL.md 正文 → 应拆到 references/ 按需读;
• ❌ description 写得太笼统("辅助开发") → Agent 永远不会想起它;
• ❌ 一个 Skill 干十件事 → 拆小,一个 Skill 一个明确场景;
• ❌ 用 Skill 存放每轮都需要的硬约定 → 那是 CLAUDE.md 的职责。

下一步

不想从零写?看看社区验证过的第三方 Skill:Skills 推荐——治过度工程的 Ponytail、治"AI 味"前端的 ui-ux-pro-max 与 Impeccable。