When to Split a Skill into Two: Triggers, Steps and Overlap

Run the two tests before you touch the file. The table is the short version; the sections after it explain how to run each test and what the numbers mean.

The 20% figure is a working threshold, not a law. It comes from treating trigger accuracy as a classification problem where a wrong pick costs a full run plus a correction. At one in five, you are spending enough on misfires to pay for a second file. Below that, a sharper description is the cheaper fix. Patronus AI's write-up on agent routing makes the same point in the multi-agent setting: a misclassified input trickles down through every subsequent step and compounds errors, so routing accuracy deserves its own evaluation rather than being assumed per Patronus AI's routing guide.

Build a small eval set before you argue about the description. The optimize-descriptions guide recommends about 20 queries split roughly evenly between should-trigger and should-not-trigger, and it is explicit that the valuable negatives are near-misses: requests that share keywords with your skill but need something else per the optimizing descriptions guide.

For a skill covering two jobs, label every request with the job it belongs to, not just a boolean. That gives you a 3-way outcome per request: correct job, wrong job, no trigger.

[
  { "query": "reconcile the Q3 vendor invoices against the PO log and flag mismatches", "job": "reconcile" },
  { "query": "turn the attached statement into a monthly summary for the finance review", "job": "summarize" },
  { "query": "pull the totals from this spreadsheet into a chart", "job": "none" }
]

Three rules make the set useful.

1. Use requests people actually sent. Pull them from logs or tickets. Synthetic queries drift toward the wording already in your description, which flatters the skill. The same guide warns that realistic prompts carry file paths, column names and backstory that generic test queries lack.
2. Vary phrasing and explicitness. Some requests name the domain; others describe the need without naming it. A skill that only fires when the user says "invoice" is fragile.
3. Keep the near-misses hard. A request that shares vocabulary with your skill but needs a different capability is the only negative that tells you anything.

Run the set against the current single-skill setup. Record how many requests land on the wrong job. If that count divided by the number of two-job requests is above about 0.2, split.

One caveat on interpretation: agents only consult skills for tasks that need knowledge beyond their baseline, so a trivially simple request may not trigger any skill even with a perfect description per the optimizing descriptions guide. Do not count those as failures.

The trigger test catches skills that fire on the wrong requests. The step test catches skills that fire correctly and then do the wrong thing anyway.

Print both halves of the body and read them as if they were two separate documents. You are looking for four specific patterns.

Contradictions. Job A says "always normalize currency to USD before comparing." Job B says "preserve amounts exactly as written for audit." A single skill cannot hold both without a branch, and branches inside a skill body are where models start guessing.

Ordering conflicts. Job A must read data before writing anything. Job B must write a draft first, then revise. Concatenated into one numbered list, the two orders become one order, and one job loses.

Shared preconditions that only apply to one job. "Load the reference table" may be mandatory for reconciliation and pure overhead for summarization. Overhead is not free: every loaded token competes with the rest of the context per Anthropic's context engineering post.

Length that buries the point. If the guidance for job B sits 600 lines below the guidance for job A, the model reads it after it has already formed a plan. Anthropic's skill authoring guidance puts the default assumption bluntly: the model is already capable, so only add context it does not already have, and challenge each paragraph for whether it justifies its token cost per the skill authoring best practices.

A worked trace helps. Take three previously completed tasks, one per job plus one ambiguous, and walk the model's reading order through the file. If at any point the model would need to hold a rule from job A while executing job B, you have interference. Write that down; it is your evidence.

Red Hat's applied AI team makes a related distinction worth borrowing here: separate mechanical work that belongs in a deterministic script from subjective work that belongs in instructions. Switching a file-fetching step from model inference to a script cut their costs by 26% per Red Hat's skill development write-up. If half of your skill is mechanical and half is judgment, that is often the real seam, and it may not fall where the two jobs divide.

If you want a reason to take description hygiene seriously at more than one skill, look at routing research. SkillRouter, an Alibaba paper, evaluated routing over roughly 80,000 candidate skills with heavy overlap. Hiding the skill body from the strongest retrieve-and-rerank pipeline dropped Hit@1 from 68.0% to 24.0%, and the paper reports body-access effects of 37 to 44 percentage points across model configurations per the SkillRouter paper.

