Creating Agents

Purpose

Create well-formed agent definitions following established patterns. Avoid duplication, ensure proper structure.

Agent Structure

---
name: agent-name
description: Brief one-line description explaining WHEN to use
---

# Agent Title

## Purpose
Clear statement of what this agent does

[Main content sections...]

Frontmatter:

• name: kebab-case
• description: One line, action-oriented (~60 chars)

- Good: "Python toolchain setup and configuration standards" - Bad: "An agent that helps with Python"

Location Guidelines

• Project-specific: .claude/agents/
• User-global: ~/.claude/agents/ (only if requested)
• Always check existing agents first to avoid overlap

Agent Types

Stack/Tooling ([language]-stack):

• Toolchain and tools
• Configuration files
• Quality thresholds

Workflow (process name):

• Step-by-step process
• When to use / avoid
• Examples and anti-patterns

Standards ([topic]-standards):

• Rules and conventions
• Rationale
• Verification

Setup ([tool]-setup):

• Installation
• Configuration
• Verification

Naming Patterns

• [language]-stack - python-stack, javascript-stack
• [tool]-setup - git-setup, docker-setup
• [topic]-standards - context-standards
• [process] - refactorer, software-engineer
• [feature]-[aspect] - design-system, website-forms

Design Principles

Scope clearly: Define what's IN scope (specific problem) and OUT of scope (reference other agents).

Define the trigger: What problem does this solve? Who uses it and when?

Match structure to type:

Stack agents:

## Toolchain
## Project Structure
## Setup Commands
## Configuration Files
## Quality Thresholds
## Common Patterns

Workflow agents:

## Purpose
## When to Use
## Workflow Steps
## Examples
## Common Pitfalls

Porting Principles

When creating similar agents from references:

• Extract the agentic skills/goals, not just content
• Identify common sections and universal principles
• Adapt quality thresholds for target domain
• Match structure from references
• Maintain consistent voice/detail level

Editing Guidelines

• Read existing agent first to understand scope and patterns
• Make surgical changes - don't rewrite unnecessarily
• Preserve style and maintain consistency with purpose
• Validate references still work after changes

Common Mistakes

• Overlapping agents - check existing first
• Vague descriptions - be specific about when to use
• Missing frontmatter
• Broken references
• Wrong location
• Duplicating content - reference instead
• Mega-agents - stay focused

Verification

# Check frontmatter
head -5 .claude/agents/agent-name.md

# Validate references
grep -o '@[a-z-]*' .claude/agents/agent-name.md

# Check naming
echo "agent-name" | grep -E '^[a-z][a-z0-9-]*$'