Skills, Subagents, and the Orchestrator Pattern: The Layer Most Teams Confuse

I had a conversation with a tech lead at a client last quarter that crystallized why this article needed to exist. They had spent three weeks building what they called “their agent fleet,” six custom agents for different parts of their codebase, with bespoke prompts, careful naming, the works. We sat down to look at why they could not figure out how to run two of them in parallel.

The answer was that they had not built agents. They had built six skills. All living inside one Claude Code session, all loading into the same context window when their descriptions matched. By the time the third one was active, the context was past 150K tokens and quality was degrading. Running two of them at once was not a thing because they were not separate processes. They were paragraphs in the same prompt.

The conceptual gap cost them three weeks. The rewrite, once we named the primitive correctly, took two days. The system was much smaller after we were done, and it ran in parallel for the first time.

This article is the layer most teams confuse, written so you do not have to lose those three weeks.

The three layers. Tools, MCPs, Skills.

Before skills versus subagents, the layer that gives both of them context. Claude Code (and any modern coding agent) operates on three orthogonal layers, and most teams have only really internalized one of them.

Tools are verbs. They are what the agent can physically do, there’s some questions, for example:

• Read a file.
• Write a file.
• Edit a file.
• Run a bash command.
• Search with grep.
• Glob a path.
• Fetch a URL.
• Search the web.

These are built into the agent. You do not configure them. You allow or restrict them.

MCPs are external connections. The Model Context Protocol is an open standard Anthropic introduced in November 2024 and has since been adopted by OpenAI, Google, Microsoft, Cursor, and most agent surfaces. In December 2025, Anthropic donated MCP to the Agentic AI Foundation under the Linux Foundation.

Anthropic-reported adoption: 97 million-plus monthly SDK downloads and 10,000-plus active MCP servers. MCP is the layer that connects your agent to your production database, Datadog, Sentry, GitHub, Slack, Jira, and anything else with an API.

Skills are recipes — folders of markdown that tell the agent how to do a specific kind of work well in your context: when to write a Postgres migration this way and not that way, how to structure a spec at this company, what “code review” means when this particular team does it. They are the institutional knowledge of your team, version-controlled and tool-agnostic.

The three layers are independent. Most teams I see have figured out tools (they ship features), have plugged in two or three MCPs (usually GitHub and a database), and have done almost nothing on skills. Skills are where the highest-leverage investment is for most teams in 2026.

Read more: The Three Eras of Software: From Autocomplete to Agentic Development

What a skill actually looks like

A skill is a folder. At minimum it contains a SKILL.md with two YAML frontmatter fields: name and description. That is the only required content. Optionally, the folder can include references/ (additional markdown loaded on demand), examples/ (concrete examples the agent reads when relevant), and scripts/ (executable code the skill can call).

The mechanic that makes skills cheap is what Anthropic calls progressive disclosure, and it is on the official skills docs. Three levels of loading.

Level one is the frontmatter. Just the name and description. This is in the agent’s system prompt all the time, in every session. Claude reads only this when deciding whether to invoke the skill. A description like “when the user wants to plan a Postgres migration” is what tells the agent “this skill is relevant to this task.” Get the description wrong and the skill never gets used.

Level two is the body of SKILL.md, loaded only when the skill is activated. Anthropic recommends keeping this under 500 lines — past that, you are pushing the agent’s working memory and the skill stops being cheap to run.

Level three is the references/ files. Loaded only when the body of the skill points to them. This is how you carry deep reference material (a 2,000-line database conventions doc, say) without paying its context cost on every task that touches the database. The agent fetches it only when it needs it.

Skills follow a four-level hierarchy: Enterprise, User, Project, Plugins. Same hierarchy as CLAUDE.md, which is intentional. Skills work across agent surfaces too. The same SKILL.md runs in Claude Code, Cursor, Codex CLI, OpenCode, and Copilot CLI. That portability is part of why skills are the layer you should invest in over surface-specific prompts.

Ready-made packs worth knowing

I do not love when engineering teams build everything from scratch. Skills are an area where the community has shipped a lot of useful work, much of it free, and forking is usually the right move.

Superpowers is the largest community-built skill pack, authored by Jesse Vincent (obra). On January 15, 2026 it was accepted into Anthropic’s official Claude Code plugin marketplace, which is roughly the open-source equivalent of getting endorsed.

It ships skills for brainstorming, test-driven development, systematic debugging, subagent-driven development with code review, and skill authoring itself (yes, a skill that writes skills).

Install with /plugin install superpowers@claude-plugins-official. Works across Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI, and OpenCode.

GStack is Garry Tan’s pack, shipped on March 12, 2026 under MIT. Garry Tan is President and CEO of Y Combinator, and GStack is opinionated in a way that reflects YC’s view of a startup engineering team. Twenty-three specialists modeled as personas (CEO, Designer, Engineering Manager, Release Manager, Doc Engineer, QA Lead, Chief Security Officer, others) plus eight power tools.

The loop the pack enforces is Think, Plan, Build, Review, Test, Ship, Reflect. Useful for small teams that want a strong opinion on workflow without writing one themselves.

Tech Leads Club agent-skills is a pack built by a Brazilian engineering community, MIT-licensed, on npm at @tech-leads-club/agent-skills. The flagship skill is tlc-spec-driven which implements the Specify, Design, Tasks, Execute workflow with adaptive depth.

Other skills in the pack include skill-architect, subagent-creator, create-technical-design-doc, handoff, and diagnose. Install interactively with npx @tech-leads-club/agent-skills or per-skill with agent-skills install -s tlc-spec-driven.

The pattern across all three is the same. Do not build from scratch what someone has already shared. Fork the pack, customize the parts that need to fit your context, contribute back if you can.

Read more: Spec-Driven Development: How to Capture Intent Before You Burn Tokens

