Skip to main content
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; 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 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. Skills with benchmark evidence carry a with/without comparison — 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 the returns-policy skill you picked off the registry, replace its 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 skill list: one name + description row per relevant skill, injected into the system prompt as a ready-made fragment. Two strategies build that list:
  • Full menu — every eligible skill’s row. Used when the whole skill list 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 skill list 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 load_skill(name) tool is rolling out per adapter — live on LangChain, OpenAI Agents, the OpenAI SDK, Pydantic AI, Google ADK, the Gemini API and the Anthropic Messages API (through each one’s agent_config()), where the model calls the tool and the body arrives as a tool result. inject_skill_body is tri-state and resolved per adapter (SDK 0.12.0+): CrewAI’s skill loader (enable_skill_loader=True), which has no tool loop, injects the routed skill’s body by default because injection is its only body channel (from SDK 0.14.0, when the platform ranked the result by the turn’s message — see query_ranked); every agent_config(), with its load_skill tool loop (langchain, openai_agents, openai, pydantic_ai, adk, google_genai, anthropic), doesn’t, so a body is never delivered twice; an explicit decimalai.init(inject_skill_body=True|False) or DECIMALAI_INJECT_SKILL_BODY=1|0 always wins. Exact budgets and the current adapter matrix live in the router reference.

​
Start from a pack, then scaffold

The Support pack also offers a public builder. You can download a real Python/OpenAI starter without a DecimalAI account, or sign in to save the reviewed configuration and try a bounded hosted sample when sponsorship is enabled. A recorded example, a local successful task, and a hosted trial are separate outcomes. The anonymous starter freezes and delivers the full selected instructions and text companions; it does not use the connected SDK’s progressive router or upload traces. See the Support tutorial for prerequisites and the four-call local check cost. You do not have to assemble the bundle by hand. Pick a role in the pack gallery — Support, Coding, Data Analyst and 29 more — and click Start with N skills. The create form opens at app.decimal.ai/agents/new?pack=<slug> — for example ?pack=support — with that role’s starter prompt filled in and its starter skills ticked. Create the agent, then let the CLI write the code for it:
agent.py reads the prompt from your workspace when it starts and receives the agent’s skills on every turn. Build an agent walks through every step, including the install line and keys, and other frameworks are one flag away (see the CLI reference). Support only: --project generates a fuller LangChain project — the agent plus checks that confirm the Support skills reached the model and the answers hold up:
It needs the three Support skills its checks use; the Support tutorial covers it end to end. For any other pack, use the single-file command above.

​
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 write a skill’s files without forking it:
Other frameworks point their own skill loader at the same folder with decimalai.skills_dir(); Native skill loaders has the line for each. CI and Docker reproduce the files with decimalai skills install --frozen; Skills on disk covers the commands.
Export is decimalai skills add (SDK 0.15.0+), with one folder, .agents/skills/, for every runtime. The 0.14 spellings, decimalai skills export <ref> and decimalai skills install <ref>, were removed in 0.18. For an editable copy, Fork. decimalai skills pull <ref> still writes a keyless loose copy that nothing updates.
Exported files serve runtimes that load skills themselves. An agent that gets its skills from the router, as this page describes, doesn’t need them, and a skill that is both routed and on disk reaches the prompt twice: pick one channel per agent. Install is reversible — remove the link from the skill page or from Your skills, and your agents stop receiving it. A fork is your own skill and is deleted like any other. Every word here is defined once, in Vocabulary. An editable copy made in the dashboard reaches only the agents you pick, and an installed skill reaches the agents you choose under Apply to. A copy made with the SDK’s router.fork() reaches the agents that had the original and the ones you add it to (SDK 0.25.1+). An older SDK sends no scope, so its copy gets the platform’s default; narrow it with Only agents it’s assigned to on its Settings tab.

​
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.
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, and skill observability are the measured surfaces; the trajectory set is a practice you build from them — the Support tutorial starts with two checked support scenarios.

Support agent tutorial

The worked example: create a Support agent from its pack, generate the project, check real answers, and open their traces.

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.