skill 的创建包含起草，测试，评估，改进的迭代训练，生产出高质量，可复用，能被Agent正确Agent正确触发的技能。

核心

三层加载机制

  • Level 1: 元数据（name+description）→ 永远在上下文中 (~100 词)
  • Level 2: SKILL.md 正文 → 触发时加载 (<500 行最佳)
  • Level 3: scripts/references/assets → 按需加载（无限制）

触发机制

Decription是触发机制，不能简单理解为简介

  1. Agent不会查询所有skill，只会根据可用的skill列表中的name和description来决定是否使用
  2. description必须“pushy”
  3. ❌ “How to build dashboards.”- ✅ “How to build dashboards. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics…”

迭代循环

起草 SKILL.md → 写 2-3 个测试 prompt → 并行跑（有skill vs 无skill）→ 用户评估 → 改 → 再跑

改进规则

泛化：不要过拟合到几个测试用例，要能处理百万级 prompt
精简：删除没用的部分，看 transcript 而非只看结果
解释：用 theory of mind，不要用全大写 MUST；LLM 聪明，能理解意图
复用：如果3 个测试用例都各自写了 create_docx.py，就该打包成 script

写作风格

  • ✅ ALWAYS use this exact template:（祈使句 + 给模板）
  • ❌ 全大写 MUST + 一堆禁令和 if-else（会让模型僵化）

测试用例的设计

  • 2-3 个真实用户会说的prompt（不是抽象的”格式化数据”）
  • 客观可验证 →适合断言（文件转换、数据抽取）
  • 主观输出（写作风格、设计）→ 用定性评估，不要硬塞断言

理解

评估执行的5步流程

  • Step 1: 同时启动 with-skill 和 baseline 两个 subagent（重要：必须同 turn 启动）
  • Step 2: 跑的过程中起草 assertions
  • Step 3: 捕获 timing data（total_tokens, duration_ms）— 仅一次机会
  • Step 4: 评分 → aggregate_benchmark → 启动 eval-viewer
  • Step 5: 读 feedback.json → 改进 → 下一轮 iteration

Workspace 组织结构

1
2
3
4
5
6
7
my-skill-workspace/
├── iteration-1/
│   ├── eval-0/with_skill/outputs/
│   ├── eval-0/without_skill/outputs/
│   ├── eval_metadata.json
│   └── benchmark.json
└── iteration-2/...

Description优化流程

  1. 生成 20 个 trigger query（10 should-trigger + 10 should-not-trigger）
  2. HTML 模板给用户审核
  3. run_loop.py 后台跑（60% train / 40% test，最多 5 轮）
  4. 用 best_description（按 test score 选，防过拟合）

了解

类别 内容 怎么用
命令 python -m scripts.aggregate_benchmark 跑评估时查
命令 python -m scripts.package_skill 打包时查
命令 python -m scripts.run_loop 优化 description 时查
路径 agents/grader.md agents/comparator.md agents/analyzer.md spawn 对应 subagent 时读
路径 references/schemas.md 写 evals.json / benchmark.json 时参考
路径 assets/eval_review.html description 优化时用
路径 eval-viewer/generate_review.py 启动 review viewer 用
字段名 grading.json 必须用 text/passed/evidence（viewer 依赖） 出错时查
标志 --static <output_path> 无显示环境时查
文件 LICENSE.txt 不用管