| 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：明确需求
在动笔前，先和用户确认以下问题：
- 这个 Skill 解决什么问题？（用一句话说清）
- 什么场景下会用到？（用户会说什么话触发它？）
- 谁是使用者？（开发者、数据分析师、运维？）
- 操作风险有多高？（会改数据/发请求/删文件吗？）
这是最关键的阶段。如果边界没定清楚，后面一定会越写越大。
如果用户想写一个"万能助手"类 Skill，引导他们拆分成多个小 Skill。参见 references/splitting-skills.md。
阶段 2：起草元数据
帮用户写出精准的 name 和 description。
name 要求：
- 最多 64 字符，只含小写字母、数字、连字符
- 不含 XML 标签和保留字（anthropic、claude）
- 优先用动名词形式（verb-ing）：
processing-pdfs、reviewing-code
description 要写清三件事：
- 这个 Skill 做什么
- 在什么场景下用
- 带上用户可能说的触发词
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 真的需要这段吗？这是私有知识还是通用常识？值不值得占上下文？
正文要素（按优先级排）：
- 执行步骤 — 按什么顺序做
- 边界规则 — 哪些情况不要做
- 默认方案 — 正常走哪条路
- 例外处理 — 什么情况换方案
- 验证检查 — 做完怎么确认没跑偏
- 失败兜底 — 失败了怎么办
具体写法参考：
阶段 5：设定自由度
根据任务风险决定自由度（高风险 = 低自由度）：
| 自由度 | 适合场景 | 写法 |
|---|
| 低 | 数据库迁移、部署、删文件——出错代价高 | 给精确命令，明确"不要改" |
| 中 | 有固定模板但允许调整 | 给模板、参数和边界 |
| 高 | 代码审查、方案评估——需要判断取舍 | 给检查方向，不写死步骤 |
凡是会改数据、发请求、部署、迁移、删除文件的任务，自由度收紧；
凡是分析、评审、总结、生成草稿类任务，可以适当放开。
阶段 6：添加验证与反馈循环
复杂任务必须要有验证点，防止 Agent 跳过步骤直接说"做完了"。
两种核心机制：
- 阶段检查点 — 关键步骤后强制验证
- 完成检查清单 — 收尾前逐项确认
## 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。
