# Create Forge Agent

Creates and edits forge agent files with YAML frontmatter and instructions.

- Repository: https://github.com/tailcallhq/forgecode (7636 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add tailcallhq/forgecode --skill create-agent -g -a claude-code -y`
Codex: `npx skills add tailcallhq/forgecode --skill create-agent -g -a codex -y`
Cursor: `npx skills add tailcallhq/forgecode --skill create-agent -g -a cursor -y`
Gemini CLI: `npx skills add tailcallhq/forgecode --skill create-agent -g -a gemini-cli -y`

## Description

Create new agents for the code-forge application. Agents are stored as .md files in the <cwd>/.forge/agents directory with YAML frontmatter (id, title, description, reasoning, tools, user_prompt) and markdown body containing agent instructions. Use when users need to add new agents, modify existing agents, or understand the agent file structure.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

{{{{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

```markdown
---
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:

The rest: https://github.com/tailcallhq/forgecode/blob/HEAD/.forge/skills/create-agent/SKILL.md