skill-forge

Skill Forge

使用此技能创建、测试、改进、打包和维护 Claude Code 与 Codex 技能。

默认工作循环如下：

1. 明确技能的预期边界。
2. 起草或编辑 SKILL.md。
3. 创建贴近实际的评估提示词。
4. 运行该技能和适当的基准测试。
5. 评分、汇总，并向用户展示查看器。
6. 根据反馈改进并重复上述流程。
7. 可选：优化前置元数据中的描述并打包技能。

如果用户只想头脑风暴，请跳过评估，作为设计伙伴提供帮助。 如果用户已有草稿，请从验证、评估或迭代开始。

渐进式披露索引

仅阅读当前分支所需的参考文件：

• references/skill_authoring.md - 起草、审阅或大幅重构 SKILL.md 前阅读，尤其是正文可能接近 500 行，或现有技能知识正在缩短、重组、翻译或移至参考文件时。
• references/eval_workflow.md - 运行测试用例、基准测试、评分、生成查看器、盲测比较或根据反馈迭代前阅读。
• references/description_optimization.md - 优化或调试技能的触发描述前阅读。要求先阅读目标技能的 SKILL.md，提取「适用于」和「不适用于」的情形，然后与用户一起审阅触发评估。
• references/openai_yaml.md - 生成或审阅 Codex agents/openai.yaml 元数据前阅读。
• references/skill_creator_comparison.md - 更新平台假设或比较 skill-forge 与 Anthropic/OpenAI 创建流程前阅读。
• references/trigger_eval_boundaries.md - 更改触发评估的解析方式，或解读 Claude Code / Codex CLI 中出乎意料的触发结果前阅读。
• references/schemas.md - 编写或手动检查 evals.json、eval_metadata.json、grading.json 或 benchmark.json 前阅读。
• references/platform_notes.md - 在 Claude.ai、Cowork 或无头环境中运行时阅读。

agents/ 目录包含专用子 Agent 的指令：

• agents/grader.md - 如何根据输出评估预期结果。
• agents/comparator.md - 如何进行盲测 A/B 比较。
• agents/analyzer.md - 如何分析基准测试结果。

与用户沟通

Skill Forge 的使用者对编程的熟悉程度可能各不相同。请使用符合用户习惯的词汇。通常可以使用「评估」和「基准测试」等术语，而「JSON」和「预期结果」可能需要简短解释。

清楚说明权衡。在运行耗时较长的评估循环、更改触发行为或打包技能前，先征求确认。

创建或编辑技能

首先提取对话中已有的信息。如果用户说「把这个做成技能」，请先复用已观察到的工作流程、工具、修正、输入和输出，再提出更多问题。

明确以下几点：

1. 该技能应让 Agent 能够做什么？
2. 该技能应在何时触发？
3. 应生成什么输出？
4. 该技能应仅适用于 Claude、仅适用于 Codex，还是兼容两者？
5. 现在是否应添加评估？

起草时，请阅读 references/skill_authoring.md。至少应提供：

• name：稳定的技能标识符。
• description：触发边界。所有「何时使用」的指引都应写在此处。
• compatibility：可选要求，仅在有用时添加。
• 正文指令：持久有效的工作流程，以及指向随附资源的指引。

对于确实适用的情况，描述应直接且略带强调，因为技能可能触发不足。也要明确说明相近但不适用的情况，避免该技能接管普通的编码、文档或运维工作。

编辑 SKILL.md 后，请进行验证；如果存在 Codex 元数据，也请重新生成。

Python 环境设置

运行脚本前，请确保在 skill-forge 目录中准备好 Python 环境：

uv sync --group dev

每次调用脚本都使用 uv run。如果缺少 uv，请引导用户访问 https://docs.astral.sh/uv/。

验证技能

对于兼容 Codex 的技能，在生成或审核 agents/openai.yaml 前，请阅读 references/openai_yaml.md。

目标技能的 SKILL.md frontmatter 稳定后，生成 Codex UI 元数据：

uv run python -m scripts.generate_openai_yaml <skill-dir>

打包或发布前运行验证：

