skill-forge

用途

skill-forge 用于把一份已完成的 .skill-plan.yaml（或 .skill-plan.patched.yaml）编译成最终、符合 schema 的技能包（skill bundle）。它只负责生成，不负责发现：发现与规划由 skill-wizard 和 skill-plan 完成，skill-forge 内部不运行发现式访谈循环。

主要能力

• 以计划为唯一事实来源：.skill-plan.yaml 驱动所有生成决策。
• 仅生成契约：发现发生在 skill-wizard + skill-plan 阶段。
• 人工写入门：写入文件前始终要求显式确认。
• 草稿质量门：在合成前强制执行反模式与清晰度检查。
• 按 tier 输出不同结构：
  • Tier A：仅 SKILL.md（示例以内联 ## Example 形式存在）。
  • Tier B：SKILL.md + scripts/* + references/Example.md + references/*（当 context=yes 时）。
  • Tier C：SKILL.md 编排器 + references/Example.md + 各阶段 playbook 的 references/*.md。

使用方式（状态机）

0. 导入计划（必需）

自动触发：用户提供包含 .skill-plan.yaml 的路径，或要求从计划进行 forge。

操作：

• 在 skill 目录下运行 Bash scripts/import-plan.sh <plan-path>。
• 将 JSON 输出解析为工作状态（intent、tier、mechanism、target path、notes）。
• 处理非零退出码：
  • 1：计划文件缺失或不可读 → 要求提供有效路径。
  • 2：YAML 解析或结构错误 → 要求用户修复计划 YAML。
  • 3：缺少必需键 → 列出缺失键，要求用户通过 skill-plan/skill-refine 修补。
  • 4：completed 不为 true → 停止并要求用户先完成规划。
• 打印摘要：intent、scope、mechanism、tier、target path。
• 询问：Proceed to generate bundle? [yes/no]

1. 蓝图（验证）

• 根据计划字段（tier、mechanism、context_assets、workflow_notes）构建文件计划。
• 展示预计目录树 + 3 行 SKILL.md 预览。
• 请求确认。
• 若用户请求结构性变更（intent/scope/mechanism/context/path/workflow），不要内联访谈或修改计划。
• 指示用户通过 skill-refine 修补 .skill-plan.yaml（或重跑 skill-wizard/skill-plan），然后重跑 skill-forge。

2. 草稿（质量门）

• 以 assets/skill-template.md 为骨架起草 SKILL.md 指令。
• 根据 tier 与 mechanism 生成 scripts/、references/ 和 assets/ 的草稿文件。
• 对照下方反模式扫描草稿。向用户打印违规项。在内部修复。
• 条件推送规则：若条件墙无法压平，将逻辑推入 scripts/。用一次脚本调用替换 SKILL.md 步骤。在 draft_changes[] 中记录变更。
• 对照下方清晰度清单运行草稿。打印剩余失败项。在内部修复。
• 展示修正后的草稿。询问：Write to disk or adjust?
• 若请求的调整改变计划语义，停止并引导用户在上游修补计划。

3. 示例（校准）

• 生成端到端示例，展示生成技能在使用中的行为。
• 放置规则：Tier A → 作为 ## Example 内嵌于 SKILL.md。Tier B/C → 写入 references/Example.md。
• 内容规则：
  • 使用与 frontmatter 触发条件匹配的真实用户输入。
  • 走查生成 SKILL.md 中的每个工作流步骤。
  • 至少包含一个边界情况或修正（例如条件推送、验证失败）。
  • 以生成技能产出的具体输出结尾。
  • 添加 ### Agent-calibration notes 块（语气、节奏、输出形态）。
• 询问：Example looks good? [yes / no / edit]
• 在计划中持久化 example_placed + example_generated: true。

4. 写入（合成）

• 检查目标路径。冲突时警告。覆盖需显式 yes。
• 通过 Write 工具写入文件：先 SKILL.md，然后按 tier 写入 scripts/、references/（Tier B/C 含 Example.md）、assets/。
• 更新 .skill-plan.yaml 元数据：
  • 追加来自质量门的 draft_changes[]
  • 设置 example_placed
  • 设置 example_generated: true
  • 保持 completed: true
• 输出：Skill forged.

反模式（起草时强制执行）

• ❌ "Consider doing X" → 替换为 "Do X."
• ❌ "You might want to..." → 删除。硬性要求或丢弃。
• ❌ "This helps with..." → 上下文。移至 description frontmatter。
• ❌ 长散文段落（>3 句）→ 拆为项目符号。
• ❌ "First, second, finally" → 与编号列表冗余。删除序数词。
• ❌ 嵌套列表超过 2 层 → 压平或拆分到参考文件。
• ❌ "See below/above" → 使用文件路径或章节标题。
• ❌ 条件墙 → 将逻辑推入 scripts/。用脚本调用替换步骤。
• ❌ 在正文重复 frontmatter → 删除。description 只属于 YAML。
• ❌ 开放式任务 → 添加具体范围约束。

清晰度清单（写入前须全部通过）

• 每条指令为祈使动词开头（"Read"、"Generate"、"Call"）。
• 无指令超过 2 行。
• 无模糊词（consider、might、perhaps、optionally、you could）。
• 步骤有序。若顺序无关，标注为 "parallel"。
• 每步单一动词。无复合动作。
• 文件引用使用相对 skill 根的相对路径。
• 无无范围约束的模糊指令。
• 每步声明输出预期（"produce JSON with keys..."）。
• 指令总行数 <= 80（为 frontmatter + 标题预留 20）。
• 若步骤需要外部工具，工具名明确。

参考文件

• assets/skill-template.md — 生成技能的 SKILL.md 骨架。
• assets/plan-template.yaml — .skill-plan.yaml 输入契约。
• references/Examples.md — 生成阶段的提示示例。

适用场景

当一份已完成的 .skill-plan.yaml（或 .skill-plan.patched.yaml）已就绪，需要通过 /skill-forge 生成或更新符合规范的技能包时使用。

限制

• 不在 skill-forge 内运行发现式访谈循环。
• 结构性变更需在上游通过 skill-refine 或 skill-wizard/skill-plan 修补计划后重跑。
• 写入文件前必须获得显式人工确认。
• 覆盖已有文件需显式 yes。
• 关于收费、价格、平台支持范围等信息暂未提供。