Agent Architect

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?

If the need fits a non-subagent pattern, surface that and ask before generating.

Mode detection

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.

1. 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.
2. Tools required — Default to least-privilege. See reference/tool-and-model-selection.md for combinations and the MCP inheritance gotcha.
3. 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>
---

# <Agent Name>

<One-sentence role statement.>

## When invoked
<Immediate first action.>

## Process
1. <Step>
2. <Step>

## Output format
<Specific deliverable structure.>

## Boundaries
- Do NOT <thing to escalate or refuse>
- When unsure, return control to the parent.

## Report / Response
**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:

1. Identify what the user accomplished, what sequence worked, what signals they looked for, what output format they wanted.
2. Write the system prompt as if instructing a fresh Claude instance from a cold start. The subagent will not have conversation history.
3. Infer frontmatter: name from purpose (verb-noun preferred), description from the trigger, tools from what was actually used, model matching what worked.
4. Run the same Step 6 self-validation as Architect mode.
5. 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