wshobson/team-composition-patterns
plugins/agent-teams/skills/team-composition-patterns/SKILL.md
Design optimal agent team compositions with sizing heuristics, preset configurations, and agent type selection. Use this skill when deciding how many agents to spawn for a task, when choosing between a review team versus a feature team versus a debug team, when selecting the correct subagent_type for each role to ensure agents have the tools they need, when configuring display modes (tmux, iTerm2, in-process) for a CI or local environment, or when building a custom team composition for a non-standard workflow such as a migration or security audit.
$ install --global
skillsauthnpx skillsauth add wshobson/agents team-composition-patternsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 17, 2026, 2:09 AM110.2s3 files scanned
SKILL.md
- name:
- team-composition-patterns
- description:
- Design optimal agent team compositions with sizing heuristics, preset configurations, and agent type selection. Use this skill when deciding how many agents to spawn for a task, when choosing between a review team versus a feature team versus a debug team, when selecting the correct subagent_type for each role to ensure agents have the tools they need, when configuring display modes (tmux, iTerm2, in-process) for a CI or local environment, or when building a custom team composition for a non-standard workflow such as a migration or security audit.
- version:
- 1.0.2
Team Composition Patterns
Best practices for composing multi-agent teams, selecting team sizes, choosing agent types, and configuring display modes for Claude Code's Agent Teams feature.
When to Use This Skill
- Deciding how many teammates to spawn for a task
- Choosing between preset team configurations
- Selecting the right agent type (subagent_type) for each role
- Configuring teammate display modes (tmux, iTerm2, in-process)
- Building custom team compositions for non-standard workflows
Team Sizing Heuristics
| Complexity | Team Size | When to Use | | ------------ | --------- | ----------------------------------------------------------- | | Simple | 1-2 | Single-dimension review, isolated bug, small feature | | Moderate | 2-3 | Multi-file changes, 2-3 concerns, medium features | | Complex | 3-4 | Cross-cutting concerns, large features, deep debugging | | Very Complex | 4-5 | Full-stack features, comprehensive reviews, systemic issues |
Rule of thumb: Start with the smallest team that covers all required dimensions. Adding teammates increases coordination overhead.
Preset Team Compositions
Review Team
- Size: 3 reviewers
- Agents: 3x
team-reviewer - Default dimensions: security, performance, architecture
- Use when: Code changes need multi-dimensional quality assessment
Debug Team
- Size: 3 investigators
- Agents: 3x
team-debugger - Default hypotheses: 3 competing hypotheses
- Use when: Bug has multiple plausible root causes
Feature Team
- Size: 3 (1 lead + 2 implementers)
- Agents: 1x
team-lead+ 2xteam-implementer - Use when: Feature can be decomposed into parallel work streams
Fullstack Team
- Size: 4 (1 lead + 3 implementers)
- Agents: 1x
team-lead+ 1x frontendteam-implementer+ 1x backendteam-implementer+ 1x testteam-implementer - Use when: Feature spans frontend, backend, and test layers
Research Team
- Size: 3 researchers
- Agents: 3x
general-purpose - Default areas: Each assigned a different research question, module, or topic
- Capabilities: Codebase search (Grep, Glob, Read), web search (WebSearch, WebFetch)
- Use when: Need to understand a codebase, research libraries, compare approaches, or gather information from code and web sources in parallel
Security Team
- Size: 4 reviewers
- Agents: 4x
team-reviewer - Default dimensions: OWASP/vulnerabilities, auth/access control, dependencies/supply chain, secrets/configuration
- Use when: Comprehensive security audit covering multiple attack surfaces
Migration Team
- Size: 4 (1 lead + 2 implementers + 1 reviewer)
- Agents: 1x
team-lead+ 2xteam-implementer+ 1xteam-reviewer - Use when: Large codebase migration (framework upgrade, language port, API version bump) requiring parallel work with correctness verification
Agent Type Selection
When spawning teammates with the Agent tool, choose subagent_type based on what tools the teammate needs:
| Agent Type | Tools Available | Use For |
| ------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------- |
| general-purpose | All tools (Read, Write, Edit, Bash, etc.) | Implementation, debugging, any task requiring file changes |
| Explore | Read-only tools (Read, Grep, Glob) | Research, code exploration, analysis |
| Plan | Read-only tools | Architecture planning, task decomposition |
| agent-teams:team-reviewer | Read/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage | Code review with structured findings |
| agent-teams:team-debugger | Read/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage | Hypothesis-driven investigation |
| agent-teams:team-implementer | Read/Write/Edit/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage | Building features within file ownership boundaries |
| agent-teams:team-lead | Read/search/Bash plus Agent Teams coordination tools | Team orchestration and coordination |
Key distinction: Read-only agents (Explore, Plan) cannot modify files. Never assign implementation tasks to read-only agents.
Display Mode Configuration
Configure in ~/.claude/settings.json:
{
"teammateMode": "tmux"
}
| Mode | Behavior | Best For |
| -------------- | ------------------------------ | ------------------------------------------------- |
| "tmux" | Each teammate in a tmux pane | Development workflows, monitoring multiple agents |
| "iterm2" | Each teammate in an iTerm2 tab | macOS users who prefer iTerm2 |
| "in-process" | All teammates in same process | Simple tasks, CI/CD environments |
Custom Team Guidelines
When building custom teams:
- Every team needs a coordinator — Either designate a
team-leador have the user coordinate directly - Match roles to agent types — Use specialized agents (reviewer, debugger, implementer) when available
- Avoid duplicate roles — Two agents doing the same thing wastes resources
- Define boundaries upfront — Each teammate needs clear ownership of files or responsibilities
- Keep it small — 2-4 teammates is the sweet spot; 5+ requires significant coordination overhead
Troubleshooting
A teammate was spawned as Explore but needs to write files.
Explore and Plan are read-only agents. Change the subagent_type to general-purpose or an appropriate specialized agent type. Never assign implementation tasks to read-only agents.
The team is growing too large and coordination is slowing everything down. Each additional teammate adds communication overhead. Consolidate roles: can one agent cover two dimensions? A 4-person team doing 6 independent tasks is usually better served by 3 agents covering 2 tasks each.
tmux mode is not showing panes.
Ensure tmux is installed and a session is already running before spawning teammates. The in-process mode works without tmux and is suitable for CI or scripted environments.
Two reviewers are flagging the same issues. The review dimensions overlap. Redefine each reviewer's focus area: one on correctness/logic, one on security, one on performance/scalability. Overlapping coverage wastes tokens and produces duplicate findings.
A team-lead is spawning teammates but they are not receiving tasks.
Verify that the lead is using the Agent tool to spawn teammates and passing complete context in the prompt. Teammates start fresh with no prior conversation history — they need all relevant information in their initial prompt.
Related Skills
- parallel-feature-development — Decompose work streams and assign file ownership once the team is composed
- team-communication-protocols — Establish messaging norms and shutdown procedures for the assembled team
Related Skills
wshobson/hermes-tweet
tools
VerifiedTrustedCommunity
Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.
39,228SKILL.mdUpdated Jul 9, 2026
wshobson/avoid-ai-writing
testing
VerifiedTrustedCommunity
Audit and rewrite prose so it stops reading as machine-generated. Use this skill when asked to remove AI-isms, clean up AI writing, edit a draft for AI tells, audit a README, changelog, release note, PR description, or blog post for machine-sounding prose, or make text sound less like AI. Supports a detect-only mode, a rewrite mode, and an edit-in-place mode, with optional voice and context profiles.
38,906SKILL.mdUpdated Aug 19, 2026
wshobson/python-design-patterns
development
VerifiedTrustedCommunity
Python design patterns including KISS, Separation of Concerns, Single Responsibility, and composition over inheritance. Use this skill when designing a new service or component from scratch and choosing how to layer responsibilities, when refactoring a God class or monolithic function that has grown too large, when deciding whether to add a new abstraction or live with duplication, when evaluating a pull request for structural issues like tight coupling or leaking internal types, when choosing between inheritance and composition for a new class hierarchy, or when a codebase is becoming hard to test because of entangled I/O and business logic.
38,906SKILL.mdUpdated Apr 25, 2026
wshobson/prompt-engineering-patterns
development
VerifiedTrustedCommunity
This skill should be used when the user asks to "optimize a prompt", "improve prompt performance", "design a prompt template", "write better prompts", "debug prompt issues", "use chain-of-thought", "structured prompting", "few-shot prompting", or wants to apply advanced prompt engineering patterns for production LLM applications.
38,906SKILL.mdUpdated Apr 25, 2026