Skip to main content

Agent Definition Guide: Creating Custom Agents

Need an agent that specializes in React development? Or one focused on security auditing? You can create custom agents tailored to your specific needs using simple markdown files.

What Are Agents?​

Think of agents like different specialists for your development team:

  • Agent: A specialized AI assistant with specific expertise, tools, and behavior patterns - like having expert consultants for different development tasks
  • Agent Definition File: A markdown file containing YAML configuration and system instructions that define the agent's capabilities and behavior
  • System Prompt: The markdown content that defines the agent's personality, expertise, and specific instructions
  • Tools: Specific capabilities an agent can use, such as reading files, running commands, or searching code

What You'll Need​

  • Forge installed and running
  • Access to create directories in your home folder
  • Basic familiarity with YAML syntax

Quick Start: Create Your First Agent​

Follow these steps to create and use a custom agent in under 5 minutes:

Step 1: Choose Your Agent Storage Location​

You have two options for storing custom agents:

Global Agents (Recommended for most cases)

  • Location: ~/forge/agents/ (Unix/macOS) or %USERPROFILE%\forge\agents\ (Windows)
  • Available across all projects and Forge sessions
  • Use for general-purpose agents you'll reuse

Project-Specific Agents

  • Location: .forge/agents/ (in your project root - note the dot prefix)
  • Override global agents with the same ID
  • Use for project-specific customizations

Step 2: Create the Agent Directory​

For Global Agents:

# macOS/Linux
mkdir -p ~/forge/agents
ls -la ~/forge/agents

# Windows Command Prompt
mkdir "%USERPROFILE%\forge\agents"
dir "%USERPROFILE%\forge\agents"

# Windows PowerShell
New-Item -ItemType Directory -Path "$env:USERPROFILE\forge\agents" -Force
Get-ChildItem "$env:USERPROFILE\forge\agents"

For Project-Specific Agents: macOS/Linux:

# macOS/Linux
mkdir -p .forge/agents
ls -la .forge/agents

Windows Command Prompt:

mkdir ".forge\agents"
dir ".forge\agents"

Windows PowerShell:

New-Item -ItemType Directory -Path ".forge\agents" -Force
Get-ChildItem ".forge\agents"

Step 3: Create Your Agent Definition File​

Create frontend-expert.md in your chosen directory:

---
id: frontend-expert
title: Frontend Development Expert
description: React, TypeScript, and modern frontend specialist
---

You are a frontend development expert specializing in React and TypeScript.

Focus on writing clean, maintainable code with proper TypeScript interfaces, accessibility attributes, and comprehensive testing using React Testing Library.

Always explain your architectural decisions and provide working examples.

Important: The filename can be anything ending in .md, but the id field in the YAML must be unique across all your agents.

Step 4: Load Your Agent​

  1. Restart Forge to discover new agents
  2. Use the /agent command to view available agents
  3. Select "FRONTEND_EXPERT" from the list
  4. Your custom agent is now active

Agent Definition File Structure​

Every agent definition file follows this structure:

---
# YAML Configuration (frontmatter) - defines capabilities and behavior
id: unique-identifier
title: Human Readable Name
description: Brief description of capabilities
# Additional options...
---

Your system prompt content goes here as regular markdown.
This section defines the agent's expertise and specific instructions.

Configuration Requirements and Validation​

Forge validates all agent definitions during startup. Understanding these rules prevents common errors:

Validation Rules​

  • Unique IDs: Each id must be unique across all agent definition files
  • Valid YAML: Frontmatter must use proper YAML syntax (spaces, not tabs)
  • Recognized Tools: Only supported tools allowed in the tools array
  • Parameter Ranges: All numeric values must be within valid ranges (see table below)

Parameter Constraints​

ParameterValid RangeDefaultPurpose
idRequired-Must be unique across all agents
max_turns0+100Maximum conversation turns
max_walker_depth0+1File tree traversal depth
max_tool_failure_per_turn0+3Max tool failures before completion
max_requests_per_turn0+100Max requests in single turn
temperature0.0 - 2.0ProviderResponse creativity (0=precise, 2=creative)
top_p0.0 - 1.00.8Nucleus sampling threshold
top_k1 - 100030Top-k sampling limit
max_tokens1 - 100,00020480Maximum response length

