| name | agent-architect |
| description | Designs, captures, and deploys Claude Code subagents (markdown files in .claude/agents/ or ~/.claude/agents/). Use when the user asks to design, create, scope, or build a subagent, lock a working chat pattern as a subagent, deploy an existing subagent file, convert a skill or slash command into a subagent, or references the /agents command, .claude/agents/ directory, or subagent frontmatter. Not for AGENTS.md, CLAUDE.md, slash commands, hooks, or general skills (use prompt-to-skill for skills). |
Agent Architect
Generates Claude Code subagent definition files. Three modes auto-detected from invocation: Architect (scope from a description), Lock (capture a working chat pattern), Push (deploy to project or user scope).
This skill complements the built-in /agents "Generate with Claude" wizard. Use the wizard inside Claude Code with a clear concept. Use this skill when scoping in claude.ai, capturing a chat pattern, deploying to a tracked repo, or applying anti-pattern enforcement.
When to activate
Activate when the user:
- Says "design / create / scope / build a subagent for X" or "I need an agent that Y"
- Says "lock this as a subagent" after demonstrating a working chat pattern
- References
.claude/agents/, subagent frontmatter, or the /agents command
- Asks to convert a skill, slash command, or chat pattern into a subagent
Do NOT activate for skills (use prompt-to-skill), slash commands (.claude/commands/), AGENTS.md (the agents.md open standard), CLAUDE.md (repo instructions), hooks (lifecycle scripts), or generic prompts (use prompt-architect).
Pre-flight: should this be a subagent?
| User need | Better option |
|---|
| Repeatable instruction the parent should always follow | CLAUDE.md entry |
| Manual prompt template the user invokes | Slash command in .claude/commands/ |
| Domain knowledge loaded on demand | Skill (use prompt-to-skill) |
| Lifecycle action (PreToolUse, SubagentStop) | Hook in settings |
| Read-only exploration | Built-in Explore subagent |
| Read-only planning | Built-in Plan subagent |
| Generic delegation with full tools | Built-in general-purpose subagent |
| Specialized, narrow, repeatable task with custom tools/model/prompt | Custom subagent — proceed |
If the need fits a non-subagent pattern, surface that and ask before generating.
Mode detection
| Signal | Mode |
|---|
| User describes an agent's purpose with no demonstrated chat pattern | Architect |
| "Lock this as a subagent" after a working chat sequence | Lock |
| Either followed by "push it" / "ship it" / "deploy it" | adds Push |
| "Deploy this agent" with file already in chat | Push only |
If ambiguous, ask exactly one clarifying question.
Workflow checklist
Copy this checklist into your response and check off items as you progress:
Subagent generation:
- [ ] Step 1: Pre-flight — confirmed subagent is the right tool
- [ ] Step 2: Mode detected (Architect / Lock / Push)
- [ ] Step 3: Scoping interview complete (purpose, tools, model)
- [ ] Step 4: Frontmatter drafted
- [ ] Step 5: System prompt body drafted (When invoked, Process, Output format, Boundaries, Report/Response)
- [ ] Step 6: Self-validation against anti-patterns passed
- [ ] Step 7: Scope confirmed (project / user)
- [ ] Step 8: File written
- [ ] Step 9: Reload reminder + test invocation surfaced
Do not skip Step 6.
Architect mode
User describes intent; this mode scopes and generates.
Scoping interview (max 3 questions, one per turn)
Use the interrogate skill's discipline. Skip any question chat already answers.
- Purpose and trigger — What is the single, narrow job? Auto-delegate via
PROACTIVELY / MUST BE USED directive, or only on explicit invocation? See reference/description-patterns.md.
- Tools required — Default to least-privilege. See reference/tool-and-model-selection.md for combinations and the MCP inheritance gotcha.
- Model tier —
inherit is the safe default. Switch to haiku, sonnet, or opus only when there is a clear reason.
Generation template (strict)
This template is strict — fill in the placeholders, do not restructure. See reference/frontmatter.md for full field details.
---
name: <kebab-case-name>
description: <When to invoke. Use directive language for auto-delegation.>
tools: <comma-separated allowlist OR omit to inherit all parent tools>
model: <sonnet | opus | haiku | inherit>
---
<One-sentence role statement.>
<Immediate first action.>
1. <Step>
2. <Step>
<Specific deliverable structure.>
- Do NOT <thing to escalate or refuse>
- When unsure, return control to the parent.
**Status:** complete | partial | blocked
**Summary:** <one paragraph>
**Findings / Output:** <deliverable in the Output format above>
**Obstacles:** <if partial or blocked, what stopped you>
**Next steps:** <optional follow-up for parent>
Step 6 — Self-validation feedback loop
Before writing the file, check the draft against the anti-pattern catalog:
Self-validation:
- [ ] Description specifies WHEN to invoke, not just what the agent is
- [ ] Tools list is least-privilege (no "just in case" inclusions)
- [ ] System prompt assumes cold start (no references to chat history)
- [ ] Single narrow job (does not span unrelated domains)
- [ ] Not duplicating a built-in (Explore / Plan / general-purpose)
- [ ] Output format is specific (not "review feedback" or "summary")
- [ ] Report/Response section present with Status field
If any item fails, revise the draft and re-check. Do not proceed to write until all items pass. Full catalog with detection patterns and remediations: examples/anti-patterns.md.
For worked input/output examples, see examples/architect-mode.md.
Lock mode
User has demonstrated a working pattern in chat. Capture it:
- Identify what the user accomplished, what sequence worked, what signals they looked for, what output format they wanted.
- Write the system prompt as if instructing a fresh Claude instance from a cold start. The subagent will not have conversation history.
- Infer frontmatter:
name from purpose (verb-noun preferred), description from the trigger, tools from what was actually used, model matching what worked.
- Run the same Step 6 self-validation as Architect mode.
- Show the proposed file. Ask once whether to adjust before deploying.
For worked input/output examples, see examples/lock-mode.md.
Push mode
Deploy the generated file. See reference/deployment.md for scope priority order, container deploy fallback (git format-patch + git am), and post-deploy reminders.
Quick path: ask scope (project / user), write the file, remind the user that subagents load at session start (run /agents to reload), suggest a test invocation.
Subagent constraints
If the user's design assumes any of these, the answer is not a subagent — redirect to a parent-agent prompt or CLAUDE.md instruction:
- No plan mode (begins executing immediately)
- No live thinking output (parent only sees final return)
- No mid-stream coordination (returns one final message)
- No conversation history inheritance (fresh context window)
- No persistent CWD (
cd does not persist between Bash calls)
Anti-patterns (top 6)
- God agents doing everything → force decomposition
- Tool soup "just in case" → least-privilege
- Vague descriptions → force specific triggers
- Stateful assumptions that the agent will remember chat → write for cold start
- Reinventing built-ins → use the built-ins
- Subagent for one-shot prompts → if it fits in a single parent turn, no subagent needed
Extended catalog: examples/anti-patterns.md.
Chaining with other skills
- After
interrogate → Architect mode with scoped requirements
- After successful chat pattern → Lock mode
- Before
architect-plan-for-dispatch → generate worker subagents the plan will delegate to
- Pair with
prompt-to-skill → when the agent's domain knowledge should also be a Skill loaded via the skills: frontmatter
- After
devils-advocate → stress-test design before deploy
