Skip to main content
This tutorial assembles a customer-support agent that triages tickets, applies your policies, drafts grounded replies, and escalates when it should — from registry skills, not a hand-written mega-prompt. Support is the reference example because it’s the archetype the official catalog covers best, but the process at the end works for any role. If you haven’t read Assemble an agent from skills, that guide is the general version of the mental model used here.

​
The mental model: agent = lean main prompt + skill bundle

An agent built this way is two things, and the skill router is the glue:
  1. A lean main prompt — the always-on core: identity, mission, authority and limits, tools, one line of baseline tone, and “lean on your installed skills.”
  2. An installed skill bundle — the on-demand library. Each turn, the Skill Router matches the incoming message against the bundle and surfaces the relevant skills; the agent applies them and replies.
The dividing line — the one real design decision: if something is true on every turn, it belongs in the main prompt. If it’s true only in some situations, it’s a skill.
Why bother splitting? Three reasons, each measurable:
  • Context stays lean. The refund policy loads only when a refund comes up; the handoff format loads only at escalation. A mega-prompt pays for everything on every turn.
  • Each part is proven separately. Every skill in the bundle carries its own ablation — with-vs-without evidence that it lifts. A paragraph buried in a mega-prompt is never tested on its own.
  • Parts are swappable. Fork one policy skill and the rest of the agent is untouched — no prompt surgery, no re-testing everything at once.
Before (the mega-prompt): one 900-line system prompt embedding the refund table, the SLA matrix, the escalation thresholds, the reply format, and three paragraphs of tone guidance. Every turn pays for all of it, and no single rule has ever been measured. After (the split): a ~15-line main prompt; the refund table lives in refund-returns-policy, the SLA matrix in sla-priority-assignment, the escalation thresholds in support-escalation-policy — each loaded when relevant, each with its own benchmark.

​
How skills reach the agent at runtime

What’s live today: on every routed turn the router surfaces a menu of name + description rows for the matching skills (budgeted, so a growing bundle can’t bloat the prompt), and the SDK injects that fragment into your system prompt. Full instruction bodies load on demand — this is progressive disclosure.
Honest status: on-demand body loading via the load_skill(name) tool is rolling out per adapter — it’s live on the openai_agents and pydantic_ai adapters, 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 with inject_skill_body=True (off by default). See the router reference for the current mechanics and budgets.

​
The support bundle (skill map)

Decompose the support role into jobs-to-be-done, then map each job to a skill. Every skill below exists in the official registry today: Two things to notice about the taxonomy column (the badges are the two-axis classification):
  • Public-scope skills are generic and usually carry over unchanged — extraction, classification, grounding, redaction encode broadly-shared behavior.
  • Private-scope skills ship as templates. Their bodies say so explicitly (“Template: replace with your refund policy”). They encode the shape of a house policy with example rules — useful for a demo, but the point is to fork them and substitute your own rules in step 6.
The gaps are yours to author. This bundle triages, decides, and escalates — but it doesn’t yet enforce your reply structure, a de-escalation register for upset customers, or a pre-send policy check on the drafted reply. Those are classic preference skills, and writing them is a one-guide job: follow Authoring Skills, prove each lifts, and slot them into the Respond and Guard rows. Resist the urge to stuff these into the main prompt instead — “the customer is upset” is a situation, and situational knowledge is a skill.

​
The process, in six steps

1

Decompose the role into jobs-to-be-done

The turn stages above: triage, understand, answer, decide, respond, guard, escalate. Write them down before touching any skill — the decomposition is what keeps the bundle honest. If a job doesn’t appear in real tickets, it doesn’t need a skill.
2

Map each job to a skill

Reuse from the registry first; author the gaps with the skill-authoring guidance. Classify each as you go (capability vs. preference, public vs. private) — the classification tells you which ones you’ll customize later and which will retire.
3

Prove each skill lifts — ablation is the per-skill gate

