MarcelLeon Skill Creator
用于“创建 -> 评测 -> 迭代 -> 优化触发”的完整工作流技能。
先对齐用户阶段
先判断用户当前在哪个阶段，再补齐下一步：
- 还在定义需求：先澄清目标、触发场景、输出标准
- 已有草稿：直接进入测试与迭代
- 已有多轮结果：重点做诊断与重构，而不是重写一遍
如果用户明确说“不需要完整评测流程”，可降级为轻量协作；否则默认走标准闭环。
与用户沟通风格
根据用户熟悉度调节术语密度：
- 可直接使用：
evaluation、benchmark - 对
JSON、assertion等术语，若用户没有明显技术背景，先用一句话解释再使用
目标是“专业但不堆术语”。
一、创建 Skill
1) Capture Intent（先抽取上下文再提问）
若当前对话里已包含可复用流程，先从历史中提取：
- 用了哪些工具
- 步骤顺序是什么
- 用户纠正过哪些点
- 输入/输出格式长什么样
然后确认以下 4 点：
- 这个 skill 要让 Claude 具体做成什么事？
- 触发条件是什么（用户会怎么说）？
- 预期输出格式是什么？
- 是否需要测试用例？
默认建议：
- 可客观验证任务（文件转换、结构化提取、固定流程）建议有测试
- 主观创作任务（文风、设计偏好）可以先不做形式化断言
2) Interview & Research
主动补齐：
- 边界/异常情况
- 输入输出样例
- 依赖与运行环境
- 成功标准
测试提示词（eval prompts）在这一步完成前不要急着写。
3) 编写 SKILL.md
至少落实：
namedescription（这是触发核心，必须写清“做什么 + 何时用”）- 正文流程（必要步骤、工具用法、结果标准）
description 要稍偏“主动触发”，避免 under-trigger。
示例（表达方式）：
- 弱：
用于生成仪表盘 - 强：
用于生成仪表盘。凡是用户提到 dashboard、指标可视化、看板、业务监控、数据展示，即便没说“仪表盘”，也应触发此技能。
4) Skill 结构原则
skill-name/
├── SKILL.md (required)
└── optional resources
├── scripts/
├── references/
└── assets/
渐进披露：
- 元数据（name/description）总在上下文
SKILL.md触发后加载（建议 <500 行，必要时可超）scripts/references/assets按需读取
设计要点：
- 若接近 500 行，把变体细节下沉到
references/ SKILL.md中要明确指向这些参考文件，告诉模型何时读- 参考文件 >300 行建议提供目录
5) 安全与可预期
- 不得包含恶意代码、提权、未授权访问、数据外传流程
- Skill 的真实行为应与描述一致，不做“隐式意图”
6) 编写风格
- 以祈使句描述动作
- 少用机械化
MUST，多解释“为什么要这样做” - 指令应可泛化，不要对少量样例过拟合
二、测试用例与评测闭环
写完草稿后，先准备 2-3 条真实用户风格测试提示词，并与用户确认。
把测试集存到 evals/evals.json（先写 prompts，断言可后补）：
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "User's task prompt",
"expected_output": "Description of expected result",
"files": []
}
]
}
完整 schema 见 references/schemas.md。
强制顺序：不要中途停
不要使用 /skill-test 或其他测试 skill；按下面连续完成。
工作目录规范：
- 在 skill 同级创建
<skill-name>-workspace/ - 迭代分目录：
iteration-1/,iteration-2/ - 每条 eval 单独目录：
eval-0/,eval-1/ - 仅在需要时创建目录，不要一次性全部建完
Step 1：同一轮同时启动 with-skill 与 baseline
每个测试用例同轮启动两路：
with_skill- baseline
基线策略：
- 新建 skill：baseline =
without_skill - 改造现有 skill：baseline = 旧版本快照（
cp -r <skill-path> <workspace>/skill-snapshot/）
每个 eval 写 eval_metadata.json（此时 assertions 可先空）：
{
"eval_id": 0,
"eval_name": "descriptive-name-here",
"prompt": "The user's task prompt",
"assertions": []
}
Step 2：运行期间补断言
不要干等任务结束。并行完成：
- 草拟可客观验证的 assertions
- 向用户解释每条断言检验什么
- 更新
eval_metadata.json与evals/evals.json
主观任务不强行量化；以人工评审为主。
Step 3：任务完成即记录时延/Token
子任务完成通知里会出现 total_tokens 与 duration_ms，这是唯一可靠来源。必须立即写入各运行目录 timing.json：
{
"total_tokens": 84852,
"duration_ms": 23332,
"total_duration_seconds": 23.3
}
Step 4：评分、聚合、分析、展示
评分（grading）
逐 run 生成grading.json。数组字段必须是text、passed、evidence（viewer 依赖这些字段名）。聚合 benchmark
在skills/skill-creator/目录运行：
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
生成 benchmark.json 与 benchmark.md。
- 分析（analyst pass）
结合agents/analyzer.md检查：
- 非区分性断言（各方案都通过）
- 高方差/可能 flaky 的评测
- 时延与 token 的权衡
- 生成评审 viewer（必须）
使用官方脚本，不要自造 HTML：
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
<workspace>/iteration-N \
--skill-name "my-skill" \
--benchmark <workspace>/iteration-N/benchmark.json \
> /dev/null 2>&1 &
VIEWER_PID=$!
如果是第 2 轮及以后，加 --previous-workspace <workspace>/iteration-<N-1>。
无图形/远程环境：使用 --static <output_path> 生成静态 HTML。用户点击提交后会下载 feedback.json，再拷回 workspace。
- 通知用户评审入口
明确告诉用户：
Outputs看样例输出并填写反馈Benchmark看量化对比
Step 5：读取反馈并收尾
用户评审完成后读取 feedback.json，优先处理有明确投诉的用例；空反馈视为通过。
结束后关闭 viewer：
kill $VIEWER_PID 2>/dev/null
三、迭代改进（核心）
改进时遵守 4 条：
- 从反馈提炼可泛化规则，不要只修当前样例
- 保持 prompt 精简，删掉“高成本低收益”指令
- 解释为什么，让模型理解意图而不是死记规则
- 发现重复劳动就产品化：多次重复写出的 helper 脚本应沉淀到
scripts/
迭代循环：
- 修改 skill
- 在
iteration-(N+1)重新跑全部测试与 baseline - 用
--previous-workspace再开 viewer - 用户评审
- 再迭代
停止条件：
- 用户明确满意
- 反馈基本为空
- 连续迭代无显著增益
四、进阶：盲测对比（可选）
需要更严格比较两个版本时：
- 读
agents/comparator.md - 让独立 agent 在不知来源前提下比较输出
- 再用
agents/analyzer.md分析胜因
多数场景下，人审 + benchmark 已够用。
五、Description 触发优化
SKILL.md frontmatter 的 description 决定触发概率。建议在 skill 稳定后再做。
Step 1：构造触发评测集
准备 20 条 query（建议 8-10 条应触发 + 8-10 条不应触发）：
[
{"query": "the user prompt", "should_trigger": true},
{"query": "another prompt", "should_trigger": false}
]
质量标准：
- 贴近真实用户输入（路径、字段名、上下文、错别字/口语都可）
- 负例要“近邻混淆”，不是明显无关句子
- 多做边界样例，少做教科书样例
Step 2：让用户审阅 query
用模板 assets/eval_review.html：
- 读取模板
- 替换占位符：
__EVAL_DATA_PLACEHOLDER____SKILL_NAME_PLACEHOLDER____SKILL_DESCRIPTION_PLACEHOLDER__
- 写到临时 HTML（如
/tmp/eval_review_<skill>.html）并打开 - 用户导出
eval_set.json - 从
~/Downloads读取最新导出文件
Step 3：跑自动优化循环
后台执行：
python -m scripts.run_loop \
--eval-set <path-to-trigger-eval.json> \
--skill-path <path-to-skill> \
--model <model-id-powering-this-session> \
--max-iterations 5 \
--verbose
要点：
- 训练/测试拆分：60%/40%
- 每条 query 跑 3 次统计触发率
- 结果用 test score 选
best_description，避免过拟合 train - 描述优化脚本通过当前会话的
claude -p执行，不需要单独配置ANTHROPIC_API_KEY
执行期间需定期向用户同步迭代进度与得分变化。
Step 4：应用结果
- 用
best_description回写 SKILL.md - 向用户展示 before/after 与评分变化
触发机制补充
技能只会在 Claude 认为“有必要调用 skill”时触发。简单一步请求即使语义匹配，也可能不触发。
因此触发评测 query 要足够“复杂且值得调用 skill”。
六、打包交付（可选）
如环境支持，执行：
python -m scripts.package_skill <path/to/skill-folder>
然后返回 .skill 产物路径给用户。
七、Claude.ai 适配
在 Claude.ai（无子任务并发）场景：
- 测试用例改为串行执行
- 可跳过 baseline 对照
- 无法开浏览器时，在对话里直接展示结果并收集反馈
- 定量 benchmark 可降级，优先做人审
run_loop.py/run_eval.py依赖 CLI 能力，受环境限制时可跳过- 若目标是“更新已有 skill”而非新建：保持原 skill 名称不变；若安装路径只读，先复制到
/tmp/<skill-name>/再编辑与打包
八、Cowork 适配
在 Cowork 场景：
- 可使用子任务并行（严重超时时可降级串行）
- 无显示环境时必须使用
generate_review.py --static - 反馈文件通过下载获得后，放回 workspace 继续下一轮
run_loop.py/run_eval.py通常可用，建议放在技能收敛后执行- 不要忘记：先生成 viewer 给人审，再做你自己的深入分析
- 如果是更新已有 skill，同样遵循 Claude.ai 章节中的“保留原名称 + 先复制到可写目录”规则
九、参考文件
agents/：
agents/grader.md：断言评分规范agents/comparator.md：盲测比较流程agents/analyzer.md：benchmark 诊断方法
references/：
references/schemas.md：evals.json、grading.json、benchmark.json等结构定义
十、核心闭环（再强调）
- 明确 skill 目标
- 起草或修改 skill
- 运行测试（with-skill + baseline）
- 产出 benchmark + viewer，先让用户评审
- 依据反馈迭代
- 收敛后再做 description 优化与打包