Configuration Options​

Required Configuration​

Only one field is mandatory:

---
id: unique-agent-identifier
---

Model and Provider Selection​

You can customize which model and provider your agent uses:

---
id: my-agent
model: claude-sonnet-4 # Optional: Override the default model
provider: open_ai # Optional: Override the default provider
---

Provider naming rules:

  • Provider names must be in snake_case format
  • Examples of valid provider names:
    • provider: openai
    • provider: open_router
    • provider: requesty
    • provider: anthropic

When to specify a provider:

  • If you want to use a specific provider instead of the default
  • When using models available on multiple providers
  • For testing different provider implementations
  • Leave unspecified to use the default provider configured in Forge

For agents that can be used as tools by other agents:

---
id: unique-agent-identifier
title: Human Readable Agent Name
description: Brief description of agent capabilities
---

Note: Agents without a description field cannot be used as tools by other agents.

Complete Configuration Reference​

---
# REQUIRED
id: backend-api-expert

# RECOMMENDED
title: Backend API Specialist
description: Expert in REST APIs, databases, and server architecture

# MODEL SELECTION
model: claude-sonnet-4 # Any supported model ID
provider: anthropic # Optional: override the default provider (must be in snake_case)

# USER PROMPT (Template with Handlebars syntax)
user_prompt: |-
  {{#if (eq event.name 'backend-api-expert/user_task_update')}}
  <feedback>{{event.value}}</feedback>
  {{else}}
  <task>{{event.value}}</task>
  {{/if}}
  <system_time>{{current_time}}</system_time>

# BEHAVIOR CUSTOMIZATION
custom_rules: |
  - Use dependency injection for services
  - Add comprehensive error handling
  - Include request/response logging
  - Write integration tests for all endpoints

# TOOL ACCESS (specify which tools this agent can use)
tools:
  - read
  - write
  - patch
  - shell
  - search

# CONVERSATION LIMITS
max_turns: 100 # Maximum conversation length (default: 100)
max_walker_depth: 3 # File tree traversal depth (default: 1)
max_tool_failure_per_turn: 3 # Max tool failures before forcing completion (default: 3)
max_requests_per_turn: 10 # Max requests in a single turn (default: 100)

# MODEL PARAMETERS (All optional with validation)
temperature: 0.2 # Creativity level: 0.0 to 2.0 (default: provider default)
top_p: 0.9 # Nucleus sampling: 0.0 to 1.0 (default: 0.8)
top_k: 40 # Top-k sampling: 1 to 1000 (default: 30)
max_tokens: 4096 # Maximum response length: 1 to 100,000 tokens (default: 20480)

# CONTEXT COMPACTION (Optional - automatic context management)
compact:
  # Triggering thresholds (ANY condition triggers compaction)
  token_threshold: 100000 # Trigger when context exceeds this many tokens
  message_threshold: 200 # Trigger after this many total messages
  turn_threshold: 50 # Trigger after this many user turns (optional)
  on_turn_end: false # Trigger on user message (use with caution, default: false)

  # Compaction strategy (controls what to preserve)
  retention_window: 6 # Number of recent messages to preserve unchanged
  eviction_window: 0.2 # Percentage (0.0-1.0) of context to compact

  # Summarization settings
  max_tokens: 2000 # Maximum tokens for the generated summary
  model: claude-sonnet-4 # Model to use for compaction (optional)
  prompt: | # Custom compaction prompt (optional)
    Summarize the following conversation context while preserving key technical details.

# REASONING CONFIGURATION (Optional - for models that support reasoning)
reasoning:
  enabled: true # Enable reasoning mode (default: false)
  effort: medium # Reasoning effort: low, medium, high (optional)
  max_tokens: 2048 # Max tokens for reasoning (must be > 1024, < max_tokens)
  exclude: false # Hide reasoning from output (default: false)

# ADVANCED FEATURES
tool_supported: true # Enable this agent as a tool for other agents (default: true)
---
You are a backend development expert specializing in APIs and server architecture.

Focus on production ready, scalable code with proper error handling, logging, and comprehensive testing.

Available Tools and When to Use Them​

You can customize which tools each agent has access to using exact names or glob patterns for flexible configuration.

Tool Configuration with Glob Patterns​

Instead of listing every tool individually, use glob patterns to grant access to tool families:

---
id: my-agent
title: My Custom Agent
tools:
  - read # Exact tool name
  - write
  - "mcp_*" # All MCP tools (mcp_weather, mcp_database, etc.)
  - search
---

Check the list of built-in tools.

Glob Pattern Syntax​

PatternDescriptionExample
*Match any charactersmcp_* matches all MCP tools
?Match single characterread? matches read1, read2
[...]Match character classtool[123] matches tool1, tool2, tool3

Built-in Tools​

  • read - Read files and directories
    • Use for: Code analysis, documentation review, configuration inspection
  • write - Create and modify files
    • Use for: Generating new code, creating documentation, updating configurations
  • patch - Apply targeted changes to files
    • Use for: Bug fixes, small modifications, refactoring
  • remove - Delete files
    • Use for: Cleanup tasks, removing deprecated code
  • shell - Execute shell commands
    • Use for: Running tests, building projects, system operations
  • fetch - Retrieve external resources
    • Use for: API calls, downloading dependencies, checking external services
  • search - Search within files
    • Use for: Finding code patterns, locating specific functions, analyzing codebases
  • undo - Reverse previous changes
    • Use for: Error recovery, experimentation
  • plan - Create implementation plans
    • Use for: Breaking down complex tasks, project planning
  • followup - Ask clarifying questions
    • Use for: Gathering requirements, clarifying ambiguous requests

MCP Tools (External Integrations)​

MCP (Model Context Protocol) tools connect your agents to external services. Once configured, can be accessed using glob patterns.

Popular integrations:

  • Weather data for real-time information
  • Database connections (PostgreSQL, MySQL)
  • Email services for notifications
  • Browser automation for testing

Example: Grant access to all MCP tools automatically:

tools:
  - read
  - write
  - search
  - "mcp_*" # Automatically includes all MCP tools like mcp_weather, mcp_database, etc.

Benefits of using glob patterns for MCP tools:

  • Automatic Access: New MCP servers you add are automatically available to the agent
  • No Configuration Updates: Don't need to modify agent definitions when adding MCP tools
  • Flexible Control: Can still restrict specific MCP tools if needed

Use /tools in Forge to see all available tools (MCP tools are listed separately).

Learn more: MCP Integration Guide

Agent Examples​

Frontend Development Specialist​

---
id: frontend-dev
title: Frontend Development Expert
description: React, TypeScript, and modern frontend best practices
model: claude-sonnet-4
temperature: 0.1
custom_rules: |
  - Use TypeScript strict mode
  - Prefer functional components with React hooks
  - Add comprehensive PropTypes or TypeScript interfaces
  - Include ARIA attributes for accessibility
  - Write tests using React Testing Library
  - Optimize for Core Web Vitals
tools:
  - read
  - write
  - patch
  - "mcp_*" # All MCP tools for external integrations
max_turns: 50
---

You are a frontend development expert specializing in React and TypeScript.

## Key Focus Areas:

- Component architecture and reusability
- Performance optimization techniques
- Accessibility (WCAG 2.1 compliance)
- Modern CSS and styling solutions
- State management patterns

Always provide working code examples and explain your architectural decisions.

Backend API Specialist​

---
id: backend-api
title: Backend API Specialist
description: REST APIs, databases, and scalable server architecture
model: claude-sonnet-4
temperature: 0.15
custom_rules: |
  - Use dependency injection patterns
  - Add comprehensive error handling with proper HTTP status codes
  - Include structured logging with correlation IDs
  - Write integration tests for all endpoints
  - Follow OpenAPI/Swagger documentation standards
  - Implement proper authentication and authorization
tools:
  - read
  - write
  - patch
  - shell
  - "mcp_*" # Database and external service integrations
max_turns: 75
---

You are a backend development expert specializing in APIs and server architecture.

## Key Responsibilities:

- Design RESTful APIs following industry standards
- Database schema design and optimization
- Security best practices implementation
- Performance optimization and caching strategies
- Microservices architecture patterns

Provide production ready code with proper error handling and monitoring.

Security Code Auditor​

---
id: security-auditor
title: Security Code Auditor
description: Identifies security vulnerabilities and recommends fixes
model: claude-sonnet-4
temperature: 0.05
custom_rules: |
  - Identify potential security vulnerabilities
  - Suggest specific remediation steps
  - Follow OWASP guidelines
  - Check for common security anti-patterns
  - Recommend security testing approaches
tools:
  - read
  - search
max_turns: 30
reasoning:
  enabled: true
---

You are a security expert focused on identifying and fixing security vulnerabilities in code.

## Security Focus Areas:

- Input validation and sanitization
- Authentication and authorization flaws
- Injection vulnerabilities (SQL, XSS, CSRF)
- Insecure data handling
- Dependency vulnerabilities

Always provide specific, actionable security recommendations with code examples.

Customizing Built-in Agents​

Instead of creating agents from scratch, you can customize Forge's built-in agents (Forge, Muse, Sage, Parker, Prime) to match your project needs.

How Customization Works​

Forge loads agents in this priority order:

  1. Project-specific (.forge/agents/ - highest priority)
  2. Global (~/forge/agents/)
  3. Built-in (embedded in Forge - lowest priority)

The filename doesn't matter - only the id field in the YAML frontmatter must match the built-in agent you want to override.

Setting Up Agent Customization​

Create a markdown file in your agents directory with the appropriate id:

  • id: "forge" - customize the Forge agent
  • id: "muse" - customize the Muse agent
  • id: "sage" - customize the Sage agent
  • id: "parker" - customize the Parker agent
  • id: "prime" - customize the Prime agent

Customization Example​

Here's how to customize the Forge agent for frontend development. Create my-custom-forge.md in .forge/agents/:

---
id: "forge"
title: "Frontend-Focused Forge"
description: "Forge agent specialized for frontend development with React and TypeScript"
reasoning:
  enabled: true
tools:
  - read
  - write
  - patch
  - shell
---

You are a specialized development agent for our React TypeScript project.

## Your Frontend Focus:

- **React & TypeScript**: Build modern, type-safe components
- **UI/UX**: Create responsive, accessible interfaces
- **Performance**: Optimize for Core Web Vitals and user experience
- **Testing**: Write comprehensive tests for components and user interactions
- **Best Practices**: Follow modern frontend patterns and conventions

## Your Approach:

- Always explain your architectural decisions
- Provide working code examples with proper TypeScript types
- Include accessibility considerations (ARIA attributes, semantic HTML)
- Suggest performance optimizations when relevant
- Write tests alongside implementation

You maintain all of Forge's capabilities but with deep frontend expertise.

Troubleshooting​

Common Issues and Solutions​

Agent not appearing in selection list

  1. Verify file location:
    • Global: ~/forge/agents/ or %USERPROFILE%\forge\agents\
    • Project: .forge/agents/ (note the dot prefix)
  2. Ensure .md file extension
  3. Check YAML frontmatter is valid
  4. Confirm id field exists and is unique
  5. Restart Forge to reload agents

"Invalid YAML" errors

  1. Use an online YAML validator to check syntax
  2. Use spaces for indentation, not tabs
  3. Quote strings containing special characters
  4. Use | for multiline strings with preserved line breaks
  5. Use > for multiline strings with folded line breaks

Agent validation warnings

  1. Check parameter values are within valid ranges (see constraints table)
  2. Verify all tools in tools array are recognized
  3. Ensure reasoning.max_tokens > 1024 and < max_tokens
  4. Add description field if agent will be used as a tool

Agent not behaving as expected

  1. Review system prompt for clarity and specificity
  2. Adjust temperature (lower = more consistent responses)
  3. Make custom_rules more specific and actionable
  4. Verify appropriate tools are included
  5. Check model supports requested features

Error Message Reference​

  • "Agent with id 'example' already exists" → Duplicate agent ID found
  • "Invalid temperature value: 3.0" → Temperature outside 0.0-2.0 range
  • "Unknown tool: invalid_tool" → Tool name not recognized
  • "reasoning.max_tokens must be greater than 1024" → Reasoning tokens too low

Best Practices​

Writing Effective System Prompts​

  1. Be Specific: Define clear responsibilities and focus areas
  2. Include Examples: Show the type of output you expect
  3. Set Boundaries: Specify what the agent should and shouldn't do
  4. Use Structure: Organize instructions with headers and lists
  5. Test Iteratively: Refine prompts based on agent behavior

Configuration Tips​

  1. Start Conservative: Use lower temperature values for consistent behavior
  2. Limit Tools: Only include tools the agent actually needs
  3. Set Appropriate Limits: Configure max_turns based on expected conversation length
  4. Use Custom Rules: Add specific guidelines for your project or team
  5. Enable Reasoning: Use reasoning mode for complex problem-solving agents

Team Collaboration​

  1. Consistent Naming: Use descriptive, consistent agent IDs and titles
  2. Document Purpose: Write clear descriptions explaining each agent's role
  3. Share Configurations: Version control agent definition files with your project
  4. Establish Conventions: Create team standards for agent organization
  5. Regular Review: Update agents as project requirements evolve

Advanced Configuration​

Dynamic Prompt Templates​

Agent prompts support Handlebars template variables for context-aware behavior:

System Prompt Variables:

  • {{current_time}} - Current timestamp
  • {{env.cwd}} - Current working directory path
  • {{env.os}} - Operating system (macOS, Linux, Windows)
  • {{env.shell}} - Shell type (bash, zsh, PowerShell)

User Prompt Variables:

  • {{current_time}} - Current timestamp
  • {{event.name}} - Event identifier (e.g., "agent-id/user_task_init")
  • {{event.value}} - Event payload (user's message, feedback, or task data)

Environment-Specific Agents​

Create specialized agents for different deployment contexts:

---
id: prod-deployment
title: Production Deployment Expert
description: Handles production deployments with safety and monitoring focus
model: claude-sonnet-4
temperature: 0.05
custom_rules: |
  - Always consider production safety first
  - Include rollback procedures in all deployments
  - Add comprehensive monitoring and alerting
  - Use blue-green deployment strategies
  - Validate all environment configurations before deployment
tools:
  - read
  - write
  - shell
max_turns: 25
reasoning:
  enabled: true
  effort: high
---

You are a production deployment expert focused on safe, reliable deployments.

## Deployment Priorities

1. Zero-downtime deployments
2. Comprehensive monitoring and alerting
3. Quick rollback capabilities
4. Infrastructure as code
5. Security compliance

Always include monitoring, logging, and recovery procedures in your recommendations.

Model-Specific Optimization​

Different models work better with different configurations:

# For creative tasks
model: claude-sonnet-4
temperature: 0.7
top_p: 0.9

# For precise technical tasks
model: claude-sonnet-4
temperature: 0.1
top_p: 0.8

# For reasoning-heavy tasks
model: claude-sonnet-4
temperature: 0.2
reasoning: true

Provider-Specific Configuration​

You can specify different providers for different use cases:

  • OpenAI:
id: openai-agent
model: gpt-4
provider: openai
  • Requesty
id: requesty-agent
model: anthropic/claude-sonnet-4-5
provider: requesty

Important: Provider names must always be in snake_case format (lowercase with underscores separating words).

Getting Help​

If you encounter issues not covered in this guide:

  1. Check Forge startup logs for specific error messages and warnings
  2. Test with a minimal agent configuration first to isolate issues
  3. Verify your agent definition against the working examples provided
  4. Check the Forge documentation for updated tool lists and configuration options
  5. Consult the Forge community or support channels for additional assistance

Remember: Custom agents are powerful tools for streamlining your development workflow. Start with simple configurations and gradually add complexity as you become familiar with the options.