| Guide ID | A-4 |
|---|---|
| Audience | Developers, Team leads |
| Prerequisites | GS-2: Core Concepts, T-2: Skills vs Agents vs Teams |
| Time | 20 minutes |
| Difficulty | Advanced |
Agent Composition
A skill is a single piece of knowledge. An agent is a composite intelligence built from skills that belong together. The difference matters: loading three related skills individually means each must be scored, resolved, and budgeted separately, with no guarantee they all load into the same session. Composing them into an agent means they load as a unit, with a single description that tells Claude when to delegate to this combined expertise.
In the chipset model, agent composition is the process of building higher-order coprocessors from simpler ones. The Amiga's Agnus was itself a composition: it combined the blitter (bulk memory operations) and the copper (display timing sequences) into a single chip because those functions were always needed together during display rendering. gsd-skill-creator detects when skills are always needed together and proposes composing them into agents for the same reason: co-activated knowledge should be loaded as a unit.
The Composition Journey
Composition follows a five-stage progression: Observation → Pattern → Skill → Agent → Team. Each stage emerges from the one before it through automated detection, but every transition requires explicit user confirmation. The system proposes; the user disposes.
Observation. During Claude Code sessions, Paula (the I/O controller) records what happens: commands executed, files touched, skills activated, corrections made. These observations accumulate in .planning/patterns/sessions.jsonl as structured, timestamped records.
Pattern. The pattern detection engine scans observations for recurring sequences. When the same command sequence, file access pattern, or workflow structure appears 3 or more times, it becomes a skill candidate. Patterns are the raw material from which skills are synthesized.
Skill. A confirmed pattern becomes a skill — a Markdown file with YAML frontmatter that provides guidance to Claude Code when specific triggers are matched. Skills are stored in .claude/skills/<name>/SKILL.md and managed through the 6-stage loading pipeline.
Agent. When skills that frequently activate together form a stable cluster, the system proposes composing them into an agent. An agent is a .claude/agents/<name>.md file that combines expertise from multiple skills, with a unified description that tells Claude when to delegate to this composite intelligence.
Team. When multiple agents need to coordinate on complex tasks, they can be organized into a team. Teams are JSON configurations in .claude/teams/<name>.json that define topology, coordination patterns, and member roles.
Co-Activation Tracking
The co-activation tracker monitors which skills activate together during sessions. Every time the loading pipeline runs, it records which skills were loaded. Over time, this produces a co-activation matrix: a record of how often each pair of skills appears in the same session.
Three thresholds govern when co-activation becomes composition-worthy:
5+ co-activations. The skill pair must have been loaded together in at least 5 separate pipeline runs. This filters out coincidental overlaps. Two skills might both load during a single unusual session; 5 co-activations across multiple sessions indicates a genuine relationship.
7+ days stability. The co-activation pattern must persist over at least 7 calendar days. This filters out temporary project phases. During a sprint focused on testing, every testing-related skill might co-activate — but if the pattern disappears after the sprint, it was not a stable composition candidate.
2-5 skills per cluster. The cluster detector groups related skills based on co-activation density. A cluster must contain at least 2 skills (a single skill is already a skill, not an agent) and at most 5 (beyond 5, the agent becomes too broad to be useful). The cluster boundaries are determined by co-activation strength: skills within the cluster co-activate more frequently with each other than with skills outside the cluster.
The tracking data is stored in .planning/patterns/agent-suggestions.json, which maintains the co-activation counts, cluster assignments, and stability timestamps for each candidate agent.
Source: src/agents/ (agent composition engine), src/detection/ (co-activation and cluster detection)
Agent Generation
When a cluster meets all three thresholds, the system generates an agent definition. The generated agent follows the official Claude Code agent format:
Frontmatter fields:
| Field | Type | Description |
|---|---|---|
name | string | Agent identifier — lowercase letters, numbers, and hyphens only (required) |
description | string | What the agent does and when Claude should delegate to it (required) |
tools | string | Comma-separated list of allowed tools, e.g., Read, Write, Edit, Bash, Glob, Grep (NOT a YAML array) |
model | string | Model assignment: inherit, sonnet, opus, or haiku |
skills | string[] | Skills to preload when this agent is spawned |
The tools field is the most common format mistake. It must be a comma-separated string (tools: Read, Write, Bash), not a YAML array. This matches the official Claude Code agent specification. Run skill-creator agents validate to check all agents for format compliance, or skill-creator migrate-agent to convert legacy array-format agents to the string format.
The agent's body combines the expertise descriptions from each constituent skill, providing a unified instruction set. The generated description follows the "Use when..." pattern: it states what the agent does and specifies the conditions under which Claude should delegate to it.
Known issue: Agents stored at the user level (~/.claude/agents/) may not be automatically discovered by Claude Code at session startup (GitHub #11205). Use project-level agents (.claude/agents/) instead, or load user-level agents manually via the /agents UI command or the --agents CLI flag.
Source: src/agents/ (agent generation), docs/AGENT-GENERATION.md (format specification)
Team Topologies
When a task requires coordination among multiple agents, teams provide the structure. Three topology patterns are supported, each designed for a different coordination need.
Leader-Worker
One coordinator agent delegates tasks to worker agents and synthesizes their output. The leader manages context distribution, work assignment, and result aggregation. Workers operate independently within their delegated scope.
Use cases: Parallel ecosystem research (one synthesizer coordinates four domain researchers), adversarial debugging (one coordinator directs three investigators exploring different failure hypotheses).
Built-in templates: The GSD Research Team (5 members: 1 synthesizer + 4 researchers) and the GSD Debugging Team (4 members: 1 coordinator + 3 investigators) both use leader-worker topology.
Pipeline
Sequential stages with explicit handoffs. Each agent processes its input and passes structured output to the next agent in the chain. The pipeline topology enforces ordering: agent B cannot start until agent A completes its handoff.
Use cases: Data processing chains (extract, transform, validate, load), review chains (draft, review, revise, approve), build pipelines (lint, test, build, deploy).
Swarm
Peer agents with a lightweight coordinator. All agents can communicate with each other (not just with the leader). The coordinator manages scheduling and conflict resolution but does not direct work. Agents self-organize around the task.
Use cases: Parallel exploration (multiple agents exploring different solution approaches simultaneously), brainstorming (agents propose, critique, and refine ideas collaboratively).
Validation Pipeline
Before a team can be deployed, it passes through a 6-check validation pipeline. These checks catch configuration errors that would cause runtime failures or degraded behavior.
1. Schema validation. The team's JSON configuration must conform to the expected schema: required fields present, correct types, no unknown fields. This catches malformed configurations before any other processing.
2. Member resolution. Every agentId referenced in the team's member list must correspond to an existing agent file in .claude/agents/. The leadAgentId must match one member's agentId. Missing agents cause blocking errors.
3. Topology rules. Each topology type has specific structural requirements. Leader-worker requires exactly one coordinator. Pipeline requires a defined stage order with no cycles. Swarm requires a coordinator but no strict hierarchy. Violations of topology rules are blocking errors.
4. Tool overlap detection. When multiple agents in the same team have access to the same tools (especially write-capable tools like Write, Edit, Bash), the validator raises a warning. Tool overlap is not an error — it may be intentional — but it increases the risk of conflicting modifications.
5. Skill conflict detection. If two agents in the same team preload skills that provide contradictory guidance (detected via conflict analysis from src/conflicts/), the validator raises a warning. Skill conflicts within a team can cause inconsistent behavior.
6. Role coherence. The validator checks whether each agent's role (coordinator, specialist, worker) is consistent with its tool permissions and skill set. A specialist agent with no skills is incoherent. A coordinator with write-only tools is suspicious. These are warnings, not errors.
Errors are blocking: the team cannot be used until they are resolved. Warnings are informational: the team can be used but may exhibit suboptimal behavior. Run skill-creator team validate my-team to validate a specific team, or skill-creator team validate --all to validate all teams.
Source: src/teams/ (team management and validation), docs/AGENT-TEAMS.md (team configuration reference)
When to Use What
The composition hierarchy provides a decision framework:
Use a skill when the knowledge covers a single domain and can stand alone. A skill for TypeScript patterns, a skill for commit conventions, a skill for testing practices — each is self-contained and useful independently.
Use an agent when multiple skills consistently activate together and represent a coherent expertise area. A "react-fullstack-agent" combining react-hooks, react-components, and api-patterns skills captures the reality that these three concerns are rarely useful in isolation — a developer working on React components almost always needs all three.
Use a team when a task requires parallel coordination among multiple agents with different expertise. Research tasks that span multiple domains, debugging tasks that require adversarial hypothesis testing, or build pipelines with sequential validation stages — these require team-level coordination that no single agent can provide.
What's Next
- A-1: Chipset Architecture — The coprocessor model that composition builds upon
- T-5: Creating Agent Teams — Step-by-step guide to building teams
- T-2: Skills vs Agents vs Teams — Choosing the right abstraction level