A decision framework for routing tasks across Claude Code's three execution modes — direct prompt, single subagent, or agent team — built and battle-tested in a Java enterprise codebase.
Most Claude Code tutorials answer "how do I prompt the AI to do X". The harder question, and the one that actually decides outcomes in a team setting, is:
"Should this task be a direct prompt, a subagent, or a coordinated agent team — and which agents?"
Get this wrong and you either (a) burn tokens and wall-clock time dispatching agent teams for trivial changes, or (b) hand single-shot prompts to tasks that needed structured investigation. Both are failure modes I've watched a team fall into.
This repo documents the routing skill I use daily, plus the catalog of specialized subagents it dispatches.
| Path | What it is |
|---|---|
skills/route.md |
The route skill — a meta-skill that classifies a task and recommends the cheapest execution mode that solves it |
agents/README.md |
Catalog of 11 specialized subagents the routing skill dispatches |
agents/templates/ |
Sanitized prompts of 3 of the most universal agents (refactor-advisor, code-reviewer, debugger) — starting points to adapt |
examples/ |
Concrete cases: tasks that ended up as direct prompts, subagents, or teams (with reasoning) |
docs/adapting.md |
How to port this framework to a different stack |
Files touched?
|
+-------------+-------------+
| | |
1-3 files 4-10 files 10+ files
| | |
Complexity? Modules? Agent Team
/ \ / \
Low High One Multiple
| | | |
Direct Sub- Sub- Agent
prompt agent agent Team
Rule of thumb: pick the simplest mode that solves the task. Don't escalate to an agent team for what a subagent resolves, nor a subagent for what a direct prompt resolves.
I lead AI adoption on a developer team working over a Java enterprise codebase with years of history — multi-tenant, multi-module, with legacy conventions a generic LLM gets wrong. After a few months of daily use, three things became obvious:
- The same task type kept reappearing. Routing decisions stopped being judgment calls and became a pattern.
- The cost of dispatching a team for a trivial change (slower, more tokens, more coordination overhead) was visible enough to want to systematize avoiding it.
- A team of 6 devs needs shared mental models for when to call which subagent, otherwise everyone wastes the same tokens learning the same lessons.
route is the codification of that. It runs as a skill, takes a task description, and returns: classification, recommended mode, suggested agents (if applicable), and a ready-to-paste prompt.
- If you use Claude Code on a non-trivial codebase: copy
skills/route.mdinto~/.claude/skills/route/SKILL.md, adapt the agent list to your actual subagents, and invoke it with/route <task description>. - If you're building your own subagents:
agents/README.mdis a catalog model — use it as a template for what a clear agent description looks like (responsibility, when to dispatch, when not to). - If you're skeptical of agent teams: read the section in
skills/route.mdon when not to escalate. Most "I want a team" instincts dissolve under that filter.
- Not a Claude Code tutorial. Read Anthropic's docs first.
- Not a generic agent library. Agent prompts here are described by responsibility, not pasted in full — the prompts themselves are tied to a specific Java enterprise codebase and wouldn't transfer cleanly.
- Not a finished product. This is a working artifact from real daily use; expect rough edges and opinions over polish.
MIT. Take it, fork it, adapt it. If you build a better version, ping me on LinkedIn — I want to see it.