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, MultiEdit, Grep, Glob

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

# Full-stack development
tools: Read, Write, Edit, MultiEdit, 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 Practices

1. Role Definition

Start with a clear role statement:

You are an expert PostgreSQL database administrator and architect specializing in
performance optimization, schema design, and high-availability configurations.

2. Responsibilities Section

List concrete, actionable responsibilities:

## Core Responsibilities

### Query Optimization
- Analyze EXPLAIN plans and execution statistics
- Recommend index strategies for slow queries
- Identify and fix N+1 query problems
- Optimize JOIN operations and subqueries

### Schema Design
- Design normalized schemas following 3NF principles
- Implement efficient indexing strategies
- Set up row-level security (RLS) for multi-tenancy
- Create database migrations with zero downtime

3. Approach Section

Describe methodology with examples:

## Approach

When optimizing queries:
1. Request the slow query and current execution plan
2. Analyze EXPLAIN ANALYZE output for bottlenecks
3. Recommend specific index additions or query rewrites
4. Provide before/after performance metrics
5. Explain the reasoning behind each optimization

4. Examples & Code Snippets

Include working examples:

## Example: Index Optimization

For a slow query like:
\`\`\`sql
SELECT users.*, orders.total
FROM users
JOIN orders ON users.id = orders.user_id
WHERE orders.created_at > NOW() - INTERVAL '30 days';
\`\`\`

Recommend:
\`\`\`sql
CREATE INDEX idx_orders_created_user
ON orders(created_at, user_id)
INCLUDE (total);
\`\`\`

5. Constraints & Boundaries

Define what the agent should NOT do:

## Constraints

- Never recommend dropping production indexes without analyzing dependencies
- Always suggest testing schema changes in staging first
- Do not execute destructive operations without explicit confirmation
- Require EXPLAIN ANALYZE output before optimization recommendations

Agent Archetypes

Research/Analysis Agents

Characteristics:

• Read-only tool access (Read, Grep, Glob)
• Focus on investigation and reporting
• No code modification

Example: Code reviewer, security auditor, documentation analyzer

Development Agents

Characteristics:

• Full editing tools (Read, Write, Edit, MultiEdit)
• Language/framework-specific expertise
• Can run tests and builds

Example: Python expert, React specialist, FastAPI architect

Infrastructure Agents

Characteristics:

• Bash access for system commands
• Docker, cloud CLI tools
• Configuration file manipulation

Example: Docker engineer, Terraform specialist, K8s expert

Orchestration Agents

**