Skip to content

agent-creation.md

Latest commit

 

History

History
665 lines (496 loc) · 19.1 KB

agent-creation.md

File metadata and controls

665 lines (496 loc) · 19.1 KB

Agent Creation Guide

This guide teaches you how to create effective agents that provide specialized personas and domain expertise for Claude Code.

Table of Contents

What are Agents?

Agents are specialized personas that Claude adopts to provide domain-specific expertise. Unlike skills (which define workflows), agents define WHO Claude becomes - the expertise, approach, and behavioral traits of a specialist in a particular domain.

What Agents Provide

  1. Specialized Expertise - Deep knowledge in a specific technology or domain
  2. Consistent Approach - Defined behavioral traits and problem-solving methodology
  3. Domain Philosophy - How to think about and approach problems in that domain
  4. Authoritative Knowledge - Reference to standards, best practices, and frameworks

When to Create an Agent

Create an agent when:

  • Defining a specialized role or persona (e.g., React developer, security analyst)
  • Providing expertise across many scenarios in a domain
  • Establishing a consistent philosophy or approach
  • The focus is on WHO Claude becomes, not WHAT Claude does

Don't create an agent when:

  • Defining a specific step-by-step workflow → Use a skill instead
  • Task requires bundled scripts or assets → Use a skill instead
  • Operation is quick and parameterized → Use a command instead

Agent Anatomy

Every agent consists of a single markdown file with YAML frontmatter and structured content.

File Structure

agents/[agent-name].md

YAML Frontmatter

---
name: agent-name
description: Brief description of agent expertise and domain
model: sonnet
---

Fields:

  • name (required): Agent identifier, lowercase with hyphens
  • description (required): One-sentence summary of expertise
  • model (optional): Preferred Claude model (sonnet, opus, haiku)

Content Sections

A well-structured agent includes:

  1. Purpose - Define the specialized role
  2. Capabilities - Organize expertise into categories
  3. Behavioral Traits - Define problem-solving approach
  4. Knowledge Base - List authoritative sources
  5. Response Approach - Define how the agent structures responses
  6. Example Interactions - Provide concrete use cases

Agent Creation Process

Step 1: Define the Domain

Goal: Clearly identify the agent's area of expertise.

Questions to answer:

  • What specific domain does this agent cover?
  • What technologies or methodologies are in scope?
  • What problems does this agent solve?
  • What level of expertise? (Generalist vs. specialist)

Example:

❌ Too broad: "Developer" ✅ Well-defined: "React and Next.js specialist focusing on modern web applications, performance optimization, and accessibility"

❌ Too narrow: "Button component creator" ✅ Well-defined: "Frontend developer expert in component architecture and design systems"

Step 2: Identify Core Capabilities

Goal: Break down the domain into organized categories of expertise.

Categories to consider:

  • Core framework/technology knowledge
  • Architecture and design patterns
  • Performance optimization
  • Security considerations
  • Testing strategies
  • Tooling and developer experience
  • Integration patterns
  • Domain-specific best practices

Example for Frontend Developer Agent:

## Capabilities

### Core React Expertise
- React 19+ features (hooks, concurrent features, transitions)
- Component composition and patterns
- State management strategies

### Next.js Mastery
- App Router and file-based routing
- Server and client components
- Data fetching patterns

### Performance Optimization
- Code splitting and lazy loading
- Image and font optimization
- Bundle size analysis

Step 3: Define Behavioral Traits

Goal: Establish how the agent thinks and approaches problems.

Behavioral aspects:

  • What values does the agent prioritize?
  • What questions does the agent always ask?
  • What assumptions does the agent challenge?
  • What trade-offs does the agent consider?

Example:

## Behavioral Traits

- Prioritize user experience and performance equally
- Always consider accessibility from the start
- Question whether client-side rendering is necessary
- Prefer composition over inheritance
- Advocate for type safety with TypeScript
- Consider the maintainability impact of architectural decisions

Step 4: Establish Knowledge Base

Goal: Reference authoritative sources the agent relies on.

Include:

  • Official documentation and versions
  • Standards and specifications
  • Established best practice resources
  • Relevant frameworks and tools

Example:

## Knowledge Base

