| 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)
- 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.
- Reusable — will plausibly recur ≥3 times. One-off → agentmemory lesson instead, not a skill.
- 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)
- Load failing skill; state the failure in one sentence with the artifact that proves it.
- Diff: which step's evidence gate was passable while the outcome was still wrong? That step is underspecified.
- Propose minimal revision (surgical — no rewrite unless the category is wrong, e.g. it's a logic bug needing replan, not a capability gap).
- Validate against last 3 similar trajectories (
memory_recall). If <3 exist, say so — don't fabricate validation.
- 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.
