skill-authoring

name	skill-authoring
description	当你要编写一份可用的 Agent Skill（把领域经验外化成按需加载的指令）时使用；当需要把个人/团队经验沉淀为可复用、可版本控制、可分享的能力单元时使用。不适用于系统提示词的整体设计（见 prompt-engineering），聚焦 SKILL.md 的编写方法。

Skill 编写方法（Skill Authoring）

角色与读者

面向需要把经验写成 Skill 的开发者（元能力：用 Skill 创造 Skill）。本 Skill 服务的目标：让一份 Skill 成为"新员工遇到某类任务时的操作手册"——遇到什么任务用它、按什么顺序行动、哪些情况停下来确认、什么结果算完成。核心认识：一份实用的 Skill 不应只是背景知识或成功对话的摘要，而应是可执行的行动指南。

核心原则（配正例/反例）

1. SKILL.md 结构：YAML frontmatter + 渐进式披露三层

   • frontmatter：name（小写字母/数字/连字符，匹配目录名）+ description（路由条件，见下）。
   • 三层：元数据（name+description，常驻）→ 核心流程（SKILL.md 正文，按需加载）→ 子文档/脚本（选择性深入）。
   • description 是路由决策关键：写法像路由条件而非功能介绍，明确"何时使用/何时不使用"边界 + 典型反例。"何时该用我"比"我能做什么"重要得多。

2. Skill 四部分（宝玉《图解 Skill》）

   • 角色与读者：服务谁、面向什么任务、输出标准。
   • 核心原则：只保留 3-5 条最重要判断，配正例反例。
   • 禁止清单：高频错误、越权动作、易误解表达，写清合法例外。
   • 参考资料：术语表、模板、范文、子文档。
   • 规则尽量写成"作用域 + 动作 + 例外 + 验证方式"，避免堆成越来越长的禁用词表。

3. 写作型 Skill 的迭代法

   • 从 3-5 篇满意原创开始，让 Agent 归纳生成二十行初版，再处理真实任务，作者逐句改稿。
   • 原文与修改稿的差异比抽象说"更自然一点"更有信息量：告诉 Agent 哪些词被删、哪些长句被拆、哪些地方补事实。
   • 把反复出现的改动整理回 Skill，每条规则保留正例、反例、适用范围。

4. Skill 可捆绑代码工具和模板文件

   • 如 PPT Skill 可含模板和解析脚本。Skill 的价值不仅在于上下文管理，更在于为领域知识积累提供可持续路径（模块化、可独立开发/测试/版本控制/分享，类似 pip/npm 生态）。

5. 与模型厂商训练方法保持一致

   • 基础模型公司推行的 Agent 用法本质是它们专门训练过的模式，同一生态内模型天然最佳表现。选择 Skill 交互模式时与厂商训练方法保持一致。

执行流程（SOP 检查清单）

1. 写 frontmatter（name + description 路由条件）。
2. 写四部分（角色读者 / 核心原则 3-5 条配正反例 / 禁止清单写清例外 / 参考资料）。
3. 用真实任务检验：Skill 能否让"新员工"知道遇到什么任务用它、按什么顺序行动、什么算完成。
4. 迭代：从初版（短小可读）开始，用真实任务反馈补全规则。
5. 可捆绑代码工具/模板，独立版本控制。

禁止清单（写清合法例外）

• 禁止 description 写"我能做什么"而非"何时该用我"（宽泛描述导致路由失准）。例外：写路由条件 + 反例。
• 禁止把 Skill 写成背景知识或成功对话摘要（应是可执行行动指南）。例外：背景知识放参考资料。
• 禁止堆砌几十条规则（短小可读的初版比罗列几十条更适合迭代起点）。例外：核心原则 3-5 条，细节放子文档。
• 禁止规则写成抽象描述（"更自然一点"）。例外：配正例反例 + 适用范围。
• 禁止安装来源不明的第三方 Skill（Skill 内容是新的注入面）。例外：安装前审查内容（如同审查代码）。

参考资料

• 本书第 2.5 节《动态提示词与 Agent Skills》（渐进式披露、如何编写 Skill、Skills 位置、与工具关系）。
• 笔记 02-上下文工程.md 第 2.5 节。
• 宝玉《别再用提示词去 AI 味了，方向就是错的》；Anthropic "Agent Skills"。