Reusable Patterns for Structuring Claude Code Skills

After you have built a handful of Claude Code skills, you start noticing that the good ones share a shape and the bad ones share their failure modes. The difference is rarely the model — it is how the skill structures its instructions, divides labor between prose and code, and manages the context it pulls in. This post collects the reusable patterns that separate skills which fire crisply and produce consistent output from skills that drift, bloat, or quietly misbehave.

Pattern: the thin description, the thick body

The strongest structural pattern is to keep the description razor-thin and trigger-focused while the body carries all the weight. The description's only job is routing, so it should contain the activating nouns and verbs and nothing else — no tutorials, no caveats. The body, by contrast, can be generous: numbered steps, decision branches, examples of good and bad output. Mixing these concerns is the most common anti-pattern; descriptions that try to teach end up neither triggering well nor instructing well.

A practical test: read the description alone and ask "could I tell from this exactly when to reach for the skill?" Then read the body alone and ask "could a competent stranger follow this without guessing?" When both pass independently, the skill is structured right. When you find yourself wanting to put procedure in the description or trigger logic in the body, that is the signal to refactor.

Pattern: separate the deterministic from the judgmental

Every non-trivial skill mixes two kinds of work: deterministic operations a script does perfectly, and judgment calls only the model can make. The reusable pattern is to draw a hard line between them. Hand the model structured, trustworthy data from a script, and reserve its tokens for the decisions — which items matter, how to phrase the summary, what the user probably meant. The diagram captures how a well-structured skill routes a task across this line.

flowchart TD
  A["Skill activated"] --> B{"Step is deterministic?"}
  B -->|Yes| C["Run bundled script"] --> D["Emit structured JSON"]
  B -->|No| E["Model applies judgment"]
  D --> E
  E --> F{"Need external data?"}
  F -->|Yes| G["Call MCP tool"] --> E
  F -->|No| H["Compose final output"]
  H --> I["Return result to user"]

This pattern pays off twice. It makes output reproducible, because the numeric and structural parts come from code that does not vary. And it makes the skill cheaper, because the model reasons over compact structured input instead of re-deriving facts from raw text every run. When a skill feels unreliable, look first for judgment work that should have been deterministic.

Pattern: load resources lazily with pointers

A skill body should not inline a large reference document; it should point to one. Keep the lengthy style guide, the schema, or the lookup table as a separate file in the skill folder, and have the body say "when you need the field definitions, read schema.md." This mirrors how Claude Code itself works — metadata first, detail on demand — and it keeps the always-loaded body small. A bloated body that inlines everything defeats progressive disclosure inside your own skill.

The pointer pattern also lets one resource serve several skills. A shared brand-voice.md can be referenced by every content skill, so you update tone in one place. Treat bundled resources like modules you import, not text you paste, and your skill library stays maintainable as it grows from three skills to thirty.

Pattern: encode the local, trust the general

The model arrives knowing an enormous amount about programming, writing, and common formats. A skill earns its keep by encoding what the model cannot know — your taxonomy, your conventions, the quirk that finance tickets route differently, the fact that dates in this export are day-first. The reusable discipline is to ruthlessly cut any instruction that merely restates general knowledge and keep only the local, specific, surprising details. Every sentence in the body should be something the model would otherwise get wrong.

This keeps bodies short, which keeps triggering fast and execution focused. It also makes skills more robust across model upgrades: as base models improve at general tasks, your skills do not rot, because they never relied on encoding general knowledge in the first place. They encode the part that is yours, which does not change when the model does.

Pattern: compose, don't conglomerate

When a procedure grows large, the temptation is to stuff it all into one mega-skill. The better pattern is composition: small, single-purpose skills that can each trigger independently, with one orchestrating skill that calls out to the others by describing the sub-tasks. This mirrors good function design — small units with clear contracts beat one sprawling routine. Each small skill stays easy to test, easy to trigger precisely, and reusable in contexts the mega-skill never anticipated.

Composition also plays naturally with subagents. An orchestrating skill can instruct Claude Code to spawn a subagent per sub-task, each loading the relevant small skill in its own context window. The result scales: you add capability by adding small skills, not by growing one fragile monolith whose description has to match a dozen unrelated situations at once.

Frequently asked questions

What goes in the description versus the body?

The description holds only routing signal — the nouns and verbs that say when to use the skill. The body holds the procedure: numbered steps, decision branches, edge cases, and examples. Keeping these concerns separate is the core structural pattern.

How do I keep a skill's context cost down?

Inline only the local, specific knowledge the model cannot already have, point to large reference files instead of pasting them, and push deterministic work into bundled scripts. This keeps the always-loaded body small and the per-run token cost low.

When should I split one skill into several?

Split when a single skill's description has to cover several unrelated triggers, or when its body branches into clearly distinct procedures. Small single-purpose skills trigger more precisely, test more easily, and compose under an orchestrating skill.

How do I stop skills from rotting as models improve?

Encode only what is specific to your domain and never restate general knowledge. Because your skills rely on local conventions rather than facts the model already knows, base-model upgrades improve them rather than breaking them.

Bringing agentic AI to your phone lines

These same structuring patterns power CallSphere's voice and chat agents: thin routing, deterministic tools, and judgment kept where it belongs, so every call is answered and booked correctly 24/7. See the patterns in action at callsphere.ai.