README

Overview

This directory contains research findings on developing custom Claude Code agents and the testing workflow needed for iterative development.

Research Tasks Completed

✅ Task 1: Agent Specification Research

Status: Complete Documentation: agent-spec.md

Researched and documented the complete specification for Claude Code custom agents including:

• File structure and storage locations
• YAML frontmatter configuration
• Tool restrictions and model selection
• Best practices and common patterns
• Example agent structures

Key Findings:

• Agents are Markdown files with YAML frontmatter
• Stored in .claude/agents/*.md (project) or ~/.claude/agents/*.md (user)
• Critical fields: name, description, tools, model
• The description field is crucial for proper delegation
• Tool restriction improves security and focus

✅ Task 2: Headless Mode Verification

Status: Confirmed Working Documentation: headless-testing.md

Verified that Claude can run in headless mode via CLI:

$ claude -p "What is 2+2?"
4

Key Findings:

• -p/--print flag enables non-interactive mode
• Outputs response to stdout and exits
• Supports multiple output formats (text, json, stream-json)
• Can continue conversations with --continue
• Provides extensive configuration options

✅ Task 3: Headless Agent Invocation

Status: Discovered and Documented Documentation: headless-agent-testing-guide.md

Key Discovery: Agents CAN be invoked in headless mode with explicit syntax:

claude -p "Use the [agent-name] and provide its complete response. [task]"

Example:

$ claude -p "Use the simple-agent and provide its complete response."
SIMPLE AGENT ACTIVATED
Agent: simple-agent
Status: Working!
✅ The agent was successfully invoked
✅ Custom agents are working correctly

Critical Requirements:

1. Run from project root (where .claude/agents/ exists)
2. Explicitly name the agent: “Use the [agent-name]”
3. Request complete response: “and provide its complete response”
4. Complex agents may timeout - use simpler test queries

The Development Challenge

Problem: Agent files are loaded when Claude Code starts. Changes to agent .md files require restarting the interactive session to take effect.

Solution: Use headless mode for rapid iterative testing.

Recommended Development Workflow

# 1. Create or edit agent
vim .claude/agents/my-agent.md

# 2. Test immediately in headless mode (loads fresh agent definitions)
# IMPORTANT: Explicitly invoke the agent by name!
claude -p "Use the my-agent and provide its complete response. Test functionality."

# 3. Iterate rapidly without session restarts
vim .claude/agents/my-agent.md
claude -p "Use the my-agent and provide its complete response. Test with different input."
claude -p "Use the my-agent and provide its complete response. Edge case testing."

# 4. Once satisfied, restart interactive session for production use
# (Only restart when you're done iterating)

Key Pattern for Headless Testing:

claude -p "Use the [agent-name] and provide its complete response. [your task]"
          ^^^^^^^^^^^^^^^^       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^
          Explicit agent         Request raw output            Your test

Quick Start

Create Your First Agent

# 1. Create agent file
cat > .claude/agents/example.md << 'EOF'
---
name: example
description: Example agent that demonstrates basic structure
tools: Read, Write
model: haiku
---

You are an example agent. Your purpose is to demonstrate
the basic structure and capabilities of Claude Code agents.
EOF

# 2. Test it immediately
claude -p "Show me how the example agent works"

# 3. Iterate and refine
vim .claude/agents/example.md
claude -p "Test again"

Testing Patterns

# Fast testing with Haiku
claude -p "Quick test" --model haiku

# Realistic testing with Sonnet
claude -p "Real world test" --model sonnet

# JSON output for automation
claude -p "Generate data" --output-format json

# Tool restrictions
claude -p "Read only test" --tools "Read,Grep"

# Continue conversation
claude -p "First prompt"
claude -p "Follow up" --continue

Documentation Structure

agent-spec.md

Complete specification of the agent file format:

• File structure and YAML frontmatter
• Configuration fields and options
• System prompt guidelines
• Example agent structures
• Best practices and patterns
• Troubleshooting guide

headless-testing.md

Comprehensive guide to headless mode testing:

• Basic usage and options
• Agent development workflow
• Testing patterns and examples
• Scripting and automation
• Debugging techniques
• Best practices

README.md (this file)

Overview and quick reference for the research.

Key Insights

Agent Development

1. Description is critical: It determines when agents are invoked
2. Tool restriction improves focus: Limit to minimum required
3. Start simple: Iterate based on real usage
4. Use appropriate models: Haiku for speed, Sonnet for balance, Opus for complexity

Testing Strategy

1. Headless mode is essential: Enables rapid iteration without restarts
2. Test incrementally: Small changes, quick validation
3. Use JSON output: Enables automation and verification
4. Script your tests: Build regression suites

Workflow Optimization

1. Separate testing from production: Use headless for development, interactive for real work
2. Only restart when satisfied: Minimize disruption to interactive sessions
3. Version your agents: Track changes like code
4. Document learnings: Update agent prompts with insights

Project Structure Created

.claude/
└── agents/              # Project-level agents (created)
    └── (your agents here)

~/.claude/
└── agents/              # User-level agents (already exists)
    ├── collaboration-analyst.md
    └── diagram-generator.md

Next Steps

To set up an agent development environment:

1. Create test agent directory structure

   mkdir -p .claude/agents
   mkdir -p test/agent-tests

2. Create a test harness script

   #!/bin/bash
   for test in test/agent-tests/*.txt; do
     echo "Testing: $test"
     claude -p "$(cat $test)" --output-format json
   done

3. Set up CI/CD integration

   • Run headless tests on commits
   • Validate agent syntax
   • Check for regression

4. Create agent templates

   • Starter templates for common patterns
   • Boilerplate for new agents

5. Build agent library

   • Catalog of reusable agents
   • Documentation and examples
   • Version management

Additional Resources

Built-in Examples

# View existing agents
ls -la ~/.claude/agents/
cat ~/.claude/agents/collaboration-analyst.md
cat ~/.claude/agents/diagram-generator.md

CLI Help

# View all options
claude --help

# View agent-specific help
claude --help | grep -A5 agents

Online Documentation

• Claude Code: Use /help command in interactive mode
• Agent SDK: Additional capabilities for plugin development

Environment Requirements

• Claude Code: Installed and authenticated
• Shell access: For headless mode testing
• Text editor: For editing agent files
• Optional: jq for JSON processing

Verification

All research findings have been verified:

✅ Agent spec researched and documented ✅ Headless mode confirmed working ✅ Documentation created ✅ Quick start examples provided ✅ Workflow optimization documented

Summary

This research establishes a complete foundation for iterative Claude Code agent development:

• Specification: Complete understanding of agent file format
• Testing: Headless mode enables rapid iteration
• Workflow: Optimized development cycle without session restarts
• Documentation: Comprehensive guides for reference

You can now develop agents efficiently using the headless testing workflow!