Creating Agents

Learn how to design and create specialized agents that are effective, memorable, and valuable.

Before You Start

Ask yourself these questions:

Is there a real need?

Does this fill a gap in the current roster?
Have you encountered situations where this agent would help?
Is this different from existing agents?

Is the scope right?

Is it narrow and deep (not broad and shallow)?
Can you define clear deliverables?
Are there measurable success metrics?

Do you have expertise?

Have you worked in this domain?
Do you know what makes someone effective in this role?
Can you provide real examples?

Avoid creating:

Generic “helper” agents (too broad)
Duplicates of existing agents
Agents for domains you don’t understand
Theoretical agents without practical application

Agent Design Process

Step 1: Define the Specialty

Identify the domain

What specific area does this agent master?Good Examples:

Email Marketing Automation Specialist
GraphQL API Performance Engineer
Mobile App Accessibility Expert
Developer Experience (DX) Designer

Bad Examples:

Marketing Helper (too broad)
API Developer (too generic)
Mobile Expert (not specific)
Designer (no specialty)

Define the target user

Who would activate this agent and when?Example:

## Email Marketing Automation Specialist

**Target User**: Marketing managers and growth teams

**When to Use**:
- Setting up email automation flows
- Optimizing email campaigns for conversion
- A/B testing email sequences
- Analyzing email performance
- Improving deliverability

Determine what makes them special

What unique value does this agent provide?Example:

## What Makes Them Special

Unlike general marketing agents:
- Deep expertise in email automation platforms
- Focus on deliverability and inbox placement
- Data-driven optimization approach
- Email-specific copywriting techniques
- Compliance knowledge (CAN-SPAM, GDPR)

Step 2: Craft the Personality

Personality should match the domain requirements.

Personality Traits
Voice & Character
Communication Style

Choose 3-5 core traits:Thoroughness:

Highly thorough (QA, compliance)
Balanced (most agents)
Speed-focused (prototyping, growth)

Communication:

Direct & evidence-based
Collaborative & guiding
Creative & strategic
Authentic & community-focused

Risk Tolerance:

Risk-averse (security, compliance)
Balanced risk (standard development)
High-risk tolerance (experimentation)

Scope:

Narrow & deep specialist
Coordinating & cross-functional

Example:

## Email Marketing Automation Specialist

**Personality Traits**:
- Data-driven and analytical
- Detail-oriented with deliverability
- Experimental with A/B testing
- Compliant and ethical
- Results-focused

Create a distinctive voice:Method 1: Signature QuoteWrite what this agent would say that others wouldn’t:

"I don't just send emails - I ensure they land in the inbox,
get opened, and drive action. Every sequence I design has a
30%+ open rate minimum and clear conversion goals."

Method 2: Default BehaviorsWhat does this agent do automatically?

**Default Behaviors**:
- Check deliverability before launch
- A/B test subject lines (minimum)
- Segment audiences for relevance
- Track conversion, not just opens
- Monitor spam complaints

Method 3: What They HateStrong opinions create memorable character:

**Pet Peeves**:
- "Blast" emails to entire list
- No segmentation or personalization
- Buying email lists
- Ignoring unsubscribe requests
- Clickbait subject lines

How does this agent speak?Examples:

## Communication Examples

### Reporting Success
"Welcome sequence now achieving 42% open rate (up from 28%),
with 8.5% click-through on CTA. Deliverability at 98.2%.
Next optimization: test 2-day vs 3-day delay on email 2."

### Identifying Issues
"Spam complaint rate jumped to 0.3% - above our 0.1% threshold.
Root cause: segment includes users who haven't engaged in 6
months. Recommend re-engagement campaign or list cleanup."

### Making Recommendations
"Let's split test two subject lines: 'Save 30% this week'
(direct value) vs 'Your exclusive member discount' (exclusivity).
Test on 20% of list, send winner to remaining 80%."

Step 3: Design Deliverables

What concrete outputs does this agent produce?

Code & Implementation

Provide runnable, real-world code:

// Email automation workflow configuration
const welcomeSequence = {
  trigger: 'user_signup',
  emails: [
    {
      delay: 0, // Immediate
      subject: 'Welcome to {{company_name}}!',
      template: 'welcome-01',
      personalization: ['first_name', 'signup_source'],
      goals: ['profile_completion'],
    },
    {
      delay: 2 * 24 * 60 * 60 * 1000, // 2 days
      subject: 'Get started with your first project',
      template: 'welcome-02',
      conditions: [
        { field: 'profile_completed', value: true },
      ],
      goals: ['first_project_created'],
    },
    {
      delay: 5 * 24 * 60 * 60 * 1000, // 5 days
      subject: 'Tips from {{expert_name}}',
      template: 'welcome-03',
      abTest: {
        variants: ['expert-tips-a', 'expert-tips-b'],
        splitRatio: 0.5,
      },
      goals: ['feature_adoption'],
    },
  ],
  exitConditions: [
    'user_unsubscribed',
    'user_churned',
    'completed_sequence',
  ],
};

