How to Keep a Skill Small Enough That the Agent Loads It

Strip a skill to its irreducible core and you get three things.

The trigger: the exact user phrasing or condition that should cause the agent to reach for this skill. This lives in the description, because the description is what the agent matches the request against (agentskills.io description guide).

The steps: the ordered procedure the agent should follow once loaded. If the steps are subjective, write them as prose guidance. If a step is mechanical and fragile, ship it as a script instead, because scripts run through bash and only their output enters context (Claude platform docs).

The one failure it prevents: the specific mistake this skill exists to stop. This is the part almost everyone drops, and it is the part that decides whether the body earns its tokens. A log-fetching skill whose only job is "call this endpoint with these filters" is what Red Hat's Applied AI team calls a capability skill, one that patches a model gap and will deprecate as models improve. A skill that encodes your team's root-cause analysis order of operations is a preference skill, and it stays valuable because the model cannot invent your process (Red Hat Next).

If you cannot name the failure in one sentence, you probably do not need a skill. You may need a shell command in your project instructions, or nothing at all. Anthropic's own authoring guide makes the same point bluntly: assume the model is already very smart, and challenge every paragraph with "does this justify its token cost?" (Claude skill authoring best practices).

One distinction worth internalizing before you start cutting: skills are not system prompts. A system prompt is static text loaded once at session start. A skill is a file the agent discovers, evaluates for relevance, and loads dynamically, including code it can execute (Verdent's comparison). Anything that must apply in every conversation belongs in always-on project instructions, not in a skill. Claude's own course material draws the line the same way: always-on project standards go in CLAUDE.md, task-specific expertise goes in skills (Claude Academy). Every line you move from a skill into always-on instructions is a line you stopped paying for on every skill load, and every line you move out of always-on instructions into a skill is a line you stopped paying for on every unrelated turn.

Here is a working budget. It is not a specification, it is a decision rule you can apply in one pass:

• Description: one to three sentences, under about 500 characters of the 1,024-character hard limit. You want room inside the limit for synonyms and near-miss exclusions.
• Body: under 500 lines and under 5,000 tokens. Microsoft states both numbers as guidance (Microsoft Learn); the token figure matches Anthropic's stated Level 2 budget (Claude platform docs).
• Scripts: as many as the procedure genuinely needs, referenced by relative path, not pasted inline.
• Reference files: everything that is lookup material, because they cost nothing until read.

Then delete in this order. Each category below is something the agent either already knows or can derive from the repository.

Anthropic's guide gives a concrete before and after for exactly this: a roughly 150-token passage explaining what PDFs are, why libraries are needed, which library is recommended and how to install it, versus a roughly 50-token version that just shows the extraction call (Claude skill authoring best practices). Same behavior, a third of the tokens.

The broader reason to be ruthless is that the same discipline applies to the tools around the skill. Guidance on agent tool counts holds that accuracy degrades past roughly 10 available tools, with a working recommendation of fewer than 20; connect a few MCP servers carelessly and you reach 90+ tool definitions and over 50,000 tokens of JSON schemas before the model reasons at all (SwirlAI). Skills help by deferring load, but a bloated skill body reintroduces the same problem on the one turn where precision matters most.

Where does a skill end and a script begin? The Red Hat team reports that moving mechanical steps out of inference and into deterministic scripts cut cost 26% in their experiments while improving accuracy (Red Hat Next). That is the strongest available argument for shrinking the body: every step you can replace with a script call is a step you deleted from the loaded context.

The description carries the entire triggering burden. At startup the agent sees only names and descriptions; when a user request matches one, it reads the body (agentskills.io description guide). Nothing else about your skill exists at decision time.

Four rules do most of the work.

Write it as an instruction, not a label. "Use this skill when..." beats "This skill does...". Anthropic's own PDF skill does this explicitly, listing reading, extracting, merging, splitting, rotating, watermarking, filling forms and OCR, then closing with "If the user mentions a .pdf file or asks to produce one, use this skill" (SwirlAI, quoting the official repo). The list is long because the surface area is genuinely wide, and it names the literal token .pdf.

Use the user's words, not yours. Match against intent, not implementation. If your team calls it "the reconciliation job" but users say "check the books", both phrases belong in the description. Internal codenames that nobody types will never match.

Be pushy about scope. Explicitly cover cases where the user does not name the domain: "even if they don't explicitly mention the file extension." And prune over-broad claims so it does not fire on everything.

Test what should not trigger. The best negative cases are near-misses that share keywords but need a different capability. For a CSV analysis skill, "update the formulas in my Excel budget" shares "spreadsheet" but needs editing, not analysis, and "write a script that reads a CSV and uploads each row to Postgres" shares CSV but is ETL (agentskills.io description guide).

Here is a before and after for an internal expense skill:

# Before: jargon, no user phrasing, no outcome
name: exp-pol-v3
description: Applies the Contoso finance reconciliation policy framework to submitted artifacts.

# After: trigger words, user phrasing, the outcome, and a scope note
name: expense-report
description: File and validate employee expense reports against company policy, and flag anything over the category limit before it is submitted. Use when the user mentions expense reports, receipts, reimbursements, per-diem limits, or "will I get paid back", even if they do not name the policy.

The second version matches the element Microsoft's sample uses in its format documentation, which states the description should say both what the skill does and when to use it and include keywords that help agents identify relevant tasks (Microsoft Learn).

One nuance to design around: agents typically reach for a skill only when the task needs knowledge or capability beyond what they can handle alone. A one-step request like "read this PDF" may not trigger a PDF skill even with a perfect description, because basic tools suffice. Specialized workflows, unfamiliar APIs and uncommon formats are where description quality decides the outcome (agentskills.io description guide). If your skill does something the model can already do in one step, no wording saves it.

Two mechanisms, one cheap and one rigorous.

The cheap one is a load event in your logs. Most harnesses use named tools for this, which makes instrumentation straightforward. Microsoft's implementation advertises a load_skill tool, a read_skill_resource tool when any skill ships resources, and a run_skill_script tool when any skill ships scripts (Microsoft Learn). If you can log tool calls, you can count skill loads per session and per query without any special hooks. Other harnesses expose filesystem reads, in which case log reads of SKILL.md paths.

The rigorous one is a labeled probe set. Write about 20 realistic queries to a JSON file, 8 to 10 that should trigger and 8 to 10 that should not, and label each one. The official guide's format looks like this (agentskills.io description guide):

[
  { "query": "I've got a spreadsheet in ~/data/q4_results.xlsx with revenue in col C and expenses in col D, can you add a profit margin column and highlight anything under 10%?", "should_trigger": true },
  { "query": "can you write a python script that reads a csv and uploads each row to our postgres database", "should_trigger": false }
]

Then run each query through the real harness, check the log for a load event, and score two numbers: the share of should-trigger queries that loaded (your recall) and the share of should-not-trigger queries that stayed dormant (your precision). Both matter. A skill that never fires is dead weight whose metadata you still pay for on every run. A skill that fires on near-misses poisons turns with irrelevant instructions, which is a known failure mode: context poisoning, where an error enters the context and gets reused, compounds over subsequent steps (Splunk's production context guide).

Vary the should-trigger queries along four axes the guide names: phrasing (formal, casual, typos), explicitness (naming the domain versus describing the need), detail (terse versus context-heavy with real file paths), and complexity (single step versus the relevant task buried in a longer chain) (agentskills.io description guide).

When a query misses, the fix is almost never "add more instructions to the body". The body was not read. Rewrite the description with the words from the failing query, rerun the probe set, and confirm both scores moved.

A worked example of the arithmetic: suppose your probe set has 10 should-trigger and 10 should-not-trigger queries. First run, 6 of 10 fire and 3 of 10 near-misses fire. You have 60% recall and 70% precision. You rewrite the description to add the two missing phrasings from the four misses and to add an explicit exclusion ("not for editing spreadsheet formulas"). Second run: 9 of 10 fire, 1 of 10 near-misses fires. That is 90% recall and 90% precision from one description edit and no body change.

Evaluation discipline pays off beyond triggering. The Red Hat team calls a curated evaluation dataset one of your most valuable assets, because it grounds every optimization decision in evidence rather than intuition (Red Hat Next). The probe set is the smallest useful version of that asset, and it takes an hour to build.

Run this against any skill before it goes into a shared library.

• Can I state the one failure this skill prevents in a single sentence?
• Does the description use the words users actually type, including at least one phrase that does not name the domain?
• Does the description exclude at least one plausible near-miss?
• Is the body under 500 lines and under roughly 5,000 tokens?
• Have I deleted format explanations, install steps, style rules and duplicate rules?
• Is every mechanical, fragile step a script rather than prose?
• Is every lookup table in a reference file, referenced by relative path?
• Does the probe set have 8 to 10 positive and 8 to 10 negative queries, and did I record both scores?
• Did I confirm in the logs, not by eyeballing the answer, that the load event fired?

That last item is the one people skip. A correct-looking answer does not prove the skill loaded; the model may have guessed well. The log proves it.

If you are building skills across several teams and want a shared library with experts that carry the same discipline into a line of business, Quanta Skills is where those packaged skills and experts live.