Agent skill · v2.1 · Python stdlib only

Skill Forge
route, forge, prove.

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.

Download SKILL.md View source on GitHub @osintgram_io
1,336registry entries
32sectors
402archetypes
500prompt lenses
231integration actions
162skills indexed
Operating principles

Three rules, enforced in code

RULE 01

Route before you answer

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.

RULE 02

Build from the registry

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.

RULE 03

Nothing leaves until something is better

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.

Pipeline

One build, six moves

01 routeScore the need against 1,336 entries
02 scaffoldPre-fill the spec from the registry
03 forgeRender the complete skill folder
04 validateForm gate, 90/100 minimum
05 benchScore against the incumbent
06 packageZip, or supersede with proof
Steps 02 and 03 are the auto-build. The scaffold deliberately leaves workflow, output contract and quality gates empty — and the renderer refuses an unfilled skeleton, so the thinking cannot be skipped. That is the difference between generating a skill and generating a file that looks like one.
The registry

What the router actually knows

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.

TypeCountWhat an entry is
skill162A full skill with workflow, references and scripts — 70 installed, 92 imported as reference
command500A prompt lens from a slash-command library — /swot, /eli5, /hook10
integration231One concrete action of a connected service: GitHub, BigQuery, Zoho, Ahrefs, Notion, Supabase, WordPress
core41A platform capability that needs no skill loaded: file builds, web search, translation, code execution
archetype402A 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.

An archetype hit means “this is a real professional job, build it properly” — it hands the forge the profession’s own artefact name: SBAR, BOQ, 8D, CAPA, tech pack, logframe, run sheet, method statement. A generic “report” is a failed build even when it validates.
Replacement gate

Replacing a skill has to be earned

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.

VerdictConditionWhat happens
REPLACE+10 points or more, and no regression on coverage or precisionThe old entry is superseded and stops routing
KEEP_BOTHBetter in places, not overall — or a missing judgement fileRegisters as a scoped variant; routing decides per request
REJECT_NEWWeaker than the incumbent, or under the 60/100 admission floorNot added at all

Nothing is deleted

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.

The gate is mechanical

--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.

Toolbox

Eight scripts, no dependencies

ScriptDoes
route.pyNeed → ranked candidates + verdict (reuse / adapt / forge), exit 3 on forge
scaffold_spec.pyNeed → pre-filled spec skeleton; leaves the judgement fields empty on purpose
forge_skill.pySpec → complete skill folder: frontmatter, workflow, contract, gates, bundled files
validate_skill.pyForm gate: frontmatter, name, description limits, sections, placeholders, broken paths, script compile
bench.pyRubric score and the REPLACE / KEEP_BOTH / REJECT_NEW decision
package_skill.pyValidated folder → zip, refusing to package a skill that fails validation
update_registry.pyIngest zips and folders, supersede with proof, restore, rebuild
build_registry.pyRebuild 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>
Install

Drop the folder in, run the router

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
Limits, stated plainly

What it does not do

Routing is lexical, not semantic

It can be confidently wrong on a paraphrase. The protocol therefore requires reading the top candidate’s capability line before trusting a reuse verdict.

The validator checks form, not quality

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.

Reference entries are not installed

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.

Archetypes are a map, not a capability

A match means “build this”, never “this exists”. The honesty of the registry is the whole reason its counts are trustworthy.

Attribution. The registry indexes 18 skills from anthropics/skills (Apache 2.0, commit 2c5958e) as reference entries. Origin and licence for every imported entry are recorded in registry/ATTRIBUTION.md inside the skill folder.
Contact

Built and maintained in public

Questions, bug reports, a profession the registry is missing, or a skill you want forged — the fastest route is a DM.

@osintgram_io