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: