> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Assemble an Agent from Skills
> The mental model for building agents as a lean main prompt plus a skill bundle — router mechanics, progressive disclosure, fork vs. install vs. use, and how to choose skills from the registry.
Most agents grow the same way: the system prompt accretes policies, formats, and edge-case rules until it's a mega-prompt nobody can test or safely edit. This guide covers the alternative — assembling an agent as a **lean main prompt plus an installed skill bundle**, where each part is independently measured and swappable.
For a complete worked example, see the [support agent tutorial](/tutorials/support-agent-from-skills); this page is the general model behind it.
## The mental model
An agent assembled from skills is two things:
1. **A lean main prompt** — the always-on core: identity, mission, authority and limits, tools, one line of baseline tone.
2. **An installed skill bundle** — the on-demand library. Each turn, the [Skill Router](/api-reference/skills/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.
The split earns its keep three ways:
* **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](/guides/authoring-skills#lifecycle-ablation-and-retirement) — 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.
**Before** (mega-prompt thinking): "add the new returns policy to the system prompt" — a 40-line paste into a 900-line prompt, effective everywhere, tested nowhere.
**After** (assembly thinking): fork `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](/api-reference/skills/router#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](/guides/authoring-skills#put-depth-in-references-exact-steps-in-scripts), applied at runtime by the router:
| Layer | Cost | When it's in context |
| ---------------------------------- | --------------------- | ------------------------------------ |
| Name + description (the menu row) | Cheap, budgeted | Every routed turn |
| `SKILL.md` body (the instructions) | Moderate, budgeted | Only when the skill is activated |
| `references/` and `scripts/` | Paid only on open/run | Only when the agent reaches for them |
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](/api-reference/skills/router).
## Fork, install, or use?
Three ways to get a registry skill in front of your agent, in decreasing order of ownership:
| Verb | What happens | Reach for it when |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Fork** | The skill is copied into your org as an independent skill you own and can edit. Upstream changes arrive as opt-in [merge offers](/guides/registry#3-receive-upstream-updates), never auto-applied. | You'll customize it — private policies, house style, template skills. |
| **Install** | The SDK's `install()` — a fork *plus* `SKILL.md` written to disk for file-based runtimes (Claude Code, Cursor). | Same as fork, and your runtime loads skills from disk. |
| **Use** | Subscribe an agent (or workspace) to the registry skill directly — no copy. Track latest, or pin a version. | A generic public skill you'll never edit, where you want upstream improvements to flow. |
Fork and install are defined precisely in the [Community Registry guide](/guides/registry#2-fork-into-your-org) — 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](/guides/skills#agent-skill-assignment) (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](/guides/authoring-skills#the-two-axes): **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
| Signal | Question it answers | Where it comes from |
| ------------------------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Lift** | Did this skill measurably improve an agent, with vs. without? | The [skillevaluation](/guides/skillevaluation) A/B benchmark — the strongest single signal. |
| **[SkillScore](/guides/skillscore)** | Does it work overall, on live evidence? | 0–100 composite: benchmark lift + live eval pass rate + AI-judge quality + cross-org adoption. Never install counts alone. |
| **SkillSafety band** | Is it safe to load? | The [vetting pipeline](/guides/trust-safety/how-skills-are-vetted): static scan + AI security review + content review, folded into Passed / Caution / Blocked / Not yet reviewed. |
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](/guides/skillevaluation#verified-runs-hosted).
A quick consumer checklist before adding a skill to your bundle: SkillSafety band Passed (read the findings on Caution) · lift from a *verified* run · re-verified recently if Capability · Public · trigger health healthy if it's an Automatic skill · description's "Do NOT use for" doesn't collide with another skill in your bundle.
## 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](/guides/evaluations), and [skill observability](/tutorials/skills-observability) are the measured surfaces; the trajectory set is a practice you build from them — the [support tutorial](/tutorials/support-agent-from-skills#the-end-to-end-eval-the-agent-level-ablation) shows a concrete starting shape.
## Related
The worked example: the full skill map, the concrete main prompt, and the six-step process.
Runtime mechanics — strategies, budgets, adapters, and the load\_skill tool.
Fork, receive upstream updates, publish — with the trust surfaces this guide reads.
When the registry has a gap: write a skill that proves its lift honestly.