The mental model
An agent assembled from skills is two things:- A lean main prompt — the always-on core: identity, mission, authority and limits, tools, one line of baseline tone.
- An installed skill bundle — the on-demand library. Each turn, the Skill Router matches the incoming query against the bundle and surfaces what’s relevant.
The dividing line: true on every turn → main prompt. True only in some situations → skill. That single test decides where every sentence lives.
- Lean context. Situational knowledge loads only in the situations it applies to, instead of being paid for on every turn.
- Measured parts. Every skill carries its own ablation — with-vs-without proof of lift. Prose inside a mega-prompt is never tested in isolation.
- Swappable parts. Replacing one policy skill doesn’t touch the rest of the agent.
How skills reach your agent per turn
On each routed turn, the router produces a menu: one name + description row per relevant skill, injected into the system prompt as a ready-made fragment. Two strategies build that menu:- Full menu — every eligible skill’s row. Used when the whole menu fits the budget: showing everything beats selection when everything is cheap.
- Smart route — for larger registries: semantic + lexical retrieval over skill descriptions, re-ranked by measured effectiveness, returning the top-K rows. See routing strategies.
Progressive disclosure: descriptions always, bodies on demand
The pattern that makes this scale is progressive disclosure — the same three-layer cost structure you design into a skill when authoring it, applied at runtime by the router:
Descriptions are the always-on tier; bodies load on demand. Per-turn budgets keep both tiers flat as your bundle grows — the description menu is capped (roughly 1,500 estimated tokens / 30 rows), and body loads are capped per turn (a few bodies, each size-limited). A 100-skill org pays about the same per turn as a 20-skill org; what changes is selection quality, not context cost.
Honest status: on-demand body loading via the auto-registered
load_skill(name) tool is rolling out per adapter — live on openai_agents and pydantic_ai, where the model calls the tool and the body arrives as a tool result. Adapters without a tool loop (anthropic, langchain) can opt into budgeted body injection instead (inject_skill_body=True, off by default). Exact budgets and the current adapter matrix live in the router reference.Install, fork, or export?
Three ways to get a registry skill in front of your agent. They answer different questions, so this is not a ladder — most of the time the answer is Install.
Install and Fork answer what do I have; Export answers where do the bytes
live. They are separate questions, which is why you can export a skill you only
installed:
The
skills export command landed in 0.10.2. On 0.10.0 and earlier there
was no fork-free disk write from the CLI: decimalai skills install pdf --agent claude-code writes the same files but takes a fork, and
decimalai skills pull pdf writes a keyless, read-only copy.Choosing skills from the registry
The registry’s badges and panels were designed for consumers, not just authors. Reading them well is most of the job:The source badge is provenance, not a recommendation
Before anything else, know what the badge on a card is not telling you.community means the skill was authored on the DecimalAI platform and published by its author — DecimalAI publishes its own skills into the registry too, and they carry the same badge as anyone else’s. imported means the skill was synced from a public GitHub repo. featured is a community skill the ranking promoted on its own numbers, and demotes again when those numbers fade. None of the three is a curation decision, so none of them is a substitute for reading the evidence below. See Community Registry for the full badge list.
What the taxonomy badges mean for you
Every classified skill shows its two-axis taxonomy: Capability or Preference, Public or Private scope. As a consumer:- Capability · Public is the one quadrant that expires — it teaches something future base models will absorb. Before installing, check the re-verification history (“Verified on ⟨model⟩ — re-tested ⟨date⟩”) on the skill’s detail page. A big lift number measured two model generations ago may already be zero; a fresh re-test date is the evidence that it isn’t.
- Preference skills don’t decay the same way — their failure mode is firing wrong. Check trigger health on the detail page: trigger recall and false-fire rate from the skill’s own trigger cases, joined with production routing data (how often it was offered vs. actually selected). A skill that helps but never fires — or fires on the wrong queries — is broken in a way its benchmark can’t show.
Three numbers that answer three different questions
Don’t collapse them into one gut feeling: a high-SkillScore skill with a stale re-verification may be living on old evidence, and a spectacular lift number from an unverified run is a self-reported claim. Which brings us to:
Verified vs. unverified evidence
Benchmark results reach the registry two ways, and they are not equal. Verified runs were executed by the hosted runner (same open-spec judge and validators, trusted environment, stamped with model + date) — only these feed rankings, registry cards, and SkillScore. Pushed local runs are welcome on a skill’s own page but are tagged unverified and never feed rankings — self-reported numbers can’t poison the leaderboard. See skillevaluation → Verified runs.Proving the assembly: end-to-end trajectory evals
Per-skill ablation is the unit test of this architecture. The assembled agent needs an integration test: an end-to-end trajectory eval — a fixed set of realistic, full-conversation tasks graded on the whole run (right decisions, right outputs, escalated exactly when warranted), not on any single skill’s contribution. It’s the agent-level analog of skills ablation, and it’s what you re-run when the bundle changes: swap a skill in or out, run the same task set, compare. A bundle change that helps one skill’s benchmark but hurts the trajectory eval is telling you about an interaction — usually two skills whose descriptions collide, or a gap between what one skill hands off and the next expects.Honest limits: the platform doesn’t ship a one-button trajectory eval today. Per-skill benchmarks, trace evaluators, and skill observability are the measured surfaces; the trajectory set is a practice you build from them — the support tutorial shows a concrete starting shape.
Related
Support agent tutorial
The worked example: the full skill map, the concrete main prompt, and the six-step process.
Skill Router
Runtime mechanics — strategies, budgets, adapters, and the load_skill tool.
Community Registry
Fork, receive upstream updates, publish — with the trust surfaces this guide reads.
Authoring Skills
When the registry has a gap: write a skill that proves its lift honestly.