skill-creator

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 定位

先问清楚这几个问题（一次问一个，给推荐答案）：

1. 这个 skill 解决什么问题？ — 一句话说清
2. 用户什么时候会需要它？ — 列出触发场景（用户会说什么话、遇到什么情况）
3. 属于 9 类里的哪一类？ — 库和API参考 / 产品验证 / 数据查询 / 业务自动化 / 代码脚手架 / 代码质量审查 / CI/CD部署 / Runbook排障 / 基础设施运维
   • 如果横跨多类，拆成多个 skill
   • 如果只能做一类，优先做验证类（Anthropic 实测对 agent 输出质量提升最明显）
4. 是否已有类似 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 步：验证触发

测试触发词能否匹配：

1. 模拟用户说法，看 agent 是否能从 _index.md 找到这个 skill
2. 如果触发不稳，调整 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 个，必须避免）

1. 写教程：把"你可以这样做"改成"这样做"
2. 模糊描述：把"适当处理错误"改成"出错重试 3 次，仍失败则跳过并记录到 errors.json"
3. 遗漏安全规则：涉及删除/发布/部署必须写确认流程
4. 硬编码路径：用占位符或读配置，不写死绝对路径
5. 忘更新索引：新增/修改 skill 后必须同步 _index.md
6. description 写成摘要：要写触发条件，不是功能介绍
7. 正文写 agent 本来就会的：只写增量信息，删掉显而易见的内容
8. 步骤锁死：给信息，不要锁死走法

坑点清单（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 后必须同步