Templates & Frameworks

Provide ready-to-use templates:

# Email Sequence Template

## Welcome Sequence (5 emails, 14 days)

### Email 1: Immediate Welcome
**Goal**: Set expectations, provide quick win
**Subject Line Options**:
- A: "Welcome to [Product] - Let's get started"
- B: "Your [Product] account is ready!"
**Content**:
- Welcome message
- Account confirmation
- Quick start guide (1-2 steps)
- Support link

### Email 2: Day 2 - Education
**Goal**: Feature awareness, first activation
**Condition**: Opened Email 1 OR completed signup
**Subject Line Options**:
- A: "3 ways to [achieve goal] with [Product]"
- B: "Getting started: Your first [deliverable]"
**Content**:
- Top 3 features
- Video tutorial
- Use case example
- CTA to first action

[Continue for all 5 emails...]

Processes & Checklists

Provide step-by-step procedures:

## Email Campaign Launch Checklist

### Pre-Launch (1 week before)
- [ ] Segment defined and audience exported
- [ ] Email copy written and reviewed
- [ ] Subject lines (2-3 variants for A/B test)
- [ ] Design completed and responsive
- [ ] Personalization tokens tested
- [ ] Links validated
- [ ] Preview text optimized
- [ ] Unsubscribe link present
- [ ] Spam check passed (score < 5)

### Testing (2 days before)
- [ ] Send test emails to team
- [ ] Check rendering in major clients (Gmail, Outlook, Apple Mail)
- [ ] Verify mobile responsive design
- [ ] Test all CTAs and links
- [ ] Confirm tracking pixels
- [ ] Review deliverability score

### Launch Day
- [ ] Final approval from stakeholder
- [ ] Schedule or send campaign
- [ ] Monitor first hour performance
- [ ] Check spam complaints
- [ ] Verify tracking data

### Post-Launch (24-48 hours)
- [ ] Analyze open rates
- [ ] Review click-through rates
- [ ] Check conversion tracking
- [ ] Monitor deliverability
- [ ] Document learnings

Reports & Analysis

Provide analysis templates:

# Email Campaign Performance Report

## Campaign: [Name]
**Date**: [Launch Date]
**Audience**: [Segment Description]
**List Size**: [Number]

## Performance Metrics

| Metric | Result | Benchmark | Status |
|--------|--------|-----------|--------|
| Deliverability | 98.5% | >98% | ✅ |
| Open Rate | 32.4% | >25% | ✅ |
| Click Rate | 6.8% | >4% | ✅ |
| Conversion Rate | 2.1% | >1.5% | ✅ |
| Unsubscribe Rate | 0.08% | <0.2% | ✅ |
| Spam Complaints | 0.02% | <0.1% | ✅ |

## A/B Test Results

**Subject Line Test**:
- Variant A: "Save 30% this week" - 30.2% open rate
- Variant B: "Your exclusive discount" - 34.6% open rate
- **Winner**: Variant B (+14.6% lift)

## Insights & Recommendations

### What Worked
1. Exclusivity messaging outperformed direct discount
2. Tuesday 10am send time optimal
3. Segmentation by engagement level effective

### Areas for Improvement
1. CTA button color - test variations
2. Email length - test shorter format
3. Personalization - add more dynamic content

### Next Campaign
- Use "exclusive" angle in subject lines
- Continue Tuesday morning sends
- Increase personalization beyond name
- Test 2-column vs single-column layout

Step 4: Define Workflows

How does this agent approach their work?

## Email Campaign Workflow

### Phase 1: Strategy (Day 1)
- Define campaign goals
- Identify target audience
- Research competitive emails
- Plan content themes

### Phase 2: Planning (Day 2-3)
- Write email copy
- Design email layout
- Plan A/B tests
- Set up tracking

### Phase 3: Testing (Day 4-5)
- Technical testing
- Deliverability check
- Preview in email clients
- Stakeholder review

### Phase 4: Launch (Day 6)
- Schedule/send campaign
- Monitor performance
- Quick response to issues

### Phase 5: Analysis (Day 7-10)
- Analyze results
- Document learnings
- Plan optimizations

Step 5: Set Success Metrics

How do you measure this agent’s effectiveness?

Quantitative Metrics
Qualitative Metrics
Process Metrics

Numbers-based measurements:

## Success Metrics

### Email Performance
- Open rate > 25% (industry: 20%)
- Click rate > 4% (industry: 2.5%)
- Conversion rate > 1.5% (industry: 1%)
- Unsubscribe rate < 0.2%
- Spam complaints < 0.1%

### Deliverability
- Inbox placement > 95%
- Deliverability rate > 98%
- Bounce rate < 2%
- Sender reputation > 95/100

### Business Impact
- Revenue per email > $0.50
- Email-attributed revenue > 15% of total
- List growth > 10% MoM
- Engaged subscriber rate > 40%

Quality-based measurements:

## Qualitative Success Indicators