Subagents are different

This is where most teams trip. The anatomy of a subagent looks identical to a skill on paper: a markdown file with frontmatter. The behavior is structurally different.

The official Anthropic docs state it plainly. “Each subagent starts with a fresh, isolated context window. It does not see your conversation history, the skills you’ve already invoked, or the files Claude has already read.” That sentence is the whole point. A subagent is a separate process with its own context, its own tools, its own model, and its own permissions.

Four practical differences from skills.

• Context: A skill injects content into the parent agent’s window. A subagent runs in a fresh, isolated window of its own. This is the difference that matters most. If two tasks need to run without interfering with each other’s working memory, they have to be subagents.
• Model: A skill inherits the parent’s model. A subagent specifies its own. You can run an Opus orchestrator coordinating Sonnet implementers and a Haiku formatter. You cannot do that with skills.
• Tools: A skill can declare allowed-tools to restrict what tools the parent agent uses while the skill is active. A subagent has its own tool set, granted explicitly at definition time. You can build a subagent that only has read access and grep, for example, a safe “researcher” subagent that physically cannot edit files.
• Parallelism: Skills are not parallel. They are paragraphs in the same prompt. Subagents are parallel by default. The parent agent can spawn five subagents in a single tool call and they run concurrently.

The rule of thumb I use is mechanical: if the same instruction will be reused across many tasks and does not need its own context, write a skill; if the work needs its own isolated window, its own model, or its own tool restrictions, spawn a subagent. Skills are how-to. Subagents are who-does-it.

The orchestrator and specialists pattern

This is the architectural pattern that makes era-three coding actually scale, and it is the reason getting the skills-vs-subagents distinction right matters.

The shape is one orchestrator agent, typically running on a stronger model (Opus 4.7 in the May 2026 lineup), that coordinates several specialist subagents running in parallel on a faster, cheaper model (Sonnet 4.6).

A typical feature might have a backend specialist, a frontend specialist, an infra specialist, and a product manager specialist, each working in its own context, each producing its own output. Downstream of the specialists, a reviewer subagent reads the combined diffs. The human gates after the reviewer.

The reason this works is the same reason a real software team works. Each specialist has clean context. Nobody’s working memory is polluted by what another specialist is doing. The orchestrator owns the coordination and the contract between the pieces. The reviewer owns the integration check.

Boris Cherny at Anthropic, in Mastering Claude Code in 30 Minutes, describes shipping 20 to 30 pull requests a day this way. Five parallel Claude instances, each running in a separate terminal tab with its own checkout, each started in plan mode so the plan can be reviewed before the implementation goes wide. That routine is not possible if your “agents” are skills sharing one context window. It requires real subagents in real worktrees.

Worktrees. The unsexy enabler.

Worktrees deserve their own paragraph because they are the mechanic that makes parallel subagents safe.

Git worktrees let you have multiple working directories on different branches of the same repository, all without copying the repo. Claude Code supports them natively through the –worktree (or -w) flag. claude –worktree feature-x creates a new worktree at .claude/worktrees/feature-x/ on a new branch worktree-feature-x and starts a session inside it. The session is isolated from your main checkout. Another session running with –worktree feature-y does not interfere.

Why does this matter. Because parallel subagents need somewhere to safely write files. Two subagents editing the same working directory at the same time is a recipe for merge hell and file-stomping. Two subagents each working in their own worktree, on their own branch, with their own ignored files (.worktreeinclude controls what gets symlinked back), is a clean separation that lets the orchestrator coordinate the merge upstream.

If you are running anything more than a single agent at a time, worktrees are not optional. They are how you avoid the parallel-write disaster that ends a lot of teams’ experiments with multi-agent coding.

How to configurate your agents

Four moves, in order.

1. Audit your existing “agents.” For each one, ask: does this need its own context, its own model, its own tool restrictions, or to run in parallel with another? If no to all four, it is a skill. Most of what teams have built as agents turn out to be skills mislabeled. Renaming and reorganizing is usually a one-day task and clarifies the architecture immediately.
2. Install a community pack. Pick one: Superpowers, GStack, or Tech Leads Club agent-skills. Use it for a week as-is. The point is to learn the shape of a well-built skill before you try to write your own. Forking what others built also means you do not waste a sprint reinventing brainstorm, debug, or TDD primitives that already exist.
3. Stand up one orchestrator with two specialists on a real feature. One backend specialist, one frontend specialist, both as subagents, each in its own worktree, coordinated by a parent orchestrator. Sonnet 4.6 for the specialists, Opus 4.7 for the orchestrator. Pick a feature small enough to ship in a day. The point is not the feature. The point is your team’s first real run at the pattern.
4. Commit your skills to the repo. Every skill the team writes goes in .claude/skills/ (or the equivalent for your tool) and gets versioned like code. Pull requests review skills the way they review tests. Knowledge that lives in skills is knowledge that survives turnover.

Conclusion

The pattern that wins in 2026 is not buying everyone a Claude Code license — it is building the right primitives so engineers can ship in parallel. Skills are the recipes, subagents are the workers, the orchestrator coordinates, and worktrees keep the parallelism safe. Each primitive does one job. Most teams have not split them apart yet.

That separation is what the next year of architecture work is going to be about. The teams that figure it out first will ship at five to ten times the rate of the teams still running one agent at a time in a single context window. Not because their model is better. Because their primitives are.

This is the work we do at Cheesecake Labs every day. We help engineering teams move from “we use Claude Code” to “we have an agentic system”: versioned skills, named subagents, orchestrator patterns, worktrees, the whole stack.

If your team is running agents but cannot figure out why parallelism is not working, reach out. The diagnosis is usually one of the four primitives being conflated with another, and the fix is faster than the conversation about whether it is worth doing.