| name | skill-creator |
| description | 当用户说"创建一个 skill""新 skill""修改 skill""skill 怎么写"或需要新建/修改 skill 文件夹时使用。 skill 编写规范引导：文件夹结构、description 250字符触发、Gotchas 坑点、渐进式披露。关键词：skill、创建、编写、规范。
|
skill-creator (Skill 编写规范)
触发词
创建 skill、新建 skill、写个 skill、修改 skill、skill 怎么写、skill 规范、skill 设计
概述
引导创建或修改 skill 文件夹。skill 不是"一份写了步骤的 markdown"，而是装备齐全的工具箱。本 skill 按 .agents/rules/skill_design.md 规范引导填写，确保新 skill 能被正确触发、内容高信号、不踩反模式。
前置条件
- 已读
.agents/rules/skill_design.md（skill 设计规范）
- 已读
.agents/rules/coding_principles.md（编码准则，skill 中的代码示例需遵守）
工作流
第 1 步：明确 skill 定位
先问清楚这几个问题（一次问一个，给推荐答案）：
- 这个 skill 解决什么问题？ — 一句话说清
- 用户什么时候会需要它？ — 列出触发场景（用户会说什么话、遇到什么情况）
- 属于 9 类里的哪一类？ — 库和API参考 / 产品验证 / 数据查询 / 业务自动化 / 代码脚手架 / 代码质量审查 / CI/CD部署 / Runbook排障 / 基础设施运维
- 如果横跨多类，拆成多个 skill
- 如果只能做一类，优先做验证类（Anthropic 实测对 agent 输出质量提升最明显）
- 是否已有类似 skill？ — 读
_index.md 检查，避免重复
第 2 步：决定文件夹结构
.agents/skills/{skill-name}/
├── SKILL.md # 必需：何时用 + 工作流 + 坑点 + 规则
├── references/ # 按需：正文放不下的细节（API 参数、排查手册）
├── scripts/ # 按需：现成可执行脚本（冒烟测试、模板生成）
└── assets/ # 按需：输出模板（release_note、config 等）
- 只有 SKILL.md 必需，其余按需添加
- 不要预防性创建空目录 — 真有内容了再建
- 子文件不一股脑塞给 agent，而是 SKILL.md 指引"需要时自己去翻"
第 3 步：写 description（≤250 字符，决定触发）
description 是 agent 决定用不用这个 skill 的唯一依据。agent 没读过正文。
写法：
- ❌ 人类视角摘要："帮助处理数据库相关工作"
- ✅ 模型视角触发条件："当用户要写数据库迁移、修改表结构、或遇到 migration 报错时使用"
模板：
当用户要 [具体触发场景] 时使用。覆盖关键词：[关键词1]、[关键词2]、[关键词3]。
硬约束：≤250 字符，超出被截断。装太多 skill 会互相挤占清单预算 — 贵精不贵多。
第 4 步：写正文（SKILL.md）
按 .agents/rules/skill_design.md 第五章的模板填写。正文黄金法则：只写 agent 推断不出来的，删掉它本来就会的。
该写的（信号强）：
- 坑点清单 Gotchas：agent 靠读代码永远推断不出来、只有踩过坑才知道的事
- 例："subscriptions 表是只追加不修改的，要找的记录是 version 最大的那条"
- 例："这个字段在 API 网关叫 @request_id，在计费服务叫 trace_id，是同一个值"
- "不要做"清单：冲着 agent 默认行为纠偏
- 具体可执行的工作流：每步写清"做什么 + 用什么工具/命令"
- 硬性规则：用"必须/绝不/禁止"，不用"建议/可以考虑"
不该写的（纯噪声）：
- 显而易见的事："写完代码后要运行测试" — agent 本来就会
- 教程式解释：那是 references/ 的职责
- 临时状态：那是记忆的职责
别把 agent 锁死：步骤不要写得太死。给信息，不要锁死走法。agent 对指令服从度高，写太死遇到没覆盖的情况会僵在轨道上。
第 5 步：持续攒坑点
每次 agent 用这个 skill 又栽进新坑，回头把坑补进 Gotchas。skill 越用越准。
第 6 步：更新索引
新增/修改 skill 后必须同步更新 .agents/skills/_index.md：
- 添加/修改条目：name + description + 所属类别
- 如果是删除 skill，从索引中移除
第 7 步：验证触发
测试触发词能否匹配：
- 模拟用户说法，看 agent 是否能从
_index.md 找到这个 skill
- 如果触发不稳，调整 description 中的关键词
SKILL.md 模板
---
name: my-skill
description: >
当用户要 [具体触发场景] 时使用。覆盖关键词：[关键词1]、[关键词2]。
（≤250 字符，写给模型看的触发条件，不是给人看的摘要）
---
# My Skill (my_skill_id)
## 触发词
关键词1、关键词2、关键词3
## 概述
一句话说清这个 skill 干什么、什么时候该用。
## 前置条件
- 依赖什么环境/工具/文件
## 工作流
1. [步骤1]：具体操作 + 对应的工具/命令
2. [步骤2]：...
3. [步骤3]：...
## 坑点清单（Gotchas）★ 含金量最高
- [agent 推断不出来的坑 1]
- [agent 推断不出来的坑 2]
## 关键规则
- 必须/绝不/禁止 的硬性约束
## 不要做
- [冲着 agent 默认行为纠偏的"不要"清单]
## 输入/输出
- 输入：input/xxx/
- 输出：output/xxx/
## 参考（按需查阅）
- references/api.md — 详细 API 参数
- scripts/smoke_test.sh — 冒烟测试
9 类 skill 分类参考
来自 Anthropic 内部几百个 skill 的归类。最好的 skill 干干净净落在某一类里。
| 类别 | 干什么 | 例子 |
|---|
| 库和 API 参考 | 教 agent 正确用某个库/CLI | 内部计费库的边界情况和坑 |
| 产品验证 | 教 agent 怎么测试自己写的代码 | 无头浏览器跑注册流程并逐步断言 |
| 数据查询分析 | 连接数据和监控系统 | 该 join 哪些表看转化漏斗 |
| 业务流程自动化 | 把重复工作流压成一条命令 | 聚合工单和 PR 生成站会日报 |
| 代码脚手架 | 按团队规范生成样板代码 | 新建预接好鉴权和日志的应用 |
| 代码质量与审查 | 强制执行代码质量 | 全新视角子 agent 做对抗式审查 |
| CI/CD 与部署 | 拉取推送部署代码 | 盯 PR 重试不稳定 CI、解决冲突 |
| Runbook 排障手册 | 从报警症状做多工具排查 | 给请求 ID 把所有系统日志拉齐 |
| 基础设施运维 | 带护栏的例行维护 | 清理孤儿资源前先发确认 |
反模式（8 个，必须避免）
- 写教程：把"你可以这样做"改成"这样做"
- 模糊描述：把"适当处理错误"改成"出错重试 3 次，仍失败则跳过并记录到 errors.json"
- 遗漏安全规则：涉及删除/发布/部署必须写确认流程
- 硬编码路径：用占位符或读配置，不写死绝对路径
- 忘更新索引：新增/修改 skill 后必须同步
_index.md
- description 写成摘要：要写触发条件，不是功能介绍
- 正文写 agent 本来就会的：只写增量信息，删掉显而易见的内容
- 步骤锁死：给信息，不要锁死走法
坑点清单（Gotchas）
- description 超 250 字符：清单里只显示前 250 字符，超的被截断，触发关键词丢失导致 skill 永远不被调用
- 触发词和 description 不一致：触发词章节写了"打包"，但 description 里没有"打包"关键词，agent 看不到触发词章节，只看 description
- skill 横跨多类：一个 skill 想同时做"验证"和"部署"，agent 不知道何时该用，拆成两个
- 预防性创建空目录：先建 references/ scripts/ assets/ 但没内容，下次 agent 读到空目录困惑
- Gotchas 写显而易见的事：如"修改代码后要测试" — 这是噪声不是坑点，删掉
- 工作流太死板：把每一步都写死，agent 遇到没覆盖的情况僵在轨道上 — 给信息不锁走法
高阶玩法（按需）
- 记忆：skill 在
.agents/memory/ 下维护执行历史（如日报 skill 记录上次推送内容，下次只报增量）
- 脚本：把取数/清洗/校验等底层活封装成
scripts/ 里的函数，agent 只管编排，不重复造轮子
- 首次使用引导：需用户配置的 skill，存
assets/config.json，首次运行检测配置缺失则主动询问用户并写入
关键规则
- 必须先读
.agents/rules/skill_design.md 再开始
- description 必须**≤250 字符且写触发条件**而非摘要
- 必须同步更新
_index.md
- 必须只写 agent 推断不出来的内容，删掉显而易见的
- 绝不横跨多个类别 — 一个 skill 干一件事
不要做
- 不要写教程式解释 — 那是 references/ 的职责
- 不要硬编码路径 — 用占位符或读配置
- 不要把临时状态写进 skill — 那是记忆的职责
- 不要预防性创建空目录 — 真有内容了再建
- 不要把步骤写得太死 — 给信息，不锁走法
输入/输出
- 输入：用户的 skill 需求描述
- 输出：
.agents/skills/{skill-name}/SKILL.md（+ 按需的 references/scripts/assets）+ 更新 _index.md
依赖
| 依赖 | 路径 | 说明 |
|---|
| Skill 设计规范 | .agents/rules/skill_design.md | 必读，定义所有规范 |
| 编码准则 | .agents/rules/coding_principles.md | skill 中的代码示例需遵守 |
| Skill 目录 | .agents/skills/ | skill 文件夹存放处 |
| Skill 索引 | .agents/skills/_index.md | 新建/修改 skill 后必须同步 |