### Content Quality
- Email copy aligns with brand voice
- Value-first approach (not just selling)
- Personalization feels relevant
- Design enhances readability

### Audience Relationship
- Subscribers engage consistently
- Positive reply rate
- Low complaint rate
- Strong brand sentiment

### Team Efficiency
- Campaign creation time reduced
- Fewer iterations needed
- Stakeholder approval faster
- Documentation comprehensive

Workflow efficiency:

## Process Efficiency Metrics

### Speed
- Campaign creation: < 1 week
- A/B test setup: < 2 hours
- Performance analysis: < 1 day

### Quality
- First-send success rate > 95%
- Rework required < 10%
- Technical issues < 1%

### Learning
- A/B tests per month: > 10
- Insights documented: 100%
- Learnings applied: > 80%

Agent File Structure

Every agent follows this template:

---
name: Agent Name
description: One-line description of specialty
color: colorname or "#hexcode"
---

# Agent Name

## 🧠 Your Identity & Memory
- **Role**: Clear role description
- **Personality**: Personality traits and communication style
- **Memory**: What the agent remembers and learns
- **Experience**: Domain expertise and perspective

## 🎯 Your Core Mission
- Primary responsibility 1 with clear deliverables
- Primary responsibility 2 with clear deliverables
- Primary responsibility 3 with clear deliverables
- **Default requirement**: Always-on best practices

## 🚨 Critical Rules You Must Follow
Domain-specific rules and constraints that define the agent's approach

## 📋 Your Technical Deliverables
Concrete examples of what the agent produces:
- Code samples
- Templates
- Frameworks
- Documents

## 🔄 Your Workflow Process
Step-by-step process the agent follows:
1. Phase 1: Discovery and research
2. Phase 2: Planning and strategy
3. Phase 3: Execution and implementation
4. Phase 4: Review and optimization

## 💭 Your Communication Style
- How the agent communicates
- Example phrases and patterns
- Tone and approach

## 🔄 Learning & Memory
What the agent learns from:
- Successful patterns
- Failed approaches
- User feedback
- Domain evolution

## 🎯 Your Success Metrics
Measurable outcomes:
- Quantitative metrics (with numbers)
- Qualitative indicators
- Performance benchmarks

## 🚀 Advanced Capabilities
Advanced techniques and approaches the agent masters

See the full Agent Template for details.

Testing Your Agent

Before submitting:

Self-test

Use the agent yourself in real scenarios:

Does it produce useful outputs?
Is the personality distinctive?
Are the deliverables practical?
Do the workflows make sense?

Peer review

Have someone else try the agent:

Can they understand the specialty?
Do they get consistent results?
Is the voice clear?
Are there gaps or confusion?

Real-world validation

Use it on an actual project:

Track what works well
Note what needs improvement
Iterate based on results
Document learnings

Common Mistakes

Too Broad

Problem: Agent tries to do too muchExample: “Marketing Expert” covers all of marketingFix: Narrow to specific specialty like “Email Marketing Automation Specialist”

Generic Personality

Problem: Agent sounds like every other agentExample: “I am a helpful assistant who will help you with…”Fix: Create distinctive voice with specific default behaviors and opinions

Vague Deliverables

Problem: No concrete outputs definedExample: “I will help you create better emails”Fix: “I create email sequences with 30%+ open rates, A/B test plans, and deliverability optimization”

No Real Examples

Problem: Only pseudo-code or theoretical examplesFix: Provide real, runnable code and actual templates used in production

Missing Metrics

Problem: No way to measure successFix: Define specific, measurable outcomes with target numbers

Next Steps

Agent Template

Use the complete template

Contributing Overview

How to submit your agent

Agent Design

Design philosophy deep-dive

Example Agents

Study existing agents for inspiration

Get Started

Core Concepts

Use Cases

Contributing

Creating Agents

Creating Agents

Before You Start

Agent Design Process

Step 1: Define the Specialty

Step 2: Craft the Personality

Step 3: Design Deliverables

Step 4: Define Workflows

Step 5: Set Success Metrics

Agent File Structure

Testing Your Agent

Common Mistakes

Next Steps

Agent Template

Contributing Overview

Agent Design

Example Agents

Build docs developers (and LLMs) love

Get Started

Core Concepts

Use Cases

Contributing

​Creating Agents

​Before You Start

​Agent Design Process

​Step 1: Define the Specialty

​Step 2: Craft the Personality

​Step 3: Design Deliverables

​Step 4: Define Workflows

​Step 5: Set Success Metrics

​Agent File Structure

​Testing Your Agent

​Common Mistakes

​Next Steps

Agent Template

Contributing Overview

Agent Design

Example Agents

Build docs developers (and LLMs) love

Creating Agents

Before You Start

Agent Design Process

Step 1: Define the Specialty

Step 2: Craft the Personality

Step 3: Design Deliverables

Step 4: Define Workflows

Step 5: Set Success Metrics

Agent File Structure

Testing Your Agent

Common Mistakes

Next Steps