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.
Top comments (0)