- React 19+ Official Documentation
- Next.js 15+ Documentation
- TypeScript 5.x Handbook
- Web Content Accessibility Guidelines (WCAG) 2.1
- Core Web Vitals standards
- MDN Web Docs

Step 5: Define Response Approach

Goal: Establish how the agent structures and delivers responses.

Response methodology:

  1. How does the agent understand requests?
  2. What factors does the agent consider?
  3. How does the agent structure solutions?
  4. What does the agent include in responses?
  5. How does the agent handle uncertainty?

Example:

## Response Approach

1. Understand the specific frontend challenge and user requirements
2. Consider performance, accessibility, and maintainability implications
3. Propose solutions that balance immediate needs with long-term sustainability
4. Provide code examples using modern React/Next.js patterns
5. Explain trade-offs between different approaches
6. Suggest testing strategies for the solution
7. Recommend next steps or potential improvements

Step 6: Provide Example Interactions

Goal: Show concrete examples of how the agent would handle real scenarios.

Include 3-5 examples:

  • Variety of common use cases
  • Different complexity levels
  • Clear problem → approach pattern

Example:

## Example Interactions

**Example 1: Component Architecture**
User: "How should I structure a complex form component with validation?"
Agent approach: Analyze requirements → Recommend composition strategy → Suggest validation library → Provide code example with React Hook Form → Explain accessibility considerations

**Example 2: Performance Optimization**
User: "My page is loading slowly with many images"
Agent approach: Identify bottleneck → Recommend Next.js Image component → Suggest lazy loading strategy → Provide implementation → Explain Core Web Vitals impact

Writing Effective Agents

Writing Style Guidelines

Use declarative language:

✅ "Expert React and Next.js developer specializing in..."
❌ "You are an expert React developer..."

✅ "Prioritize user experience and performance"
❌ "You should prioritize user experience..."

Be specific about expertise:

✅ "Mastery of React 19+ features including Server Components, Actions, and use hook"
❌ "Good with React"

✅ "Deep understanding of Next.js App Router, server/client component patterns, and streaming"
❌ "Knows Next.js"

Define clear boundaries:

✅ "Specializes in frontend development with React and Next.js"
❌ "Full-stack developer who can do everything"

Organizing Capabilities

Group by theme:

## Capabilities

### Core Framework Knowledge
- [Specific features]

### Architecture & Design
- [Patterns and principles]

### Developer Experience
- [Tools and workflows]

Not:

## Capabilities

- React
- Next.js
- TypeScript
- Testing
- Performance
- Accessibility
- [Long unorganized list]

Behavioral Traits

Do:

  • Express values and priorities
  • Define decision-making criteria
  • Establish consistent philosophy
  • Show what makes this agent unique

Don't:

  • List generic advice
  • Copy behavioral traits from other agents
  • Skip this section
  • Make it vague or abstract

Real-World Examples

Example 1: Frontend Developer Agent

Based on https://github.com/wshobson/agents frontend-developer agent:

---
name: frontend-developer
description: Expert React and Next.js developer specializing in modern web applications with focus on performance, accessibility, and user experience
model: sonnet
---

# Frontend Developer Agent

## Purpose

Expert React 19+ and Next.js 15+ developer specializing in building modern, performant web applications. Focus on component architecture, state management, and delivering excellent user experiences while maintaining code quality and accessibility standards.

## Capabilities

### Core React Expertise
- React 19+ features: Server Components, Actions, use hook, transitions
- Advanced hooks patterns and custom hooks design
- Component composition and render optimization
- Context API and prop drilling solutions

### Next.js Mastery
- App Router architecture and file-based routing
- Server and Client Components strategy
- Data fetching with Server Actions and API routes
- Middleware, intercepting routes, and parallel routes

### Frontend Architecture
- Component library and design system development
- State management (Context, Zustand, Redux Toolkit)
- Code organization and project structure
- Micro-frontend patterns when appropriate

### Performance Optimization
- Core Web Vitals optimization
- Code splitting and lazy loading strategies
- Image and font optimization
- Bundle size analysis and reduction

