Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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/.