That result is about large catalogs, not two-job files, and the authors are careful to call it a benchmark finding rather than a universal law. The practical takeaway for you is narrower but real: selection quality depends on more than a short label, and the cost of a bad selection is paid downstream.

The catalog-level failure is the one that surprises teams. A new skill can break an old one without editing a line of it, because installing a skill moves the decision boundary around every neighboring skill. A Google Cloud community write-up demonstrates the case where an incident-triage skill and a newly installed Kubernetes-diagnostics skill both plausibly match a single production request, and the more lexically similar skill wins even though the original had the right workflow per the catalog reliability article.

That is why the split is not finished when the second file exists. It is finished when both new descriptions pass their own trigger eval and the neighbors still pass theirs.

A split that produces two vague descriptions has made things worse: now there are two candidates for every ambiguous request. Four rules keep them apart.

Name the object, not the activity. "Reconciles vendor invoices against purchase orders and flags line-level mismatches" separates cleanly from "summarizes financial statements into a monthly narrative." Both verbs are activities, but the nouns never overlap.

State the boundary explicitly. A sentence like "Use this skill for reconciliation and mismatch flagging, not for summarizing statements, which has its own skill" is cheap and prevents most of the confusion. The spec's description field allows up to 1,024 characters, so there is room per the optimizing descriptions guide.

Use imperative phrasing. "Use this skill when..." beats "This skill does..." because the model is deciding whether to act per the optimizing descriptions guide. Anthropic's authoring guide adds the same instruction and notes the description should carry both what the skill does and when to use it per the skill authoring best practices.

Test the pair, not the individual. Concatenate both eval sets and run every request against the full catalog. A request that should trigger neither skill but triggers one is the failure mode you are hunting.

Keep the shared parts shared. If both skills need the same reference file, the same validation script, or the same output format, put those in the skill body twice, or better, in a script or reference file both bodies point at. Duplication in prose is how the two descriptions drift back together six months later.

If you maintain a skill library across several agents and want it installed and versioned in one place, the Quanta skills library is the natural next step: https://quantaintelligence.ai/skills.

The rule above answers "should I split?" It does not answer "into how many?" There is a case against splitting at all, and it is worth stating because the reflex to modularize can be expensive.

Red Hat's write-up summarizes research on the question of one big skill versus many small ones, and reports the evidence points toward "less is more" for comprehensiveness: broad skills that try to address everything are the problem, not the goal per Red Hat's skill development write-up. Read that carefully. "Less is more" argues for narrow skills, which supports splitting, but it also argues against accumulating a skill for every micro-task, which would give you forty files and forty descriptions competing for selection.

The balance is a rule of thumb: split when the two jobs have different triggers, different step orders, or different owners. Do not split when the second job is a single step inside the first, when the two jobs are always performed together in sequence, or when the second job's instructions fit in three lines. A three-line addition does not justify a new entry in the routing pool, and every entry adds to the selection problem described above.

There is also a durability question. Red Hat distinguishes capability skills, which patch gaps the base model has, from preference skills, which encode how your team works. Capability skills tend to deprecate as models improve; preference skills last per Red Hat's skill development write-up. A split driven by a format conversion the model now handles natively is a split you will undo. A split driven by two distinct workflows your team actually runs is a split worth the maintenance.

Finally, remember what the two artifacts are for. A skill is not the only customization mechanism. Custom instructions apply always or by glob and define coding standards, while skills are task-specific and loaded on demand per the VS Code agent skills documentation. If one half of your skill is really "how we name things in this repo," it belongs in AGENTS.md or custom instructions, not in a second skill. The Agentic AI Toolkit comparison draws the same line between connectivity via MCP, packaged expertise via skills, and behavioral guidance via AGENTS.md per the agentic toolkit overview.

Use this before and after the edit.

The last row matters more than it looks. Shared prose is where the two skills start converging again, and convergence is how you end up back at a two-job file.

If you would rather not run this loop yourself, an expert that reads your repo and hands back the restructured skill and the eval set is a reasonable shortcut: https://quantaintelligence.ai/agents.