| name | skill-writer |
| description | 编写和更新 skill 的规范、流程和最佳实践。Use when creating, reviewing, or improving a skill folder, SKILL.md, or bundled skill resources. |
Skill 的定义
Skill 是一个让 agent 在特定任务中获得稳定工作流、领域知识、工具脚本或素材的操作手册资料包。它遵循"渐进式披露"原则：
name 和 description：默认进入上下文，用于判断是否触发 skill。SKILL.md 正文：仅在 skill 触发后读取，放核心流程和使用指引。- 其他资源：按需读取或执行，放详细参考、脚本、模板、素材。
创建或更新流程
- 明确这个 skill 要支持的真实用户请求，至少确认核心任务和触发场景。
- 判断哪些信息必须放在
SKILL.md，哪些应拆到资源文件。
- 创建或更新 skill 文件夹，文件夹名必须等于 skill name。
- 编写
SKILL.md：先写准确的 frontmatter，再写短而可执行的正文。
- 测试新增脚本或关键资源，确保可直接运行。
- 运行校验脚本；如果失败，修复后重新校验。
- [可选]对复杂 skill 做真实任务 forward-testing，并根据结果迭代。
文件结构
每个 skill 单独成一个文件夹：
<skill-name>/
├── SKILL.md # 必需
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：详细参考资料
└── assets/ # 可选：模板、图片、字体、样例素材
只创建实际需要的资源目录。其他目录仅在任务明确需要时添加。
SKILL.md 规范
SKILL.md 由 YAML frontmatter 和 Markdown 正文组成。
Frontmatter
只包含 name 和 description：
---
name: skill-name
description: 说明这个 skill 做什么，以及在什么用户请求或任务上下文中使用。
---
name：使用小写字母、数字和连字符；建议 64 个字符以内；必须与文件夹名一致。description：这是触发机制。必须同时说明功能和使用场景，因为正文只有触发后才会被读取。
Description 写法
好的 description 应该能让 agent 只靠它判断是否触发 skill：
- 先说明能力：这个 skill 帮 agent 做什么。
- 再说明场景：什么用户请求、文件类型、工作流或任务上下文应该使用它。
- 使用具体触发词，避免 “适用于各种场景” 这类宽泛描述。
- 只放必要细节；执行步骤放正文。
- 只有常见且严重的误触发场景，才写不应使用的边界。
Markdown 正文
正文只写 agent 执行任务时必须知道的内容：
- 使用命令式表达，像操作手册一样说明步骤。
- 保留核心流程、关键约束、资源导航和少量高价值示例。
- 把低频、过长、变体化的内容拆到资源文件。
- 如果存在资源文件，明确说明它们是什么，以及何时读取或执行。
- 避免泛泛解释 skill 是什么；假设 agent 已理解基础概念。
- 需要特别关注的要求使用粗体或
<IMPORTANT>...</IMPORTANT> 标识。
资源分层判断
SKILL.md：放每次使用都需要的核心流程、约束和资源索引。references/：放详细文档、领域知识、API 说明、长示例和变体规则。scripts/：放重复、易错、需要确定性的操作。新增脚本必须实际运行测试。assets/：放最终输出会使用的模板、图片、字体、样例素材等。
避免把同一信息同时放在 SKILL.md 和资源文件中。详细信息一旦拆出去，就在 SKILL.md 中保留清晰入口。
验证
完成创建或修改后运行校验脚本：
scripts/quick_validate.py <path/to/skill-folder>
如果当前环境没有该脚本，说明无法运行该项验证，并用可用方式检查 frontmatter、文件结构和资源引用。
新增或修改 scripts/ 下的脚本时，必须实际执行代表性用例。复杂 skill 应使用真实任务做 forward-testing：只给测试 agent skill 路径和任务，不泄漏预期答案或修复思路。
