writing-your-skills

name	writing-your-skills
description	帮助用户撰写高质量的 Agent Skill。当用户想要创建新 Skill、改进现有 Skill、或询问如何写 Skill 时使用。涵盖命名规范、description 写法、正文结构、自由度把控、渐进式披露、工作流设计、常见避坑等。触发词：写skill、创建skill、新建技能、skill怎么写、skill best practices、编写skill、改进skill、skill模板。

Writing Your Skills

帮助用户从零开始撰写一个高质量 Agent Skill，或改进已有 Skill。

核心理念

Skill 是把"老员工脑子里的规矩"写进 SKILL.md，让 Agent 在合适时按需加载。

记住三个原则：

• 主干短 — 主文件 ≤500 行，细节拆到 reference
• 任务小 — 一个 Skill 只解决一类问题，不怕小，怕边界不清
• 有闭环 — 每个流程都有验证点，不能让 Agent 一路跑到底

---

工作流

阶段 1：明确需求

在动笔前，先和用户确认以下问题：

1. 这个 Skill 解决什么问题？（用一句话说清）
2. 什么场景下会用到？（用户会说什么话触发它？）
3. 谁是使用者？（开发者、数据分析师、运维？）
4. 操作风险有多高？（会改数据/发请求/删文件吗？）

这是最关键的阶段。如果边界没定清楚，后面一定会越写越大。

如果用户想写一个"万能助手"类 Skill，引导他们拆分成多个小 Skill。参见 references/splitting-skills.md。

阶段 2：起草元数据

帮用户写出精准的 name 和 description。

name 要求：

• 最多 64 字符，只含小写字母、数字、连字符
• 不含 XML 标签和保留字（anthropic、claude）
• 优先用动名词形式（verb-ing）：processing-pdfs、reviewing-code

description 要写清三件事：

1. 这个 Skill 做什么
2. 在什么场景下用
3. 带上用户可能说的触发词

# ✅ 好的范例
description: 从 PDF 文件中提取文本和表格、填充表单、合并文档。在处理 PDF 文件或用户提及 PDF、表单、文档提取时使用。

# ❌ 太模糊
description: 帮助处理文档。

详细指南参考 references/naming-guide.md。

阶段 3：设计目录结构

按复杂度选择结构（遵循渐进式披露三层模型）：

复杂度	结构	适用场景
简单	仅 SKILL.md	单一任务，≤500 行正文
中等	SKILL.md + references/	有细节需要按需加载
复杂	SKILL.md + references/ + scripts/ + assets/	有脚本、模板、多种参考资料

# 推荐结构（中等复杂度）
skill-name/
├── SKILL.md          # 主入口：流程、规则、边界
├── references/       # 细节按需加载
│   ├── advanced.md
│   └── checklist.md
└── assets/           # 模板和静态文件
    └── template.md

关键原则：只做一级引用。SKILL.md → reference.md，不要写成 SKILL.md → advanced.md → details.md 这种多级跳。

阶段 4：撰写正文

正文是 Agent 要读的"操作手册"。记住：

上下文窗口是公共资源。每写一段都问自己：Agent 真的需要这段吗？这是私有知识还是通用常识？值不值得占上下文？

正文要素（按优先级排）：

1. 执行步骤 — 按什么顺序做
2. 边界规则 — 哪些情况不要做
3. 默认方案 — 正常走哪条路
4. 例外处理 — 什么情况换方案
5. 验证检查 — 做完怎么确认没跑偏
6. 失败兜底 — 失败了怎么办

具体写法参考：

• 正文起草指南：references/body-writing.md
• 常见设计模式：references/patterns.md

阶段 5：设定自由度

根据任务风险决定自由度（高风险 = 低自由度）：

自由度	适合场景	写法
低	数据库迁移、部署、删文件——出错代价高	给精确命令，明确"不要改"
中	有固定模板但允许调整	给模板、参数和边界
高	代码审查、方案评估——需要判断取舍	给检查方向，不写死步骤

凡是会改数据、发请求、部署、迁移、删除文件的任务，自由度收紧； 凡是分析、评审、总结、生成草稿类任务，可以适当放开。

阶段 6：添加验证与反馈循环

复杂任务必须要有验证点，防止 Agent 跳过步骤直接说"做完了"。

两种核心机制：

1. 阶段检查点 — 关键步骤后强制验证
2. 完成检查清单 — 收尾前逐项确认

## Verification Checklist

Before marking work complete:

- [ ] 每条规则都写成了具体可验证的动作
- [ ] 每个例外情况都给了兜底方案
- [ ] 正文没有解释通用常识
- [ ] 术语全文统一
- [ ] 主文件不超过 500 行

阶段 7：对照清单审核

用 references/review-checklist.md 逐项对照，确保 Skill 质量。

主要检查维度：

• description 是否写清了"做什么 + 什么时候用"
• 正文是否只放了 Agent 需要的信息
• 主文件是否控制在 500 行以内
• 高风险操作是否写死了步骤
• 复杂任务是否有验证点
• 术语是否全文统一
• 是否给了默认方案而非让 Agent 自选

---

常见问题速查

用户想把 Skill 写得太全

引导拆分："这个 Skill 管代码审查、又管数据库排查、又管线上故障，Agent 拿到一个 GC 日志会先纠结该用哪部分。不如拆成三个：jvm-metrics-analyzer、distributed-trace-finder、k8s-pod-event-viewer。"

详见 references/splitting-skills.md。

正文写成了 README

README 写背景、安装、特点。Skill 正文只写：什么时候用、按什么顺序做、哪些情况别做、失败怎么兜底。

给 Agent 太多选择

不要列四个 PDF 库让 Agent 自己选。给默认方案 + 例外条件：

# ✅
默认使用 pdfplumber 提取文本。
如果是扫描版 PDF，需要 OCR，再改用 pdf2image + pytesseract。

# ❌
你可以使用 pypdf、pdfplumber、PyMuPDF 或 pdf2image 处理 PDF。

术语不统一

同一个概念全文只用一个词。前面写"API 端点"，后面就不要写成"URL"或"API 路由"。

---

模板

完整 Skill 骨架模板见 assets/skill-template.md。可直接复制改写成用户需要的 Skill。