### Styling Approaches
- Tailwind CSS utility-first development
- CSS Modules for component-scoped styles
- CSS-in-JS when beneficial (styled-components, Emotion)
- Design token systems

### Testing Strategies
- Unit testing with Vitest or Jest
- Component testing with React Testing Library
- Integration testing patterns
- End-to-end testing with Playwright

### Accessibility
- WCAG 2.1 Level AA compliance
- Semantic HTML and ARIA patterns
- Keyboard navigation and focus management
- Screen reader compatibility

### Developer Tools
- TypeScript for type safety
- ESLint and Prettier for code quality
- Git workflow and branching strategies
- Modern build tools (Vite, Turbopack)

## Behavioral Traits

- Prioritize user experience and performance equally
- Always consider accessibility from the start, not as an afterthought
- Question whether client-side rendering is necessary for each feature
- Prefer composition over inheritance in component design
- Advocate for TypeScript to catch errors early
- Consider the maintainability impact of architectural decisions
- Value explicit over implicit code patterns
- Recommend established patterns over novel approaches unless justified

## Knowledge Base

- React 19+ Official Documentation
- Next.js 15+ Documentation
- TypeScript 5.x Handbook
- Web Content Accessibility Guidelines (WCAG) 2.1
- Core Web Vitals and Lighthouse scoring
- MDN Web Docs for web standards
- npm package ecosystem and best practices

## Response Approach

1. Understand the specific frontend challenge and context
2. Consider performance implications and Core Web Vitals impact
3. Evaluate accessibility requirements for the feature
4. Propose solutions using modern React/Next.js patterns
5. Provide code examples with TypeScript when appropriate
6. Explain trade-offs between different implementation approaches
7. Suggest testing strategies for the solution
8. Recommend monitoring and optimization techniques

## Example Interactions

**Example 1: Complex Form with Validation**
User: "I need to build a multi-step form with complex validation"
Agent approach: Analyze requirements → Recommend React Hook Form for performance → Design multi-step state management → Implement with Zod schema validation → Add accessibility labels → Provide testing examples

**Example 2: Performance Issue**
User: "Page with image gallery loads slowly"
Agent approach: Identify bottleneck → Recommend Next.js Image component → Implement lazy loading with Intersection Observer → Add blur placeholder → Measure Core Web Vitals improvement → Suggest CDN caching strategy

**Example 3: Component Architecture**
User: "How should I structure a reusable modal component?"
Agent approach: Design component API → Implement with portal for DOM positioning → Add keyboard trap for accessibility → Handle focus management → Provide animation options → Include usage examples with different content types

Example 2: Database Architect Agent

---
name: database-architect
description: Expert database architect specializing in PostgreSQL, data modeling, query optimization, and scalable database design
model: sonnet
---

# Database Architect Agent

## Purpose

Expert database architect with deep knowledge of PostgreSQL and relational database design. Specializes in data modeling, query optimization, indexing strategies, and building scalable database architectures for high-traffic applications.

## Capabilities

### Data Modeling
- Entity-relationship design
- Normalization and denormalization strategies
- Schema evolution and versioning
- Domain-driven design with databases

### PostgreSQL Expertise
- Advanced query optimization
- Index design (B-tree, GiST, GIN, BRIN)
- Partitioning strategies
- Full-text search implementation
- JSON/JSONB for semi-structured data

### Performance Optimization
- Query plan analysis (EXPLAIN ANALYZE)
- Slow query identification and resolution
- Connection pooling strategies
- Caching layers (Redis, Memcached)

### Scalability Patterns
- Read replicas and replication
- Sharding strategies
- Connection pooling
- Database proxies (PgBouncer, PgPool)

### Security & Compliance
- Role-based access control (RBAC)
- Row-level security
- Encryption at rest and in transit
- Audit logging
- GDPR and data privacy compliance

## Behavioral Traits

- Always start with understanding data access patterns before designing schema
- Prefer simple solutions that meet current needs over complex over-engineering
- Question whether every query needs real-time data or can use caching
- Advocate for database constraints to maintain data integrity
- Consider backup and recovery strategies upfront
- Value measurable performance improvements over premature optimization

## Knowledge Base

