Awesome-omni-skill agent-creator

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.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ai-agents/agent-creator" ~/.claude/skills/diegosouzapw-awesome-omni-skill-agent-creator-dcaa4b && rm -rf "$T"

manifest: skills/ai-agents/agent-creator/SKILL.md

source content

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

```
--agents
```
CLI 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:
```
/agents
```
in Claude Code TUI

Manual: Create

.claude/agents/my-agent.md

~/.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
```
/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.