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

Matthew Diakonov··2 min read
claude-codeskillssub-agentsarchitecturedeveloper-workflow

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

Making Claude Code Skills Repeatable - 30 Skills Running Reliably

Running 30 Claude Code skills reliably for a macOS agent. The key to repeatability is explicit frontmatter, narrow scope per skill, and clear input/output

Claude Code Writes Your Code, but Do You Know What's in It?

AI coding agents restructure modules in unexpected ways. The code works but the architecture drifts from your mental model unless you actively review

The Coolest AI Coding Setup Uses Skills, Hooks, and Automation Triggers

The best AI coding setups are not about hardware. They use Claude Code skills as reusable automation modules and hooks as deterministic triggers - here is how to build yours.

How did this page land for you?

React to reveal totals

Comments ()

Leave a comment to see what others are saying.

Public and anonymous. No signup.