Meta Skill Writer — 教你写 Skill 的 Skill

当用户提出「帮我写个 skill」时，按以下方法论创建。

核心原则

1. 渐进式加载优先

• description：只放触发条件，不放教程。让 Agent 一眼判断"这个场景该不该用我"
• SKILL.md：放操作流程和规则。描述工作步骤，不是原理说明
• references/：放长文档、API 说明、示例。只在执行中需要时才读
• scripts/：放确定性的机械操作。不要用脚本做"AI 文本处理"，要用脚本做"格式校验/API调用/文件操作"
• 不需要一开始就把所有内容塞进 prompt

2. 角色定位清晰

• 一个 skill 只做一类任务
• 如果发现 SKILL.md 里在写"如果是场景A就…如果是场景B就…"，说明该拆成两个 skill 了

3. 可测试

• 每个 skill 都应该能用 openclaw skills check 验证依赖
• 关键的脚本路径应该能在命令行独立测试

工作流

Step 1：需求分析

和用户确认三个问题：

1. 用户说什么话时应该触发这个 skill？ → 这就是 future description
2. 这个 skill 处理完交付什么？ → 确定输出（文件？消息？数据？）
3. 它的上游输入和下游依赖是什么？ → API？本地工具？用户手动提供？

Step 2：结构设计

按以下规则决定目录结构：

最小集（大部分场景够用）：

skill-name/
├── SKILL.md          # 必需。核心说明书
├── scripts/          # 可选。确定性脚本
├── references/       # 可选。长文档/参考
├── examples/         # 可选。输入输出样例
└── evals/            # 可选。最小评测集

什么时候加 scripts/：

• 有重复的格式化/校验/转换操作
• 有外部 API 调用
• 操作顺序固定、参数明确、不依赖 AI 判断

什么时候加 references/：

• API 文档太长，放 SKILL.md 里会冲淡流程
• 有 checklist、示例、模板需要按需读取
• 有业务背景知识但并非每次都需要

什么时候加 examples/：

• 输出格式复杂，Agent 容易跑偏
• 同一个任务有多种正确结果的风格，需要有参考对照
• 边界情况（如空输入、错误输入）的预期输出不好描述
• 好的做法：放 1-3 个好例子 + 1 个坏例子，标明为什么好/坏

什么时候加 evals/：

• skill 有核心路径不能倒退（改了某处不能把原本会做的做坏）
• 有多个脚本需要联动验证
• 需要定期回归检查的场景
• 最小评测集：5-10 个输入 + 预期输出，每次迭代后跑一遍

什么时候不该加：

• 不需要把"用 Python 的话要怎么装依赖"写成脚本（模型已经知道）
• 不需要把明显的常识性知识塞进 references
• examples/ 和 evals/ 不是越大越好——精选 3-5 个高质量样例胜过 20 个凑数的

Step 3：写 SKILL.md

使用 references/skill-template.md 作为起点，填充以下内容：

frontmatter 必须包含：

---
name: skill-name           # 简短，kebab-case
version: "1.0.0"           # 语义化版本
description: "一句话说明"   # 关键！Agent 靠这个判断是否触发
---

description 写作原则：

• 直接用用户会说的话 — 不用加"当用户说…时"这种包装。用户会说"帮我评估一下这个skill"，那 description 就写「帮我评估一下这个 skill」，一字不改
• 只写触发条件，不写功能描述
• 不写步骤细节（那些放正文）
• 中英文均可，但要一致

对比案例（multi-agent-skill-evaluator 的真实迭代）：

正文结构：

# Skill 名称 — 一句话用途
(如果超出 2 行，说明 skill 范围太大)

## 首次设置（如果没有就是空）
## 工作流（核心步骤，从触发到交付）
## 输出格式（如果有）
## 注意事项

正文写作原则：

• 写操作步骤，不是写原理
• 每步说明"做什么"和"为什么"，但不写"怎么实现"（模型知道怎么实现）
• 边界条件写清楚："什么情况下停下来问用户"、"什么情况下继续"
• 错误处理写清楚："失败了怎么办"、"预期时长"

Step 4：创建脚本（如果需要）

脚本的原则：

• 可独立测试：bash script.sh "input" 应该能跑通
• 参数化：不要硬编码路径，用参数或环境变量
• 有错误处理：检查输入、检查依赖、检查返回值
• 有回退策略：主方案失败时尝试次方案

Step 5：自检清单

完成前逐项自查：

• description 是否直接用用户会说的话？
• SKILL.md 把"怎么做"写清楚了吗？AI 按步骤执行会不会卡住？
• 有没有把常识性知识写进 skill（模型不需要教）？
• 是否有测试过关键脚本路径？
• 输出格式是否明确？
• 失败场景是否说明？
• 依赖是否在 metadata 中声明？
• examples/ 和 evals/ 如果加了，内容是否精选而非凑数？

Step 6：可选——让 skill-evaluator 评估

创建完成后，可以调用 multi-agent-skill-evaluator 对新建的 skill 进行质量评估，获取改进建议。

常见反模式