Skip to content

diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-creator

agent-creator

Verified

Create 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):

  1. --agents CLI flag (session only)
  2. .claude/agents/ (project-level, version-controlled)
  3. ~/.claude/agents/ (user-level, all projects)
  4. Plugin agents/ (lowest)

Frontmatter Fields

FieldRequiredDescription
name✅ YesUnique identifier (kebab-case)
description✅ YesDelegation trigger description
toolsNoAllowlist (inherits all if omitted)
disallowedToolsNoDenylist to remove
modelNosonnet, opus, haiku, or inherit (default)
permissionModeNodefault, acceptEdits, dontAsk, bypassPermissions, plan
skillsNoSkills to preload at startup
hooksNoLifecycle hooks scoped to this subagent

Creating Subagents

Three methods:

  1. Interactive: /agents in Claude Code TUI
  2. Manual: Create .claude/agents/my-agent.md or ~/.claude/agents/my-agent.md
  3. CLI: claude --agents '{"agent-name": {...}}'

After manual creation, restart session or run /agents to load.

Writing Effective Descriptions

Critical for automatic delegation. Include:

  1. What the subagent does
  2. When to use it
  3. 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

ModeBehavior
defaultStandard permission prompts
acceptEditsAuto-accept file edits only
dontAskAuto-deny prompts
bypassPermissionsSkip all checks
planRead-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 /agents to 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.

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: 468kUpdated Claude CodeCodexVerifiedInstall
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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 321kUpdated Claude CodeCodexVerifiedInstall