skill-forge

Compile a completed .skill-plan.yaml into a final, schema-compliant skill bundle. Do not run discovery interview loops inside skill-forge.

Core Concepts

Plan as Source of Truth: .skill-plan.yaml drives all generation decisions.
Generation-Only Contract: Discovery happens in skill-wizard + skill-plan.
Human Write Gate: Always require explicit confirmation before writing files.
Draft Quality Gate: Enforce anti-pattern and clarity checks before synthesis.

Auto-trigger: User provides a path containing .skill-plan.yaml or asks to forge from plan.
Action:
1. Run Bash scripts/import-plan.sh <plan-path> from skill directory.
2. Parse JSON output into working state (intent, tier, mechanism, target path, notes).
3. Handle non-zero exits:
  - 1: plan file missing/unreadable → ask for valid path.
  - 2: YAML parse/shape error → ask user to repair plan YAML.
  - 3: required keys missing → list missing keys, ask user to patch via skill-plan/skill-refine.
  - 4: completed is not true → stop and ask user to complete planning first.
4. Print summary: intent, scope, mechanism, tier, target path.
5. Ask: Proceed to generate bundle? [yes/no]

Build file plan from plan fields (tier, mechanism, context_assets, workflow_notes).
Show projected directory tree + 3-line SKILL.md preview.
Ask confirmation.
If user requests structural changes (intent/scope/mechanism/context/path/workflow), do not interview or mutate plan inline.
- Instruct user to patch .skill-plan.yaml via skill-refine (or rerun skill-wizard/skill-plan), then rerun skill-forge.

Draft SKILL.md instructions using assets/skill-template.md as skeleton.
Generate draft files for scripts/, references/, and assets/ based on tier and mechanism.
Scan draft against anti-patterns below. Print violations to user. Fix internally.
Conditional push rule: If conditional wall cannot be flattened, push logic to scripts/. Replace SKILL.md step with one script call. Record change in draft_changes[].
Run draft against clarity checklist below. Print remaining failures. Fix internally.
Show corrected draft. Ask: Write to disk or adjust?
If requested adjustment changes plan semantics, stop and route user to patch plan upstream.

Generate end-to-end example showing generated skill behavior in use.
Placement rule: Tier A → embed as ## Example inside SKILL.md. Tier B/C → write to references/Example.md.
Content rules:
- Use realistic user input matching frontmatter triggers.
- Walk through each workflow step from generated SKILL.md.
- Include at least one edge case or correction (e.g., conditional push, validation failure).
- End with concrete output produced by the generated skill.
- Add ### Agent-calibration notes block (tone, pacing, output shape).
Ask: Example looks good? [yes / no / edit]
Persist example_placed + example_generated: true in plan.

Check target path. Warn on collision. Require explicit yes to overwrite.
Write files via Write tool: SKILL.md, then scripts/, references/ (including Example.md if Tier B/C), assets/ per tier.
Update .skill-plan.yaml metadata:
- append draft_changes[] from quality gate
- set example_placed
- set example_generated: true
- keep completed: true
Say: Skill forged.

❌ "Consider doing X" → Replace with "Do X."
❌ "You might want to..." → Remove. Hard requirement or drop.
❌ "This helps with..." → Context. Move to description frontmatter.
❌ Long prose paragraphs (>3 sentences) → Break to bullets.
❌ "First, second, finally" → Redundant with numbered list. Drop ordinals.
❌ Nested lists >2 levels deep → Flatten or split to reference file.
❌ "See below/above" → Use file paths or section headers.
❌ Conditional walls → Push logic into scripts/. Replace step with script call.
❌ Repeating frontmatter in body → Delete. Description belongs in YAML only.
❌ Open-ended tasks → Add concrete scope constraint.

Tier	Output
A	`SKILL.md` (example inline as `## Example`)
B	`SKILL.md` + `scripts/` + `references/Example.md` + `references/` (if context=yes)
C	`SKILL.md` orchestrator + `references/Example.md` + `references/*.md` per stage playbook