Claude Skills vs Sub-agents: Architecture, Use Cases, and Effective Patterns

Sandeep Thuthike — Wed, 07 Jan 2026 16:17:58 +0000

Claude Code Orchestration: Mastering Skills and Sub-agents

Building scalable workflows in Claude Code requires moving past basic chat interactions and treating the CLI as a coordination layer. The platform provides two primary primitives for this: Skills and Sub-agents.

Skills act as your persistent, filesystem-based documentation that dictates how work should be done, while Sub-agents are the execution engines that actually perform the work, often in parallel. By combining these, you shift from micro-managing every line of code to orchestrating a fleet of specialized processes that adhere to your specific engineering standards.

Skills: Encoded Procedural Knowledge

Skills are not just prompts; they are persistent, deterministic blocks of expertise that you bake into your environment.

Why they matter

Token Efficiency: Skills use progressive disclosure. Only the name and description load at startup, with the full content pulled in only when the task requires it.
Consistency: A skill ensures that whether you’re working on a feature today or six months from now, the coding conventions and review checklists remain identical.

What to turn into a Skill

If a process is repeatable and requires a specific output format, it belongs in .claude/skills/.

API design standards (REST vs. GraphQL conventions)
PR review checklists
Project-specific testing patterns
Deployment procedures

Sub-agents: Dynamic Task Delegation

Sub-agents are ephemeral instances spawned to solve a specific problem. With the rollout of async sub-agents, we can now move toward true parallel execution.

The ideal use case

Sub-agents excel at tasks that are resource-intensive or require isolated context.

Parallel Refactoring: Refactoring three independent modules at once.
Exploratory Work: Testing a library migration in a sandbox-like state without polluting the main agent's working memory.
Decomposition: Breaking a large feature into backend, frontend, and testing tracks.

The Decision Framework

Scenario	Use This	Rationale
Pattern repeats across sessions	Skill	Amortize the encoding cost; maintain standards.
Task is unique or one-time	Sub-agent	Not worth the overhead of a permanent skill.
Context efficiency is critical	Skill	Progressive disclosure saves tokens.
Work can be parallelized	Sub-agent	Concurrency saves human time.

Orchestration Patterns that Actually Work

1. Skill-Guided Sub-agents

Never spawn a sub-agent without guidance. If you tell a sub-agent to "refactor this module," you will often get inconsistent results. Instead, have the parent agent load your code-standards skill and pass those constraints to the sub-agent. This ensures parallel work does not drift from your codebase's style.

2. The Orchestrator/Specialist Model

Use the main agent as a coordinator. Spawn one sub-agent with a security-audit skill for analysis, then another with a framework-patterns skill for implementation. This creates a specialized pipeline rather than one agent trying to perform every phase of the lifecycle within a single context.

Anti-Patterns to Avoid

Sub-agents for trivialities: Do not spawn a sub-agent to rename a variable or add a null check. The overhead of spawning and integration exceeds the benefit.
Skills for one-offs: If you are doing a one-time migration from Postgres to Mongo, do not write a skill for it. Just provide the requirements to a sub-agent and move on.
Ignoring CLAUDE.md: Your CLAUDE.md should define when and how these tools are used. If the agent does not know your skills exist or when to delegate, it will default to a single-threaded, inefficient workflow.

Project Structure

A professional Claude Code setup should look like this:

.claude/  
├── CLAUDE.md           \# High-level orchestration rules  
└── skills/  
    ├── api-review/  
    │   └── SKILL.md    \# Reusable REST standards  
    ├── test-gen/  
    │   └── SKILL.md    \# Vitest/Jest boilerplate logic

Stop manually guiding the AI through every file. Encode your standards as skills, delegate the heavy lifting to sub-agents, and focus on the architecture.

DEV Community: Sandeep Thuthike