With 30+ skills, you face a systems design problem: how do you make the right skill fire at the right time without drowning your agent in context or yourself in memorization? This lesson covers the invocation tradeoff, context budgeting, and the art of writing descriptions that route correctly.
Cost: Context load — the skill's description lives in the system prompt on every turn, whether needed or not. With 30 model-invoked skills averaging 50 words each, that's 1,500 words of descriptions consuming context before the conversation even starts.
Benefit: The agent fires the skill when appropriate without the human needing to remember it exists.
Good for: Skills the agent needs mid-task — code-review during implementation, diagnose during debugging, ponytail during any build task.
Cost: Cognitive load — you must remember the skill exists and know when to use it. It's invisible to the agent otherwise.
Benefit: Zero context cost. The skill is loaded only when explicitly called. Your context window stays clean.
Good for: Skills that represent deliberate human actions — handoff (session management), teach (pedagogical mode), grill-me (stress testing), ask-the-board (advisory).
Let's do the math. Your system prompt includes a list of all model-invoked skills with their descriptions. Each description is the only thing the agent sees when deciding whether to load a skill.
| Scenario | Skills | Avg Description | Context Cost | Impact |
|---|---|---|---|---|
| Conservative | 10 model-invoked | 40 words | ~400 words | Manageable |
| Moderate | 20 model-invoked | 50 words | ~1,000 words | Noticeable |
| Aggressive | 35 model-invoked | 60 words | ~2,100 words | Significant — 5-10% of usable context consumed by skill routing alone |
Every model-invoked skill must justify its per-turn context rent. If the agent wouldn't autonomously reach for a skill in normal workflow, make it user-invoked. The skill still exists — it just doesn't occupy space until called.
Early skill systems used "Commands" vs "Skills" as categories — an implementation distinction (slash-command vs auto-loaded). The better taxonomy is invocation mode: who decides when it fires?
| Old Taxonomy | New Taxonomy | What Changed |
|---|---|---|
| Command (slash-triggered) | User-Invoked | Same mechanism, better framing — focuses on who initiates |
| Skill (auto-loaded) | Model-Invoked | Clarifies the cost: you're paying context rent |
| — | Router | New category: one entry point that maps to many |
Ask one question: "Does the agent need to reach for this autonomously during a task?"
| If yes → Model-Invoked | If no → User-Invoked |
|---|---|
| code-review (during implementation) | handoff (deliberate session end) |
| diagnose (during debugging) | teach (pedagogical mode switch) |
| ponytail (during any build) | grill-me (stress-test a plan) |
| assess (during exploration) | ask-the-board (advisory consultation) |
| write-a-skill (meta-authoring) | |
| today (daily planning ritual) |
A router skill is a single user-invoked entry point that maps to multiple sub-skills. It reduces cognitive load (remember one name instead of many) while keeping context cost low (only loads what's needed).
The ponytail family is a natural router cluster: one concept (simplicity), multiple applications. The user remembers "ponytail" and the agent routes to the right variant based on context.
For model-invoked skills, the description is everything. It's the only text the agent sees when deciding whether to load your skill. Bad wording means the skill never fires, or fires too often.
code-reviewAnalysis: Clear trigger ("user wants a code review"). Names the principles it checks — helps the agent decide if this is the right tool vs a generic review. Concise (26 words).
Verdict: ✅ Good — fires when appropriate, stays quiet otherwise.
ponytailAnalysis: Highly specific triggers (9 phrases). The agent knows exactly when to fire. But at 67 words, it's paying significant context rent.
Verdict: ⚠️ Trade-off — the specificity is valuable, but consider whether 5 trigger phrases would route just as accurately as 9.
assessAnalysis: Has disable-model-invocation: true — it's user-invoked despite having a description. The description serves human discovery (reading the skill list), not agent routing. Zero context cost.
Verdict: ✅ Correct invocation mode — "assess this codebase" is a deliberate human action, not something the agent should do unprompted.
Every split adds either context load (if model-invoked) or cognitive load (if user-invoked). Every merge makes the resulting skill harder to maintain and its description harder to write precisely.
| Split when... | Merge when... |
|---|---|
| The workflows are genuinely different (different steps, different outputs) | You hesitate about which to invoke |
| The triggers are distinct and non-overlapping | They share 50%+ of their steps |
| The skill exceeds 100 lines and has distinct domains | One is a strict subset of the other |
| Different invocation modes are needed (one model-invoked, one user-invoked) | Maintaining both costs more than maintaining one |
Here's how a real 30+ skill portfolio breaks down by invocation mode, with reasoning:
| Skill | Mode | Rationale |
|---|---|---|
| code-review | Model | Agent should apply during implementation without being asked |
| ponytail | Model | Simplicity mode should activate on trigger phrases mid-task |
| diagnose | Model | Agent should shift to diagnosis mode when hitting errors |
| architect | User | Design is a deliberate activity — the user knows when they want architecture |
| handoff | User | Session management is a human decision |
| grill-me | User | Stress-testing is opted into, never imposed |
| teach | User | Pedagogical mode is a deliberate switch |
| assess | User | "Evaluate this" is a deliberate request, not mid-task |
| ponytail-help | Router | Entry point to the ponytail family |
trail-map.html — Field Guide → Invocation axis — The full taxonomy with decision trees for model-invoked vs user-invoked routing, plus the router skill pattern.