Run each skill’s eval suite with and without the skill loaded. A skill that doesn’t lift doesn’t belong in the bundle — it costs tokens on every activation and buys nothing. Registry skills arrive with a benchmark run attached; skills you author need one before you trust them.
4

Assemble: install the bundle, write the lean main prompt

Fork each registry skill into your org and assign the bundle to your agent. Then write the main prompt (next section). There is no orchestration code — the router is the orchestration.
5

Evaluate end-to-end, not just per-skill

Per-skill ablation proves each part; it does not prove the assembled agent. Build a small trajectory eval — realistic tickets graded on the whole run. This is the genuinely new work in agent assembly; see the section below.
6

Fork-to-private: make the policies yours

Replace the template rules in the private-scope skills with your actual refund windows, SLA matrix, escalation thresholds, and macro set. The public-scope skills usually carry over unchanged.

​
The main prompt, concretely

Everything here is always-on; everything situational lives in a skill:
Apply the dividing line to every candidate sentence: Before (situational knowledge leaking into the main prompt): “Refunds are allowed within 30 days for physical goods, 14 days for digital purchases; defective items override the window; refunds over $500 must be escalated…” — paid on every turn, tested never. After: those rules live in refund-returns-policy and load when a refund is on the table. The main prompt keeps only the always-true boundary: “You may not promise refunds beyond what the policy skills grant.”
The “you may NOT” block earns its always-on cost: authority limits must hold on every turn, including turns where no policy skill fires. Limits go in the main prompt; the rules that implement them go in skills.

​
The end-to-end eval: the agent-level ablation

Per-skill benchmarks are unit tests. The assembled agent needs an integration test: a trajectory eval over realistic tickets, grading the whole run —
  • Did it land in the right queue with the right priority?
  • Did it apply the policy correctly (including the deny cases)?
  • Is the drafted reply grounded, compliant, and free of PII?
  • Did it escalate exactly when warranted — and not when it wasn’t?
Fifteen to twenty tickets spanning those axes is enough to start. Include tickets that exercise skill handoffs (a refund request from an angry Enterprise customer touches four skills), and re-run the set whenever you swap a skill in or out — it’s the same with-vs-without discipline as skills ablation, applied one level up.
Honest limits: there is no one-button trajectory eval on the platform today. This is a practice you compose from existing pieces — run the tickets through your agent, grade the trajectories with your own harness or trace evaluators, and keep the ticket set in version control next to the agent. Per-skill benchmarks and live skill observability remain the platform-measured layers underneath.

​
Fork-to-private: making it yours

The bundle above runs on generic officials — fine for a demo, wrong for production, because the private-scope skills are templates by design. To productionize, fork and customize the Preference · Private rows: support-routing-policy · sla-priority-assignment · refund-returns-policy · entitlement-gating · macro-response-selection · content-compliance · support-escalation-policy · handoff-summary-format Replace each template’s example rules with your real ones, keep the skill’s eval suite shape, and re-run the benchmark — your rules are different knowledge, so the old lift number no longer applies. The Preference · Public rows (extraction, classification, grounding, redaction) usually carry over unchanged. Your forks are private to your org unless you publish them — see visibility and forking for the contract.

​
Other archetypes, same recipe

Support is the flagship because the catalog covers it end-to-end. The same six steps assemble other roles from the same registry:
  • Coding — code review (security / performance / accessibility), test generation, PR descriptions, commit conventions, refactoring.
  • Document & back-office ops — extraction schemas, classification, validation, redaction.
  • Data analysis — SQL conventions, data cleaning, computed analysis.
Decompose the role, map the jobs, prove the lift, assemble, evaluate end-to-end, fork the policies. The archetype changes; the recipe doesn’t.

Assemble an agent from skills

The general guide: the mental model, router mechanics, progressive disclosure, and choosing skills from the registry.

Authoring Skills

Write the gap skills — classification, description craft, body craft, and the honest eval suite.

Community Registry

Discover, fork, receive upstream updates, publish your own.

skillevaluation

The open A/B benchmark that produces every lift number in this tutorial.