/agent-dev

name: agent-dev
description: >
  Use this skill when creating or refining Claude Code sub-agent definitions. Helps design specialized
  AI assistants with proper YAML frontmatter, system prompts, tool access, and example-driven descriptions.
  Automatically invoked when user requests "create an agent", "design a sub-agent", "make a specialist",
  or mentions agent development. Ensures agents follow Anthropic best practices with focused responsibilities,
  discovery-optimized descriptions, and proper tool restrictions.
allowed-tools: Read, Write, Edit, Grep, Glob, mcp__conventions__find_conventions, mcp__conventions__read_convention

Agent Dev Skill

This skill helps create production-ready Claude Code sub-agent definitions following Anthropic's official specifications and best practices.

Core Principles

1. Single Responsibility

Each agent should have ONE clear purpose. Avoid creating multipurpose agents that try to do everything.

**Good**: `postgres-expert` - PostgreSQL database management and optimization **Bad**: `database-expert` - All databases (too broad)

2. Discovery-Optimized Descriptions

The `description` field is critical for Claude to discover when to use your agent. Include:

• **What**: Clear statement of capabilities
• **When**: Specific scenarios that trigger usage
• **Examples**: Concrete usage patterns with user/assistant dialogue
• **Trigger terms**: Keywords users might mention

3. Tool Restriction Strategy

Grant only necessary tools following principle of least privilege:

• **Omit `tools` field**: Inherits all tools from main conversation (use for general-purpose agents)
• **Specify tools list**: Grant specific tools (use for focused/security-sensitive agents)

4. Model Selection

Choose the right model for the task:

• **`sonnet`**: Default choice for most agents (balanced performance/cost)
• **`opus`**: Complex reasoning, architecture decisions, critical tasks
• **`haiku`**: Simple, repetitive tasks with clear patterns
• **`inherit`**: Match parent conversation's model

Agent Structure

---
name: agent-identifier
description: >
  Primary description with capabilities and use cases.

  Examples:
  <example>
  Context: Situation description
  user: "User request example"
  assistant: "I'll use the agent-name to handle this task."
  <commentary>
  Explanation of why this agent is appropriate.
  </commentary>
  </example>

  <example>
  Context: Another scenario
  user: "Different request pattern"
  assistant: "Let me use the agent-name for this."
  <commentary>
  Another use case explanation.
  </commentary>
  </example>

tools: Tool1, Tool2, Tool3  # Optional - omit to inherit all tools
model: sonnet               # Optional - sonnet, opus, haiku, or inherit
color: "#hexcolor"          # Optional - UI color coding
---

System prompt content starts here.

You are a [role description] specializing in [domain].

## Core Responsibilities
- List key responsibilities
- Be specific and actionable
- Include success criteria

## Approach
- Describe methodology
- Include examples
- Reference best practices

## Constraints
- Limitations and boundaries
- Security considerations
- Performance requirements

File Naming & Location

**Project-level** (shared with team):

• Location: `.claude/agents/`
• Format: `agent-name.md`
• Example: `.claude/agents/postgres-expert.md`

**User-level** (personal, cross-project):

• Location: `~/.claude/agents/`
• Format: `agent-name.md`
• Example: `~/.claude/agents/custom-reviewer.md`

**Naming conventions**:

• Use lowercase letters and hyphens only
• Be descriptive but concise
• Avoid generic names like "helper" or "assistant"

Required Fields

name

Unique identifier using lowercase alphanumeric characters and hyphens.

name: fastapi-expert        # Good
name: FastAPI Expert        # Bad - no spaces or capitals
name: expert                # Bad - too generic

description

Natural language explanation with examples. This is THE MOST IMPORTANT FIELD.

**Structure**: 1. **Primary statement**: What the agent does (1-2 sentences) 2. **Use cases**: Specific scenarios (bullet points or prose) 3. **Examples**: 2-4 concrete user/assistant dialogues with commentary 4. **Trigger terms**: Keywords for discovery

**Example**:

description: >
  Expert in PostgreSQL database management, optimization, and architecture. Specializes in
  query performance tuning, schema design, replication, and PostgreSQL 16+ advanced features.
  Use PROACTIVELY for database optimization, slow queries, or schema design tasks.

  Examples:
  <example>
  Context: User needs query optimization
  user: "My PostgreSQL queries are slow"
  assistant: "I'll use the postgres-expert agent to analyze and optimize your queries."
  <commentary>
  Query performance is a core competency, so this agent is appropriate.
  </commentary>
  </example>

Optional Fields

tools

Comma-separated list of allowed tools. Omit to inherit all tools from main conversation.

**When to restrict**:

• Security-sensitive agents (limit file access, bash execution)
• Focused agents that only need specific capabilities
• Agents that should not modify code (Read, Grep, Glob only)

**Common tool sets**:

# Read-only analysis
tools: Read, Grep, Glob, Bash(git :*)

# Code modification
tools: Read, Write, Edit, Grep, Glob

# Research and planning
tools: Read, Grep, Glob, WebFetch, WebSearch

# Full-stack development
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch

model

Specify model for this agent. Options: `sonnet`, `opus`, `haiku`, `inherit`

model: sonnet    # Default - balanced performance
model: opus      # Complex reasoning, architecture
model: haiku     # Simple, fast tasks
model: inherit   # Match parent conversation

color

Hex color for UI identification (optional, cosmetic).

color: "#d79921"    # Yellow
color: "#458588"    # Blue
color: "#cc241d"    # Red

System Prompt Best Prac