Loaded automatically when the description matches the active task. Read only the section you need.
This is the Claude Code edition of agent-builder. It is skill-stack-aware: it assumes you already have a rich ~/.claude/skills/ collection and tells you to use skills first, agents second. For codex-specific agent authoring, this skill does not apply.
The core insight (read first)
In Claude Code, skills do 90% of what people reach for agents to do. The agent surface is narrow:
Blackbox verification — main can't critique its own work objectively
High-volume isolation — operations producing >1000 tokens of intermediate output
Hard tool restriction — guarantees enforced by PreToolUse hooks, not by prompting
If your need isn't one of these three — author a skill, not an agent.
Use this skill when
Deciding whether a task needs a sub-agent at all, vs. better prompting / a new skill on the main agent
Designing a custom sub-agent for .claude/agents/ or ~/.claude/agents/
Writing a description field that Claude will actually delegate to
Building a verifier subagent (test-runner, security-checker, payments-checker)
Building a planner subagent that produces SPEC.md + checklist + file budgets and stops
Restricting tools / permissions / MCP for one subagent without affecting main
Preloading skills from your stack into a subagent via skills: frontmatter
Giving a subagent persistent memory: for cross-session accumulation
Auditing an existing .claude/agents/ directory to prune anti-patterns
Do not use this skill when
Task is to build a Skill (.claude/skills/*/SKILL.md) — that's skill-evaluation
Task is to evaluate an LLM agent already in production — that's agent-evaluation
Task is to coordinate sessions across machines / peer-to-peer — that's agent-teams
Task is to author an MCP server — that's mcp-server-author
Task is purely Claude Messages API outside Claude Code — that's claude-api
Task is for codex-specific agents — codex has its own conventions; do not import these patterns blindly
Purpose
This skill teaches how to design and write Claude Code sub-agents that integrate with an existing skill-stack — specifically the kind of stack Kirill has assembled (~65 skills covering frontend, backend, data, infra, and domain). It is grounded in:
The May 2026 official sub-agent docs
Anthropic's January 2026 multi-agent guidance, which refuted the "split by role" intuition
The reality that skills are the primary specialization surface in Claude Code 2026 — agents are a narrower tool than the codex / generic agent-framework world suggests
The default position is single-agent + skills. A sub-agent earns its place when one of three conditions holds (context isolation, parallelization, specialization that even a strong skill can't deliver).
Capabilities
Each line below points to the canonical reference. The reference owns full content — do not duplicate.
Single-agent vs sub-agent decision — three Anthropic conditions + the counter-test for skills. → decision-framework.md
Context-centric decomposition — divide by context, not by role; the Telephone Game with Anthropic's own evidence. → decomposition-patterns.md
Subagent anatomy — every frontmatter field with when-to-set semantics. → subagent-anatomy.md
Starts with "Skill or agent?" — for every request, first asks whether a skill in main would suffice. Agent is the exception.
Reuses built-in subagents (Explore, Plan, general-purpose) before authoring custom alternatives
Writes descriptions in user-voice (what user types), not agent-voice (what agent does); includes Russian trigger terms where appropriate
Sets tools: explicitly for read-only agents; disallowedTools: for "inherit minus writes"
For planners: produces SPEC + checklist + budgets and stops — no implementer hand-off
For verifiers: includes the verbatim phrase "You MUST run the complete before marking as passed"
Preloads ≤4 skills per agent (compaction budget); picks skills relevant to every invocation, not just some
Names agents in lowercase-with-hyphens; checks name: uniqueness across user + project + plugin scopes before creating
Avoids bypassPermissions unless paired with strict tools: allowlist
Documents which condition (context / parallel / specialization) justified the agent — so a future audit can verify the rationale still holds
Important Constraints
NEVER decompose a single feature into separate planner / implementer / tester subagents — Anthropic documented this fails (telephone game; coordination > work). Use context-centric boundaries: independent research paths, separate components with clean interfaces, blackbox verification.
NEVER write a custom subagent that duplicates Explore, Plan, or general-purpose
NEVER write a verifier without a "You MUST run the complete " instruction
NEVER let a planner subagent edit files — planner returns SPEC, main implements
NEVER set permissionMode: bypassPermissions without an explicit tools: allowlist
NEVER write skills: [skill-name] for a skill with disable-model-invocation: true — silent fail
NEVER duplicate a stack-skill as an agent (no react-agent when react skill exists in ~/.claude/skills/)
ALWAYS write the description from the user's point of view
ALWAYS verify name: uniqueness across .claude/agents/, ~/.claude/agents/, plugin scopes
ALWAYS keep the subagent body under ~150 lines; preloaded skills carry the deep content
ALWAYS verify skill names exist before adding to skills: preload list — silent fail otherwise
Related Skills
Authoring layer (siblings)
✓ skill-evaluation — for writing the SKILL.md files that subagents preload
✓ agent-evaluation — for testing whether a built subagent works in production
Stack-skills this skill references for preload guidance
⭐ dev-orchestrator is the recommended entry point for full-cycle sessions. Launched via claude --agent dev-orchestrator, it becomes the main thread and spawns the other agents as subagents in disciplined phases. See references/orchestration-modes.md for when to use it vs. skill-driven mode (superpowers-style).
Required companion script for db-reader: copy scripts/validate-readonly-db.sh to your project's .claude/scripts/ and chmod +x it. Smoke-tested for SQL + Redis write detection with jq / python / sed fallbacks.
Templates (for authoring NEW agents beyond the five above)
(KB intentionally lean — 3 entries vs the 7 in earlier draft. Compaction budget for preloaded skills is 25K shared; deep KBs eat that fast. Add Feathers / Kleppmann / Anthropic-effective-harnesses only if a specific agent justifies them.)
Examples (concrete scenarios)
Scenario
File
Real SPEC.md from feature-planner — what good looks like
"I have 30+ agents, can I delete them all?"
→ Read references/migration-guide.md. Short answer: yes, archive them, install the 6 ready-made agents from agents/, install codex-plugin-cc plugin, optionally install superpowers for workflow skills. Net: 6 custom agents + 1 plugin + 65 stack skills covers everything.
"How do I launch a full development cycle with one command?"
→ claude --agent dev-orchestrator. The orchestrator becomes main thread and runs the 7-phase cycle (understand → plan → confirm → implement → review → iterate → wrap up), spawning feature-planner, test-verifier, security-verifier as needed. See agents/dev-orchestrator.md.
"Can subagents call other subagents?"
→ No. This is documented and enforced. Solution: either (a) run an orchestrator as main thread via claude --agent, which CAN spawn subagents (this is dev-orchestrator), or (b) put methodology in workflow skills so main itself follows the cycle (the superpowers paradigm). See references/orchestration-modes.md.
How to install the ready-made agents
# from inside this skill directorycp agents/*.md ~/.claude/agents/
# if you plan to use db-reader, also install the companion scriptmkdir -p .claude/scripts
cp scripts/validate-readonly-db.sh .claude/scripts/
chmod +x .claude/scripts/validate-readonly-db.sh
# restart Claude Code so agents load (or use /agents UI for live reload)
To launch a full development cycle in one command:
claude --agent dev-orchestrator
This makes dev-orchestrator the main thread for the session, with permission to spawn feature-planner, test-verifier, security-verifier, payments-verifier, db-reader as subagents.
Verify skill names match before relying on auto-delegation:
If any expected skill is missing → skills: preload silently fails for that skill. Either author the missing skill or remove it from the agent's frontmatter.
How to use: start at decision-framework.md. If it says "use a skill instead", stop. If it says "yes, agent", go to decomposition-patterns.md to pick the right boundary, then either copy a ready-made agent from agents/ or use a template from templates/.
