skill-forge

name	skill-forge
description	Create or revise a SKILL.md from a real task trajectory. Use when loop-runtime classifies a trajectory as novel or skill-failure, when the user says "make this a skill", "persist this pattern", "the skill got it wrong", or when a nudge resolves to "persist as skill". Enforces the evidence gate — never generate speculative skills from ideas alone.

Skill Forge

Creation gate (all must pass before drafting)

1. Executed once for real — point to the artifact in this or a recalled session (hard rule 1). No artifact → refuse, offer to run the pattern first.
2. Reusable — will plausibly recur ≥3 times. One-off → agentmemory lesson instead, not a skill.
3. Not already covered — grep existing skills dir + memory_lesson_recall first. Overlap → improvement mode, not creation.

Draft format (agentskills.io-compatible)

skill-name/
├── SKILL.md        # YAML frontmatter: name, description (pushy, trigger-rich)
├── scripts/        # deterministic steps as code, not prose
└── references/     # loaded on demand

SKILL.md body must contain, in order: Scope, Assumptions, Steps (each with its evidence-of-completion), Tool requirements, Failure modes (MANDATORY — when NOT to use, hard rule 2), Verification test (one minimal cold-runnable check).

Model-facing rule: commands and behaviors only, no theory, no technique abbreviations. "Telling lungs about gas exchange doesn't improve breathing."

Improvement mode (skill-failure path)

1. Load failing skill; state the failure in one sentence with the artifact that proves it.
2. Diff: which step's evidence gate was passable while the outcome was still wrong? That step is underspecified.
3. Propose minimal revision (surgical — no rewrite unless the category is wrong, e.g. it's a logic bug needing replan, not a capability gap).
4. Validate against last 3 similar trajectories (memory_recall). If <3 exist, say so — don't fabricate validation.
5. Version bump in frontmatter; old behavior preserved unless the failure IS the old behavior.

Commit protocol

Draft → show user → user confirms → write skill + one ledger line (skill_created/skill_revised, trigger, evidence path, scored_by). No confirmation → park in .sia/dangling.md.

Deprecation

Any skill unused or failing for 30 days: propose retirement in the weekly audit. Move to skills/_archive/ with a tombstone line in SKILL.md pointing to its successor. Never delete — the ledger must stay traceable.

Failure modes — do NOT use this skill when

• The pattern has never executed (speculative). Refuse.
• The "pattern" is a preference or fact — that's memory-consolidate territory.
• Mid-task — forge only after outcome classification; drafting mid-flight fabricates steps not yet proven.
• The improvement is really a one-line env fact ("path is X on WSL") — lesson, not skill revision.