diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-creator
agent-creator
VerifiedCreate and optimize Claude Code subagent files (.claude/agents/*.md) following official best practices. Use when user asks to create a subagent, agent file, custom agent, or needs help structuring agent files with YAML frontmatter.
Creating Subagents (Agent Files)
Guide for creating Claude Code subagents following Anthropic's official best practices (January 2026).
File Format
Subagents are Markdown files with YAML frontmatter:
---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer ensuring high standards.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Required Fields
Only two fields are required:
name: Unique identifier, lowercase letters and hyphens only (kebab-case)description: When Claude should delegate to this subagent. Include what it does and when to use it.
Directory Locations
Priority hierarchy (higher priority wins):
--agentsCLI flag (session only).claude/agents/(project-level, version-controlled)~/.claude/agents/(user-level, all projects)- Plugin
agents/(lowest)
Frontmatter Fields
| Field | Required | Description |
|---|---|---|
name | ✅ Yes | Unique identifier (kebab-case) |
description | ✅ Yes | Delegation trigger description |
tools | No | Allowlist (inherits all if omitted) |
disallowedTools | No | Denylist to remove |
model | No | sonnet, opus, haiku, or inherit (default) |
permissionMode | No | default, acceptEdits, dontAsk, bypassPermissions, plan |
skills | No | Skills to preload at startup |
hooks | No | Lifecycle hooks scoped to this subagent |
Creating Subagents
Three methods:
- Interactive:
/agentsin Claude Code TUI - Manual: Create
.claude/agents/my-agent.mdor~/.claude/agents/my-agent.md - CLI:
claude --agents '{"agent-name": {...}}'
After manual creation, restart session or run /agents to load.
Writing Effective Descriptions
Critical for automatic delegation. Include:
- What the subagent does
- When to use it
- Proactive triggers (recommended)
Good:
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
Bad:
description: Code reviewer # Too vague, missing triggers
Tool Access Control
Allowlist:
tools: Read, Grep, Glob, Bash
Denylist:
disallowedTools: Write, Edit
Default: Inherits all tools from main conversation (including MCP tools) if tools omitted.
Model Selection
model: haiku # Fast, read-only exploration
model: sonnet # Balanced (code review, debugging)
model: opus # Complex reasoning
model: inherit # Match main conversation (default)
Permission Modes
| Mode | Behavior |
|---|---|
default | Standard permission prompts |
acceptEdits | Auto-accept file edits only |
dontAsk | Auto-deny prompts |
bypassPermissions | Skip all checks |
plan | Read-only (Plan mode) |
Note: Parent bypassPermissions takes precedence.
Preloading Skills
skills:
- api-conventions
- error-handling-patterns
Key: Full content injected at startup. Subagents don't inherit skills from parent conversation.
System Prompt Patterns
The Markdown body becomes the system prompt. Use:
- Workflow steps: "When invoked: 1. Do X 2. Do Y"
- Checklists: Structured review criteria
- Output formats: Priority-based feedback structure
- Explicit constraints: "You cannot modify data..."
Automatic Delegation
Claude delegates based on task description, description field, and context.
Encourage proactive delegation: Include "use proactively" in descriptions.
Explicit invocation:
Use the code-reviewer subagent to review my changes
When to Use Subagents
Use subagents when:
- Task produces verbose output
- Need to enforce tool restrictions
- Work is self-contained with summary return
- Want to isolate context
Use main conversation when:
- Frequent back-and-forth needed
- Multiple phases share significant context
- Quick, targeted changes
- Latency matters
Limitation: Subagents cannot spawn other subagents. Chain from main conversation or use Skills.
File Naming
- Filename: Any name ending in
.md(e.g.,my-agent.md) - Name field: kebab-case (lowercase, hyphens only)
- Must be unique within scope
Loading Behavior
- Loaded at session start
- Restart session or
/agentsto load manually-created files - Changes require restart
Version Control
Project subagents (.claude/agents/): ✅ Check into version control, share with team
User subagents (~/.claude/agents/): Personal preferences, keep out of version control
Reference Files
- Examples: See examples.md
- Hooks: See hooks.md for conditional tool validation
- Advanced: See advanced.md for background execution, resuming, auto-compaction
Fundamental Principle
Focused, specialized assistants with clear delegation triggers and appropriate tool restrictions. Design them to solve specific, well-defined problems that benefit from isolated context or enforced constraints.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |