A self-updating skill factory for AI agents. It routes any request against a 1,336-entry capability registry, reuses what already exists, forges a new skill when nothing does, validates it, benchmarks it — and only retires an existing skill when the replacement measurably beats it.
Never “there’s no skill for that” from memory. Every request is scored against the registry first, because skipping the lookup is how four near-duplicate skills end up competing for the same trigger word.
A new skill names what it reuses and what it must not steal work from. The scaffold fills everything the registry already knows; only the judgement is left to write.
A skill is replaced only when a bench run shows the new one is 10 points better on the same job, with a stored proof. Newer is not better.
Five types of entry, one file each run. Counts are the build state — the scripts print the live total, and no number on this page is quoted from memory.
| Type | Count | What an entry is |
|---|---|---|
| skill | 162 | A full skill with workflow, references and scripts — 70 installed, 92 imported as reference |
| command | 500 | A prompt lens from a slash-command library — /swot, /eli5, /hook10 |
| integration | 231 | One concrete action of a connected service: GitHub, BigQuery, Zoho, Ahrefs, Notion, Supabase, WordPress |
| core | 41 | A platform capability that needs no skill loaded: file builds, web search, translation, code execution |
| archetype | 402 | A standard repeating task of a real profession with no skill built yet — a blueprint, not a capability |
402 archetypes cover 201 professions across 32 sectors — healthcare, law, civil and mechanical engineering, finance, banking and insurance, sales, education, agriculture, manufacturing, logistics, hospitality, retail, media and design, sports, government, defence, environment and energy, laboratories, pharma, HR, real estate, textiles, automotive, aviation, maritime, telecom, mining, nonprofit — and personal life admin.
The bench scores out of 100: 45 points measured from the files (workflow steps, contract lines, quality gates, bundled scripts, references, description) plus 55 points judged 0–5 across coverage, precision, triggers, boundaries and gates.
| Verdict | Condition | What happens |
|---|---|---|
| REPLACE | +10 points or more, and no regression on coverage or precision | The old entry is superseded and stops routing |
| KEEP_BOTH | Better in places, not overall — or a missing judgement file | Registers as a scoped variant; routing decides per request |
| REJECT_NEW | Weaker than the incumbent, or under the 60/100 admission floor | Not added at all |
The losing entry moves to registry/superseded.json with the winner, the date,
the margin and the proof path. It stops routing, stays listed under
## superseded, and --unsupersede brings it back. Seed entries can
never be deleted — only superseded, so the record of what replaced them survives.
--supersede refuses to run without a proof file whose verdict is
REPLACE, whose loser is the entry you named, and whose margin clears 10 points.
A hunch cannot retire a skill, and neither can a better-formatted but thinner one.
| Script | Does |
|---|---|
route.py | Need → ranked candidates + verdict (reuse / adapt / forge), exit 3 on forge |
scaffold_spec.py | Need → pre-filled spec skeleton; leaves the judgement fields empty on purpose |
forge_skill.py | Spec → complete skill folder: frontmatter, workflow, contract, gates, bundled files |
validate_skill.py | Form gate: frontmatter, name, description limits, sections, placeholders, broken paths, script compile |
bench.py | Rubric score and the REPLACE / KEEP_BOTH / REJECT_NEW decision |
package_skill.py | Validated folder → zip, refusing to package a skill that fails validation |
update_registry.py | Ingest zips and folders, supersede with proof, restore, rebuild |
build_registry.py | Rebuild registry.json / registry.md from seed + extra |
# what already exists? python scripts/route.py "nurse shift handover SBAR banao" # auto-build: scaffold, then fill only the judgement python scripts/scaffold_spec.py "nurse shift handover SBAR banao" --out spec.json python scripts/forge_skill.py spec.json --out /scratch/work/forged # form gate, then quality gate python scripts/validate_skill.py /scratch/work/forged/<name> python scripts/bench.py compare /scratch/work/forged/<new> <old-skill-dir> \ --new-judgement j-new.json --old-judgement j-old.json --out proof.json # only if the verdict is REPLACE python scripts/update_registry.py --supersede <old-id> --proof proof.json python scripts/package_skill.py /scratch/work/forged/<name>
Requirements: Python 3.9+, standard library only.
No network, no packages, no build step. The skill folder contains everything:
SKILL.md, six references, eight scripts and the built registry.
Copy skill-forge/ into your agent’s skills directory, or take the single
SKILL.md and pull the rest from the
repository.
skill-forge/
├── SKILL.md the protocol an agent follows
├── references/ routing, professions, blueprint,
│ gates, supersede, updates
├── scripts/ the eight scripts above
└── registry/
├── seed.json curated base
├── extra.json skills you supplied
├── superseded.json retired, with proof
├── registry.json built, machine-readable
├── registry.md built, greppable
└── ATTRIBUTION.md origin + licence
It can be confidently wrong on a paraphrase. The protocol therefore requires reading the
top candidate’s capability line before trusting a reuse verdict.
A thin one-paragraph skill passed at 100/100 in testing and scored 31/100 on the bench. That is exactly why the bench exists as a second gate.
Their descriptions and trigger words are searchable; the files are not present. The router
never returns reuse for one — it says the files must be imported first.
A match means “build this”, never “this exists”. The honesty of the registry is the whole reason its counts are trustworthy.
2c5958e) as reference entries. Origin and licence for every imported entry are
recorded in registry/ATTRIBUTION.md inside the skill folder.
Questions, bug reports, a profession the registry is missing, or a skill you want forged — the fastest route is a DM.
@osintgram_io