Structured Data
Capability Metadata
| Field | Value |
|---|---|
| ID | CAP-006 |
| Version | v1.0 |
| Domain | Core Learning |
| Status | Documented |
| Related | CAP-003, CAP-004, CAP-009 |
| Storage | .claude/agents/ |
| Min co-activations | 5 over 7 days |
Configuration Reference
Toggle: enable_composition in integration.json
{
"enable_composition": true,
"min_coactivations": 5,
"composition_window_days": 7
}Agent output format: YAML frontmatter + markdown in .claude/agents/
---
name: tdd-specialist
description: Composed from tdd-workflow + test-runner + beautiful-commits
skills:
- tdd-workflow
- test-runner
- beautiful-commits
composed_at: "2024-03-15"
coactivation_count: 7
---
Agent instructions here (combined from constituent skills).Technical Specifications
Co-activation tracking:
interface CoactivationRecord {
skill_set: string[]; // Skills loaded together
session_id: string; // Session where co-activated
timestamp: string; // ISO 8601 UTC
}
interface CompositionProposal {
agent_name: string;
constituent_skills: string[];
coactivation_count: number; // Must be ≥ 5
window_days: number; // Span of evidence (must be ≥ 7)
draft_agent: string; // Generated agent markdown
}
class AgentComposer {
trackCoactivation(skills: string[]): void;
getProposals(): CompositionProposal[];
compose(agent_name: string): Agent; // requires confirmation
}Overview
Composing Agents is the system's way of recognizing that some skills always travel together. When two or three skills are loaded together in 5 or more sessions over at least 7 days, the system suggests composing them into a single composite agent — a new entity that bundles the constituent skills and can be addressed as a named specialist. Composed agents live in .claude/agents/ and are loaded as a unit.
The distinction between an agent and a skill is meaningful: a skill is a single capability — a workflow, a convention, a pattern. An agent is a specialist identity that carries a cluster of related skills, enabling Claude to adopt a coherent role. When you load the tdd-specialist agent, you get the TDD workflow skill, the test runner skill, and the commit convention skill together, in a package that's been optimized for their combined use.
Like all learning capabilities, composition requires your approval. The system surfaces a composition proposal when the evidence threshold is met — you review the proposed agent, the constituent skills, and the co-activation evidence, then decide whether to create it. Once composed, agents can be loaded explicitly by name or auto-loaded when context matches their constituent skills' triggers.
History
Composing Agents was part of v1.0 from the start — composition was recognized as essential early, since individual skills without coordination would produce a fragmented toolset. A developer who always uses three skills together needs a way to manage them as a group, not as three separate entities. The 5-activation-over-7-days threshold mirrors the logic from Suggesting Skills (CAP-002): enough evidence to distinguish a real pattern from coincidence, spread over enough time to prove it's a genuine habit rather than a week-long experiment.
In v1.4, Agent Teams (CAP-009) formalized multi-agent coordination at a higher level — teams of agents working in parallel on complex tasks, with defined handoff protocols. But Composing Agents remained the bottom-up emergence path: composition from observed behavior rather than deliberate team design. The two capabilities are complementary: Composing Agents creates specialists from learned patterns; Agent Teams orchestrates those specialists on complex work. The Foundation era established the former; the Growth era (v1.11+) built the latter on top of it.
Key Concepts
Think of assembling a toolkit. If you always reach for a hammer, screwdriver, and level together when hanging a picture, you might as well put them in one pouch — a "picture-hanging kit." You don't have to remember to grab all three separately; you just grab the pouch.
Composing Agents creates that pouch automatically, from what you actually do rather than what you plan to do. If the system notices that you load "tdd-workflow," "test-runner," and "beautiful-commits" together in session after session, it suggests combining them into a "tdd-specialist" agent. Next time, you just load the specialist — and all three skills come along.
The important distinction from Agent Teams (CAP-009) is where the composition comes from. Agent Teams are designed top-down: you decide which agents work together on a project. Composing Agents is bottom-up: the system notices which skills you actually reach for together and formalizes that observation. One is planned; the other is emergent.
Usage Examples
Example 1: Review a composition suggestion
# Inside a Claude Code session
/sc:suggest
# Output includes composition proposals:
# [COMPOSITION] tdd-specialist
# Constituent skills: tdd-workflow, test-runner, beautiful-commits
# Co-activations: 7 (over 12 days — threshold: 5 over 7 days)
# Draft agent: .claude/agents/tdd-specialist.md
# Create? [y/n/preview]Example 2: Inspect a composed agent file
# Composed agents live in .claude/agents/
cat .claude/agents/tdd-specialist.md
# Output:
# ---
# name: tdd-specialist
# description: Composed from tdd-workflow + test-runner + beautiful-commits
# skills: [tdd-workflow, test-runner, beautiful-commits]
# composed_at: "2024-03-20"
# coactivation_count: 7
# ---
#
# When doing TDD work: follow the TDD workflow (red/green/refactor),
# use the test runner for verification, and commit with conventional
# commit format. All three behaviors are active for this session.Example 3: Load an agent explicitly
# Load a composed agent by name in session
# (agents can also auto-load when context matches constituent triggers)
# Tell Claude to use the agent:
# "Load the tdd-specialist agent for this session."
# Or configure auto-loading to prefer agents over individual skills:
{
"prefer_agents": true, // load composed agents when available
"auto_load": true
}