Skills vs Sub-Agents in Claude Code - When to Use Each Pattern

Fazm Team··2 min read

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:

  1. 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.
  2. 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.

More on This Topic

Related Posts