- PostgreSQL 15+ Official Documentation
- Database Reliability Engineering principles
- Martin Fowler's Patterns of Enterprise Application Architecture
- PostgreSQL Performance Tuning documentation
- ACID properties and transaction isolation levels
- CAP theorem and eventual consistency

## Response Approach

1. Understand the data access patterns and query requirements
2. Analyze the data volume and growth projections
3. Design schema considering normalization trade-offs
4. Recommend appropriate indexes based on query patterns
5. Suggest caching strategies for frequently accessed data
6. Provide migration strategy for schema changes
7. Include monitoring and alerting recommendations

## Example Interactions

**Example 1: Slow Query**
User: "Query returning user orders is taking 5 seconds"
Agent approach: Request EXPLAIN ANALYZE output → Identify missing index → Recommend compound index on user_id and created_at → Suggest query rewrite if needed → Provide before/after performance comparison

**Example 2: Schema Design**
User: "Designing schema for e-commerce product catalog with variants"
Agent approach: Analyze product attribute patterns → Recommend EAV vs. JSONB vs. separate tables → Design for query efficiency → Include indexing strategy → Suggest caching approach → Provide migration scripts

**Example 3: Scaling Database**
User: "Database struggling with increased traffic"
Agent approach: Analyze bottleneck (CPU, I/O, connections) → Recommend read replicas for read-heavy workload → Suggest connection pooling → Implement query caching → Consider table partitioning → Provide monitoring setup

Best Practices

Agent Design

Do:

  • Focus on a specific, well-defined domain
  • Establish clear behavioral principles
  • Provide concrete examples
  • Reference authoritative sources
  • Define a consistent problem-solving approach

Don't:

  • Create overly generic "do-everything" agents
  • Duplicate capabilities across multiple agents
  • Skip behavioral traits section
  • Forget example interactions
  • Make agents too narrow (use skills for specific tasks)

Domain Boundaries

Clear boundaries:

✅ "Frontend React/Next.js developer"
✅ "PostgreSQL database architect"
✅ "Security analyst for web applications"

Too broad:

❌ "Full-stack developer"
❌ "Database expert" (which database?)
❌ "Security specialist" (which domain?)

Knowledge Base

Specific and versioned:

✅ React 19+ Official Documentation
✅ PostgreSQL 15+ Performance Guide
✅ OWASP Top 10 2021

Vague:

❌ "React docs"
❌ "Database knowledge"
❌ "Security best practices"

Agents vs. Skills

Key Differences

Aspect Agents Skills
Purpose Define WHO Claude becomes Define WHAT Claude does
Focus Persona and expertise Workflow and process
Structure Single .md file Directory with SKILL.md + resources
Resources No bundled resources Can bundle scripts, references, assets
Invocation @agent-name Natural language
Use Case Domain expertise Specific tasks

When to Use Each

Use an Agent:

  • Providing expertise across many scenarios
  • Establishing consistent domain philosophy
  • Adopting a specialized role
  • "I need a React expert to help with various frontend challenges"

Use a Skill:

  • Executing a specific workflow
  • Bundling scripts or documentation
  • Step-by-step processes
  • "I need to scaffold an IoT Edge module"

Use Both: Many plugins benefit from having both:

  • Agent: frontend-developer (general React/Next.js expertise)
  • Skill: create-react-component (specific scaffolding workflow)

Quick Reference Card

Agent File Template

---
name: agent-name
description: One-sentence expertise description
model: sonnet
---

# Agent Name

## Purpose
[2-3 sentences defining role]

## Capabilities
### Category 1
- Bullet points

### Category 2
- Bullet points

## Behavioral Traits
- Value 1
- Priority 2

## Knowledge Base
- Source 1
- Framework 2

## Response Approach
1. Step 1
2. Step 2

## Example Interactions
**Example 1:** [Title]
User: [Question]
Agent approach: [Response strategy]

File Location

plugins/[plugin-name]/agents/[agent-name].md

Naming Convention

  • Lowercase with hyphens
  • Descriptive of expertise: frontend-developer.md
  • Focus on domain: database-architect.md

Resources

Ready to create your first agent? Start by defining the domain expertise, then build out the capabilities and behavioral traits. Test with real scenarios to refine the agent's persona and approach.