create-agent

{{{{raw}}}}

Create Agents

Create and manage agents for the code-forge application. Agents are specialized AI assistants with specific capabilities, tools, and behaviors.

File Location

CRITICAL: All agent files must be created in the <cwd>/.forge/agents directory, where <cwd> is the current working directory of your code-forge project.

• Directory: <cwd>/.forge/agents
• File format: {agent-id}.md
• Example: If your project is at /home/user/my-project, agents go in /home/user/my-project/.forge/agents/

This is the only location where forge will discover and load custom agents.

Agent File Structure

Every agent file must have:

1. YAML Frontmatter (required):

   • id: Unique agent identifier
   • title: Agent display name
   • description: Detailed description of what the agent does
   • reasoning: Configuration with enabled: true/false
   • tools: List of tools the agent can use
   • user_prompt: Template for user context

2. Agent Body (required):

   • Agent identity and purpose
   • Core principles
   • Capabilities
   • Methodology
   • Best practices
   • Limitations and boundaries

Example Agent File

---
id: "forge"
title: "Perform technical development tasks"
description: "Hands-on implementation agent that executes software development tasks..."
reasoning:
  enabled: true
tools:
  - sem_search
  - sage
  - fs_search
  - read
  - write
  - undo
  - remove
  - patch
  - shell
  - fetch
  - skill
  - mcp_*
user_prompt: |-
  <{{event.name}}>{{event.value}}</{{event.name}}>
  <system_date>{{current_date}}</system_date>
---

You are Forge, an expert software engineering assistant...

## Core Principles:
...

Complete Sample Agent

This sample demonstrates a complete agent structure:

---
id: "sample-agent"
title: "Sample agent for demonstration"
description: "A sample agent that demonstrates the complete agent file structure with all required fields and common patterns."
reasoning:
  enabled: true
tools:
  - sem_search
  - read
  - write
  - shell
user_prompt: |-
  <{{event.name}}>{{event.value}}</{{event.name}}>
  <system_date>{{current_date}}</system_date>
---

You are Sample Agent, a demonstration agent that shows how to structure agent files.

## Core Principles:

1. **Principle 1**: Description of the first core principle
2. **Principle 2**: Description of the second core principle
3. **Principle 3**: Description of the third core principle

## Capabilities:

### Capability Category 1:

- Description of first capability
- Description of second capability

### Capability Category 2:

- Description of third capability
- Description of fourth capability

## Methodology:

### Step 1: First Step

Description of the first step in the methodology.

### Step 2: Second Step

Description of the second step in the methodology.

### Step 3: Third Step

Description of the third step in the methodology.

## Best Practices:

- Best practice 1
- Best practice 2
- Best practice 3

## Limitations and Boundaries:

This agent cannot perform certain tasks. When asked to do so, politely explain the limitations and suggest alternative approaches.