Tool, Skill, or Subagent? Structuring Claude Code Agents That Scale

Every agent that survives contact with real requirements eventually rots the same way. You ship something that works, then bolt on capability after capability until the system prompt is 400 lines, there are a dozen tools, a handful of subagents, and performance quietly degrades. The fix isn’t a smarter model. It’s knowing which agentic primitive to reach for, and when.

Anthropic’s own engineers describe exactly this failure mode, and their decision framework for tools vs skills vs subagents is the clearest I’ve seen. It matches what I’ve learned running the agent pipelines behind Geonimo, so here it is, in the order you should actually reach for things.

Start with human-like primitives

When you build an agent, start with the same primitives a person has at a desk: a file system, the ability to write and run code, web search, a to-do list. That’s the insight behind Claude Code, it’s not a thousand bespoke tools, it’s Claude given access to a computer. The payoff compounds: as better models ship, they use those same primitives more effectively, no rewrite required.

Code execution is the standout. If your agent needs to reason over a big CSV, don’t dump the whole thing into context, give it a bash tool and let it write a quick script. One real example cut token usage from over 200,000 to a fraction of that, with lower cost and latency, just by letting the agent compute instead of “reading” everything into its head. Start with primitives, remove the ones you don’t need, and only then add custom tools.

Use skills for progressive disclosure

The most common mistake is stuffing every policy and procedure into the system prompt. It grows to hundreds of lines, contradicts itself, and confuses the model, the cause of a lot of “the model hallucinated” bugs that are really context bugs. Skills fix this. A skill is packaged, composable information the model pulls into context only when it realizes it needs it. Move your forecasting guidelines, your brand rules, your testing process into skills, and the system prompt shrinks to the handful of things the model needs every time.

In one walkthrough this took a 400-line system prompt down to about 15, with the business logic relocated into skills, and eval scores climbed as a direct result. This is the same idea as the “directives” in my outbound system: encode the judgment once, load it on demand.

Use subagents for exactly two jobs

Subagents are powerful and over-reached for. There are really only two cases where they earn their complexity:

Outside those, be skeptical. The hidden cost of subagents is communication: getting the hand-off between an orchestrator and its subagents right is hard, and a breakdown there is a classic, hard-to-debug failure. Frontier models can now hold more in a single context than they used to, so a lot of what used to need a subagent can just live in the main agent.

Custom tools next, MCP last

Only after primitives and skills should you add custom tools, and only for capability the primitives genuinely can’t cover. MCP comes last. It’s tempting to run toward MCP first, but you usually end up with a sprawl of overlapping servers that pollute context. Reserve it for when multiple agents or clients need the same standardized, governed set of tools. Increasingly, the leaner move is to let the agent call CLIs and APIs via code execution rather than wiring up an MCP server at all.

Measure it: hill-climb on evals

None of these decisions are guesses. The way to make them is to baseline your agent on a set of evals, change one thing, the architecture, the skills, the tools, and rerun, keeping what improves. Track both the deterministic metrics (turns, latency, tokens) and the fuzzy ones (tone, output quality, via an LLM judge). In the example I’m drawing on, this loop took an agent from a failing 62% to about 92%, mostly by simplifying: fewer tools, a short prompt, logic in skills. The discipline is the same one I bring to the systems I build: simplify, measure, repeat.

This is how I keep agents reliable in production. See the related habits Anthropic’s team uses and the prompting playbook, or get in touch if you want help building this way.