uv run python -m scripts.quick_validate <skill-dir>
uv run python -m scripts.quick_validate <skill-dir> --platform claude
uv run python -m scripts.quick_validate <skill-dir> --platform codex
uv run python -m scripts.quick_validate <skill-dir> --platform codex --strict-openai-yaml

对于 Claude Code 专用的 frontmatter 字段（如 disable-model-invocation、user-invocable 或 when_to_use），使用 --platform claude。对于 Codex 技能和 agents/openai.yaml，使用 --platform codex。发布 Codex 元数据前使用 --strict-openai-yaml；此选项要求包含 display_name、short_description 和 default_prompt，并会在 SKILL.md 变更后检测元数据是否过时。

评测和基准测试

运行评测前，请阅读 references/eval_workflow.md。

核心规则：

• 创建隔离的工作区，并向用户展示路径。
• 对每个测试用例，在同一轮中启动启用技能的运行和基线运行。
• 在工作区下为每项任务单独创建工作目录。
• 为每个测试用例编写 eval_metadata.json；新文件以 "expectations": [] 开始。
• 在运行进行期间起草预期结果。
• 收到运行通知时保存计时数据。
• 使用 agents/grader.md 评分。
• 使用 scripts.aggregate_benchmark 汇总。
• 使用 eval-viewer/generate_review.py 生成人工审核界面；不要编写自定义查看器 HTML。
• 再次修改技能前，先阅读用户反馈。

有关架构详情，请阅读 references/schemas.md。写入方必须输出 expectations；旧版 assertions 仅作为读取方的兼容别名。

改进技能

改进应以证据为依据，而不只是凭感觉：

• 对现有技能进行大型重构时，请在编辑前和最终验证前，按照 references/skill_authoring.md 执行保留检查。不要将“缩短”“整理”“改成英语”或“移至参考资料”视为可以丢弃会影响行为的技能知识。
• 根据用户反馈进行泛化，而不是过度拟合单个评测提示词。
• 输出结果出乎意料时，阅读对话记录。
• 删除会导致反复无效工作的指令。
• 如果多个评测都重新实现了相同的确定性辅助工具，请将辅助脚本打包。
• 进行有实质意义的修改后，重新运行评测工作流。

进行盲测 A/B 比较时，请阅读 agents/comparator.md 和 agents/analyzer.md。

描述优化

技能正文稳定后，提供触发条件优化。开始前请阅读 references/description_optimization.md。

最低工作流：

1. 阅读目标技能的 SKILL.md。
2. 提取 helps with 和 should not help with。
3. 起草应该触发和不应该触发的查询。
4. 使用 assets/eval_review.html 让用户审核查询集。
5. 使用正确的 CLI 运行 scripts.run_loop。
6. 应用 best_description，展示修改前后内容，并报告分数。

Claude Code 示例：

uv run 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

Codex CLI 示例：

uv run python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --cli codex \
  --max-iterations 5 \
  --verbose

优化循环不需要单独设置 Anthropic API 客户端。 解释 status: "error" 或 status: "not_run" 前，请阅读 references/trigger_eval_boundaries.md。

特定平台的分支

对于 Claude.ai、Cowork 和无头环境，在调整工作流前，请阅读 references/platform_notes.md。

简要说明：

• Claude.ai 没有子 Agent，因此请自行运行测试用例，跳过基线，并着重进行定性审核。
• Cowork 支持子 Agent，但可能缺少浏览器；请使用 eval-viewer/generate_review.py --static <output_path> 生成静态查看器。
• 描述优化需要 claude -p 或 codex exec；没有合适的 CLI 时请跳过。

打包并提交

如果有文件呈现工具可用，请打包最终技能：

uv run python -m scripts.package_skill <path/to/skill-folder>

否则，将生成的 .skill 路径返回给用户。

最终检查清单

• 在 frontmatter description 中清晰界定 Skill 的范围。
• SKILL.md 保持精简，并指向包含分支特定细节的参考资料。
• 明确列出 Claude 和 Codex 的验证路径。
• SKILL.md 更改后，重新生成 Codex 元数据。
• Evals、expectations、grading、benchmark 和 viewer 工件使用 references/schemas.md 中的架构。
• 打包前纳入用户反馈。