Skills vs Sub-Agents in Claude Code - When to Use Each Pattern
Skills vs Sub-Agents in Claude Code - When to Use Each Pattern
Once you have 10+ Claude Code skills, you hit an organizational question: should this be a skill or a sub-agent? The distinction matters because it affects how context flows, how errors propagate, and how composable your setup becomes.
What Skills Are Good For
Skills are self-contained instruction sets that run in the main agent's context. They are best for:
- Repeatable procedures - deploying, publishing, sending emails
- Template-driven tasks - generating boilerplate, formatting output
- Tool configurations - setting up specific MCP servers or API integrations
Skills excel when the task is well-defined, the inputs are clear, and the agent does not need to make complex decisions. Think of them as functions - they take input and produce output.
What Sub-Agents Are Good For
Sub-agents run as separate Claude instances, often via the Task tool. They are best for:
- Research and analysis - tasks that require independent exploration
- Parallel work - multiple agents working on different parts simultaneously
- Isolation - tasks where you do not want the main context polluted with intermediate work
Sub-agents excel when the task requires judgment, exploration, or when you want to run multiple things in parallel without context interference.
The Decision Framework
Ask two questions:
- Does this need its own context window? If the task generates a lot of intermediate output that the main agent does not need, use a sub-agent.
- Is the procedure fixed or exploratory? Fixed procedures are skills. Exploratory tasks are sub-agents.
Splitting by Type
A practical split for a mature setup:
- Skills: deploy, publish, email, format, generate, post
- Sub-agents: research, audit, review, test, debug
The pattern that emerges is skills for actions and sub-agents for analysis. Actions follow known steps. Analysis requires discovering the steps.
Common Mistakes
Do not put complex decision logic in skills - they become fragile. Do not use sub-agents for simple tasks - the overhead of spinning up a new context is wasted. And do not mix both patterns in one workflow without clear handoff points.
Fazm is an open source macOS AI agent. Open source on GitHub.