How to Create a New Agent
Relevant source files
The following files were used as context for generating this wiki page:Introduction
In this project, Agents are specialized AI assistants designed with a focused purpose and a dedicated system prompt. They are used to automate complex, multi-step workflows such as comprehensive code reviews, managing Git branches and pull requests, or performing scheduled maintenance tasks. Unlike general-purpose prompts, agents are defined in their own files, allowing them to be version-controlled, reused, and invoked in automated processes like GitHub Actions.
This guide outlines the structure, configuration, and creation process for new agents. By encapsulating specific logic and instructions into an agent, you can create powerful, consistent, and automated teammates that enforce project conventions and handle repetitive work.
Sources: README.md:504-506, README.md:15-26
Agent File Structure
An agent is defined as a single Markdown file located within the .claude/agents/ directory. The filename should be descriptive and correspond to the agent's name (e.g., code-reviewer.md). Each file consists of two main parts: a YAML frontmatter block for configuration and the Markdown body which serves as the agent's system prompt.
Sources: README.md:89-91, README.md:507-509
This diagram shows the standard location for agent files in the project structure.
Sources: README.md:80-91
Agent Format Example
The file must start with a YAML frontmatter block containing configuration metadata, followed by the Markdown content that instructs the agent.
---
name: code-reviewer
description: Reviews code for quality, security, and conventions. Use after writing or modifying code.
model: opus
---
# Agent System Prompt
You are a senior code reviewer...
## Your Process
1. Run `git diff` to see changes
2. Apply review checklist
3. Provide feedback
## Checklist
- [ ] No TypeScript `any`
- [ ] Error handling present
- [ ] Tests included
Sources: README.md:518-533
Agent Configuration
Configuration is managed via the YAML frontmatter at the top of the agent's Markdown file. These fields define the agent's identity and operational parameters.
Sources: README.md:518-522, README.md:535-542
| Field | Required | Description |
|---|---|---|
name | Yes | A unique, lowercase name with hyphens (e.g., code-reviewer). |
description | Yes | A brief explanation of when and why to use the agent (max 1024 chars). |
model | No | The specific model to use, such as sonnet, opus, or haiku. |
tools | No | A comma-separated list of allowed tools for the agent to use. |
Sources: README.md:535-542
The System Prompt
The body of the Markdown file, following the frontmatter, is the system prompt. This is where you provide detailed instructions for the agent. A well-structured prompt is crucial for the agent to perform its task reliably.
Best Practices for Prompts
- Define a Persona: Start by telling the agent what its role is (e.g., "You are a senior code reviewer").
- Outline a Process: Provide a clear, step-by-step process for the agent to follow.
- Use Checklists: For review or validation tasks, a checklist ensures all criteria are checked. This is demonstrated in the
code-reviewer.mdagent. - Reference Project Rules: The prompt can and should refer to project-wide standards, such as those defined in
CLAUDE.md, to ensure consistency. For example, a code reviewer agent should enforce rules on error handling and UI states.
Sources: README.md:524-533, CLAUDE.md:32-46
Invoking an Agent
Agents are typically invoked within automated workflows, most notably GitHub Actions. The anthropics/claude-code-action can be used to run an agent as part of a CI/CD pipeline.
Sources: README.md:583-585
Example: PR Code Review Workflow
The .github/workflows/pr-claude-code-review.yml workflow demonstrates how to trigger the code-reviewer agent on every pull request. The prompt input for the action explicitly instructs Claude to use the standards defined in the agent's file.
The following diagram illustrates the flow of a PR review being initiated and handled by an agent.
The key part of the workflow file is the prompt that points to the agent definition:
- uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
model: claude-opus-4-5-20251101
prompt: |
Review this PR using .claude/agents/code-reviewer.md standards.
Run `git diff origin/main...HEAD` to see changes.
Sources: README.md:606-612
Summary
Creating a new agent involves defining its purpose and process in a structured Markdown file located in .claude/agents/. By using a combination of YAML frontmatter for configuration and a detailed system prompt for instructions, you can build specialized AI assistants. These agents can then be integrated into automated workflows, like GitHub Actions, to enforce quality, manage repository tasks, and streamline development processes, making them a powerful tool for project automation.
Sources: README.md:504-506, README.md:711-717