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.
refund-returns-policy, replace the template rules with yours, re-run its benchmark, assign it to the agent. The main prompt is untouched.
There is no orchestration primitive to learn — the router is the orchestration. You don’t write code that decides “now apply the refund policy”; the router surfaces it when the query matches.
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.Fork, install, or use?
Three ways to get a registry skill in front of your agent, in decreasing order of ownership:
Fork and install are defined precisely in the Community Registry guide — fork is the canonical verb; install is fork + disk export. Whichever path you choose, the skill still isn’t loaded by any agent until it’s assigned (forks) or subscribed (Use).
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: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.