| name | new-agent |
| description | Create custom Claude Code subagents. Interactive wizard that gathers requirements, generates the agent .md file with proper frontmatter and system prompt. Use when creating a new agent, adding a subagent, or making a custom agent available globally. Keywords: agent, subagent, create agent, new agent, custom agent |
New Agent Creator
Creates custom Claude Code subagents as .md files with YAML frontmatter and a system prompt.
Agent Storage Locations
| Location | Scope | When to use |
|---|
.claude/agents/ | Current project | Team-shared, checked into version control |
~/.claude/agents/ | All projects | Personal agents across your machine |
Before creating an agent, list existing agents in the target directory to avoid name conflicts.
Agent File Format
---
name: agent-name
description: When Claude should use this agent. Include 2-3 <example> blocks.
color: green
model: inherit
memory: user
---
System prompt content here — this becomes the agent's entire personality and instructions.
Frontmatter Fields
| Field | Required | Default | Description |
|---|
name | Yes | — | Lowercase, hyphens only. Must be unique across all agents. |
description | Yes | — | Critical for delegation. Must include <example> blocks. |
tools | No | All tools | Comma-separated allowlist: Read, Grep, Glob, Bash, Write, Edit etc. |
disallowedTools | No | — | Tools to explicitly deny (removed from inherited set). |
model | No | inherit | One of: sonnet, opus, haiku, inherit. |
color | No | — | UI color: green, cyan, bright_red, yellow, blue, magenta, etc. |
permissionMode | No | default | default, acceptEdits, dontAsk, bypassPermissions, plan. |
maxTurns | No | — | Maximum agentic turns before stopping. |
memory | No | — | Persistent memory scope: user, project, or local. |
skills | No | — | Skills to preload into the agent's context. |
mcpServers | No | — | MCP servers available to this agent. |
hooks | No | — | Lifecycle hooks scoped to this agent. |
Instructions
Step 1: Gather Requirements
If $ARGUMENTS is provided, use it as the agent concept. Otherwise, ask the user:
- What domain does this agent specialize in? (e.g., "database optimization", "accessibility auditing", "Rust development")
- What should it do when invoked? (e.g., "review queries for performance", "audit HTML for WCAG compliance")
- Should it be read-only or able to modify files?
- What model should it use? (
inherit for most, haiku for fast/cheap tasks, sonnet for balanced, opus for complex reasoning)
- Should it have persistent memory across sessions? (recommended for agents that learn patterns over time)
- Where should it live? (
.claude/agents/ for project-level, ~/.claude/agents/ for user-level)
Step 2: Choose the Name
Rules:
- Lowercase letters, numbers, hyphens only
- Descriptive of the role, not the task (e.g.,
accessibility-auditor not check-accessibility)
- Check for conflicts with existing agents in the target directory
- Keep it short but unambiguous
Step 3: Craft the Description
The description is critical — Claude uses it to decide when to delegate tasks to this agent.
Required structure:
Use this agent when [trigger scenarios]. This agent excels at [capabilities]. Examples:\n\n<example>\nContext: [situation]\nuser: "[what the user says]"\nassistant: "[how Claude delegates]"\n<commentary>\n[Why this agent is the right choice]\n</commentary>\n</example>
Include 2-3 <example> blocks showing realistic delegation scenarios. These are essential — Claude relies on them for pattern matching.
Best practices:
- Start with "Use this agent when..."
- List specific trigger scenarios, not vague domains
- Include keywords users might say naturally
- Add "Use proactively" if the agent should auto-trigger (e.g., after code changes)
Step 4: Write the System Prompt
The markdown body after the frontmatter becomes the agent's system prompt. It receives only this prompt (plus basic environment details), not the full Claude Code system prompt.
Structure:
- Opening persona (1-2 sentences): Who the agent is and what it values
- Core Mindset / Principles (bulleted): The mental model that drives decisions
- Detailed Methodology: Domain-specific checklists, frameworks, or processes
- Output Format: How findings/results should be structured
- Communication Style: Tone and presentation guidelines
- Memory Guidelines (if memory enabled): What to record across sessions
Quality bar:
- Be specific and actionable, not vague
- Include domain-specific frameworks relevant to the specialty
- Define output structure so results are consistent
- Include anti-patterns (what NOT to do)
- Keep it under 150 lines — agents with bloated prompts lose focus
Step 5: Select Tool Access
Common patterns:
| Agent Type | Tools | Rationale |
|---|
| Read-only reviewer | Read, Grep, Glob, Bash | Can explore and run read-only commands |
| Code modifier | All tools (default) | Full access to make changes |
| Research-only | Read, Grep, Glob, WebSearch, WebFetch | Can search code and web, no execution |
| Restricted executor | Bash + hooks | Bash with PreToolUse hook to validate commands |
If the agent should have all tools (the common case), omit the tools field entirely.
Step 6: Create the Agent File
Write the agent .md file to the target directory chosen in Step 1.
Step 7: Verify and Report
After creating the file:
- Show the file — display the full content
- Confirm no name conflicts — check against existing agents in the target directory
- Show example invocations — 2-3 ways to trigger the agent
- Remind about loading — new agents are loaded at session start; restart the session or use
/agents to load immediately
- Suggest testing — try a request that matches the description to verify delegation
Example Agent (Reference)
A well-structured agent:
---
name: accessibility-auditor
description: Use this agent when you need to evaluate UI code for accessibility compliance, WCAG conformance, or inclusive design. Excels at identifying missing ARIA attributes, keyboard navigation issues, color contrast problems, and screen reader compatibility.\n\n<example>\nContext: The user just built a new form component.\nuser: "Can you check if this form is accessible?"\nassistant: "I'll use the accessibility-auditor agent to evaluate your form for WCAG compliance."\n<commentary>\nForm accessibility involves labels, error announcements, focus management — specialized knowledge the accessibility-auditor provides.\n</commentary>\n</example>
color: yellow
memory: user
---
You are an accessibility specialist who ensures digital interfaces work for everyone.
## Core Mindset
- **Inclusive by default**: Every user deserves equal access to functionality
- **Programmatic first**: If assistive tech can't parse it, it's broken
- **Progressive enhancement**: Start accessible, layer on interactivity
## Methodology
When auditing code:
1. Check semantic HTML structure (headings, landmarks, roles)
2. Verify all interactive elements are keyboard-accessible
3. Confirm ARIA attributes are correct and complete
4. Evaluate color contrast ratios (WCAG AA minimum)
5. Test focus management for dynamic content
## Output Format
Organize findings by impact:
### Critical (blocks access entirely)
### Major (degrades experience significantly)
### Minor (improvement opportunities)
For each finding: **what** is wrong, **where** (file:line), **why** it matters, **fix** with code example.
Be specific — cite WCAG success criteria by number (e.g., 1.4.3 Contrast)
Provide before/after code examples for every finding
Acknowledge what's already done well
Anti-Patterns
- Don't create agents for one-off tasks — use skills or the main conversation instead
- Don't create agents with vague descriptions — "helps with code" will never trigger
- Don't duplicate existing agents — check the target directory first
- Don't give write access to pure analysis agents — principle of least privilege
- Don't skip the
<example> blocks — they're the primary delegation signal
- Don't make the system prompt too long — over 150 lines dilutes focus
