---

name: claude-code-agents description: Create and configure Claude Code agents with YAML frontmatter, tool selection, model specification, and naming conventions. Reference for building specialized AI subagents that handle complex, multi-step tasks.

Claude Code Agents — Meta Reference

This skill provides the definitive reference for creating Claude Code agents. Use this when building new agents or understanding agent architecture.

---

Quick Reference

Agent Structure

Copy.claude/agents/
├── code-reviewer.md
├── security-auditor.md
├── test-architect.md
└── system-architect.md

---

Built-in Subagents

Claude Code includes built-in subagents that Claude automatically uses when appropriate:

Built-in subagents inherit parent conversation permissions with additional tool restrictions. They cannot spawn other subagents (prevents infinite nesting).

---

Agent Template

Copy---
name: agent-name
description: When to use this agent (single line)
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Agent Name

You are a [role description].

## Responsibilities

- Responsibility 1
- Responsibility 2
- Responsibility 3

## Workflow

1. Step 1: [action]
2. Step 2: [action]
3. Step 3: [action]

## Output Format

[Specify expected output structure]

---

Frontmatter Specification

name (required)

Copyname: security-auditor

Rules:

• Kebab-case only
• Match filename (without .md)
• Descriptive but concise

description (required)

Copydescription: Analyze code for security vulnerabilities using OWASP Top 10

Rules:

• Single line, under 200 characters
• Explain WHEN Claude should invoke this agent
• Include key capabilities

tools (optional)

Copytools: Read, Grep, Glob, Bash, Edit, Write

Available tools:

Minimal permissions principle: Only include tools the agent needs.

model (optional)

Copymodel: sonnet  # or opus, haiku, inherit

permissionMode (optional)

CopypermissionMode: dontAsk

skills (optional)

Preload skills into subagent context at startup:

Copyskills:
  - api-conventions
  - error-handling-patterns

Full skill content is injected into the subagent's context.

hooks (optional)

Add lifecycle hooks directly to agent frontmatter:

Copyhooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-query.sh"

Hook receives JSON via stdin with tool_input. Exit code 2 blocks the operation.

---

Agent Categories

Analysis Agents (Read-only)

Copytools: Read, Grep, Glob

Examples:

• code-reviewer - Review code quality
• security-auditor - Find vulnerabilities
• architecture-analyzer - Analyze system design

Implementation Agents (Read-write)

Copytools: Read, Grep, Glob, Edit, Write, Bash

Examples:

• backend-engineer - Build APIs
• frontend-engineer - Build UIs
• test-engineer - Write tests

Research Agents (Web access)

Copytools: Read, WebFetch, WebSearch

Examples:

• documentation-researcher - Find docs
• technology-scout - Evaluate options

---

Agent Design Patterns

Single-Responsibility Agent

Copy---
name: sql-optimizer
description: Analyze and optimize SQL queries for performance
tools: Read, Grep, Glob
model: sonnet
---

# SQL Optimizer

You optimize SQL queries. Focus on:

1. Index usage analysis
2. Query plan examination
3. Performance recommendations

Output optimization suggestions with before/after examples.

Orchestrator Agent

Copy---
name: fullstack-builder
description: Coordinate frontend, backend, and database changes
tools: Read, Grep, Glob, Task
model: sonnet
---

# Fullstack Builder

You coordinate multi-layer changes by delegating to specialized agents:

1. Analyze requirements
2. Delegate database changes to sql-engineer
3. Delegate API changes to backend-engineer
4. Delegate UI changes to frontend-engineer
5. Verify integration

Verification Agent

Copy---
name: pre-commit-checker
description: Verify code quality before commits
tools: Read, Grep, Bash
model: haiku
---

# Pre-Commit Checker

Run quality checks:
- [ ] Linting passes
- [ ] Tests pass
- [ ] No console.logs
- [ ] No TODO comments
- [ ] Types correct

Return PASS or FAIL with details.

---

Agent ↔ Skill Relationship

Agents do work → Skills provide knowledge

CopyAgent: backend-engineer
  ├── Uses skill: software-backend (API patterns)
  ├── Uses skill: dev-api-design (REST/GraphQL)
  └── Uses skill: data-sql-optimization (query optimization)

Agents reference skills implicitly—Claude loads relevant skill content based on context.

---

Naming Conventions

---

Invocation Patterns

Direct (user triggers)

CopyUser: "Review this code for security issues"
Claude: [invokes security-auditor agent]

Via Command

Copy<!-- .claude/commands/security.md -->
Run security analysis using the security-auditor agent.

Via Another Agent

Copy# Parent agent
tools: Task  # Can spawn subagents

---

Quality Checklist

CopyAGENT VALIDATION CHECKLIST

Frontmatter:
[ ] name matches filename (kebab-case)
[ ] description explains when to invoke
[ ] tools are minimal necessary
[ ] model appropriate for task complexity

Content:
[ ] Clear role definition
[ ] Specific responsibilities listed
[ ] Workflow steps defined
[ ] Output format specified

Integration:
[ ] Related skills identified
[ ] Commands reference this agent (if applicable)

---

When to Use Subagents

Use Subagents When

• Tasks produce verbose output you don't need in main context
• You want to enforce specific tool restrictions
• Work is self-contained with a clear summary
• Tasks are parallelizable (run multiple agents concurrently)
• You need isolated context to preserve main conversation quality

Use Main Conversation When

• Task needs frequent back-and-forth iteration
• Multiple phases share significant context
• Latency matters (subagents start fresh)
• You need real-time feedback during execution

Execution Modes

Foreground (default): Blocks main conversation, passes permission prompts through.

Background (Ctrl+B): Concurrent execution, auto-denies unpre-approved permissions, MCP tools unavailable.

Session Resumption

Continue previous subagent work without restarting:

CopyUser: Use the code-reviewer subagent to review the authentication module
[Agent completes]

User: Continue that code review and analyze authorization logic
[Resumes previous subagent context]

---

Security Best Practices

Deny-All Default

Start with no tools, add only what's needed:

Copy# Reviewer: read-only
tools: Read, Grep, Glob

# Builder: add write access
tools: Read, Grep, Glob, Edit, Write, Bash

Dangerous Command Awareness

Require explicit confirmation for:

• rm -rf — Recursive delete
• git push --force — Overwrite history
• sudo — Elevated permissions
• DROP TABLE — Database destruction
• Infrastructure changes (Terraform, K8s)

Context Isolation

• Each subagent has isolated context window
• Orchestrator maintains global state (compact)
• Use CLAUDE.md for shared conventions
• Never pass full codebase to subagents

---

Advanced Features (2.1.0+)

Wildcard Tool Permissions

Define broader permission patterns with fewer rules:

Copytools: Bash(npm *), Bash(*-h*), Read, Grep

Examples:

• Bash(npm *) — Allow all npm commands
• Bash(*-h*) — Allow help flags
• Bash(git status) — Allow specific command

Agent Creation Methods

1. Interactive CLI (recommended):

Copy/agents

2. Manual file creation in .claude/agents/ (project) or ~/.claude/agents/ (user)

3. CLI flag (session-only):

Copyclaude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

Agents Continue After Permission Denial

Subagents now try alternative approaches rather than stopping when permissions are denied, making autonomous workflows more resilient.

---

Navigation

Resources

• references/agent-patterns.md — Common agent patterns
• references/agent-tools.md — Tool capabilities reference
• data/sources.json — Official documentation links

Related Skills

• ../claude-code-skills/SKILL.md — Skill creation
• ../claude-code-commands/SKILL.md — Command creation
• ../claude-code-hooks/SKILL.md — Hook automation