TL;DR: When AI agents land on a team where roles already blur, the instinct is to spawn a new agent for every task — and two weeks later you have eleven agents nobody can govern. Treat agents as teammates and skills as the verbs they use. Five small choices around roles, scope, hooks, files, and dissent keep the roster sane. Setup is cheap. Taxonomy is expensive.
Most teams don't fit cleanly into the org chart. A PM writes SQL. An engineering manager ships code on Friday afternoons. A designer prototypes in React. An analyst owns a feature flag. The work doesn't match the boxes, and people have quietly agreed not to mention it.
So when Claude Code lands in a team like that, the first instinct is to spin up an agent for every task. A code reviewer. A spec writer. A debugger. A meeting summariser. A weekly update bot. Two weeks in, you have eleven agents. Half of them overlap. Nobody can describe the roster to a new joiner in one sentence.
Don't.
Each agent file is a job description. If you wouldn't write that job description for a person, don't write it for an agent.
Here is a cleaner way to think about it:
Agents are teammates. Skills are the things they do.
An engineer is an agent. Code review, debugging, drafting a PR description — those are skills the engineer uses. The test is simple: could a real person hold this title for years? "Designer" passes. "Component renamer" fails. That's a skill, not a role.
Why teams keep getting this wrong
The mistake is almost always the same. Two engineers disagree on how strict code review should be. Instead of picking one rule, the team forks the code reviewer agent into two. The payments team and the reservations team can't agree on a PR template. So each team gets its own engineer agent. Six months later, you have a roster nobody owns and rules nobody remembers writing.
Splitting agents feels like a fair compromise. It's not. It's a way of avoiding a conversation the team should have had once.
This is Conway's Law showing up again. Your AI teammates will end up shaped like your team's communication, whether you plan it that way or not. The only question is whether you do it on purpose.
The good news: five small choices, made early, save you from this.
1. Map agents to the roles your team actually has
Look at your team today. One PM, two engineers, one designer, one analyst — that's your roster. Five agents. Don't add a sixth because some blog post says you should have a code reviewer. Don't add a seventh because the roadmap says you might hire a QA next quarter. The roadmap is wrong half the time, and the agent file you write today will outlive the hiring plan.
An agent file is a contract about who does what. Writing one for a role nobody holds creates confusion in the team, not capacity. The same logic works in reverse. If a real person is doing two jobs (the engineer who also runs experiments), give that person two agents to delegate to. Don't build one agent that mixes both jobs.
2. Keep skills product-agnostic
"Draft a PR description" doesn't change when you switch products. Neither does "summarise this meeting transcript" or "run the standard code review checklist."
Product-specific knowledge belongs in context, not in the agent. An engineer working on payments and an engineer working on reservations are the same agent reading different notes. If you fork the engineer agent for every product, your roster grows with your codebase. That's a roster nobody can keep tidy.
Two approaches, two outcomes:
- One engineer agent + product-specific notes → Roster stays small. Notes stay specific.
- One engineer agent per product → Roster grows with the codebase. Skills get duplicated.
3. Use hooks to watch, not to change behaviour
Hook scripts run when something happens in Claude Code. Use them to record what happened. Which skill ran. Who used it. How long it took. Whether the human kept the output or rewrote it.
Don't use hooks to silently change what the model does. The moment you start injecting hidden instructions, you've created behaviour that lives outside the agent file. Anyone reading the agent file later won't know about it.
Why does this matter? Because the number you eventually want to track is per-role override rate. How often did the engineer's code review get rewritten by a human? How often did the analyst's data pull need fixing? You only see this if you record it from day one.
4. Save what you learn in files, not in chat
Decisions you made. Rules you agreed on. The reason you rejected that one library three sprints ago. All of this should sit in a folder of plain text files that the agents read at the start of each session.
Sessions are short. Files last (well, until git deletes them). A two-line note written today is worth more than a perfect explanation given to a fresh session next week. The fresh session won't have the explanation.
A simple test: if a teammate joined tomorrow and asked "why don't we use library X?", could the agent answer? If the answer only lives in last Tuesday's chat, the answer is gone.
5. Ask the agent to argue, not to agree
"I'd be happy to help!" is a sign the setup is wrong. It's the AI version of a junior teammate who agrees with whatever the room wants.
A more useful default: when two reasonable options exist, the agent shows both, picks one, explains why, and lets the human decide. Then it writes the choice down (see rule 4). An agent that argues with you catches mistakes. An agent that flatters you joins them.
This is about role design, not prompting. A teammate who only validates is a teammate who can't catch the team being wrong.
What this all adds up to
When Claude Code arrived, most teams treated it as a tool to write code faster. That framing is what creates the agent sprawl. Under that framing, every new task is a candidate for a new agent.
A better framing: Claude Code is a place where you design how your team works. Agent files are job descriptions. Skills are the team's verbs. The notes folder holds the stuff a new joiner would otherwise pester three people for. Hooks are the dashboard. You're staffing a team that happens to be made of context windows. The rules of staffing teams have not changed because some of the teammates are AI.
Treat the hybrid team as a team. The metaphor is the architecture.
Setup is cheap. Taxonomy is expensive. Get the role test right at the start, and skills, hooks, files, and dashboards all find a natural home. Get it wrong and you'll be rewriting agent files every time the team shape changes — which, on a team where roles are already blurred, is roughly always.
If you want more on the building blocks themselves, my earlier piece on getting the most out of Claude Cowork covers the configuration layer that makes any of this work.
Sources
- Anthropic, "Create custom subagents", Claude Code Docs
- Anthropic, "Skills explained: How Skills compares to prompts, Projects, MCP, and subagents", claude.com/blog
- Martin Fowler, "Conway's Law", martinfowler.com/bliki
- Java Code Geeks, "Conway's Law in Practice: Why Your Microservices Mirror Your Org Chart", January 2026
- alexop.dev, "Understanding Claude Code's Full Stack: MCP, Skills, Subagents, and Hooks Explained", November 2025