Prompt Formats

Updated on Oct 1, 2026

Forge ships every built-in prompt in two formats, XML and Markdown. The format you select decides which prompt files Forge loads for a workflow. Forge picks the format from the model name, and you can override it for an agent, a target, or a single operation.

How Forge selects the format

For each command, Forge uses the first valid value in this order:

The operation entry, for example operations."issue.plan".prompt_format.
The target entry, for example targets.issue.prompt_format.
The agent-level prompt_format.
Automatic detection from the resolved model name:
- A name that contains claude or anthropic (in any letter case) selects XML.
- Any other name, or no model, selects Markdown.

Valid values are xml, markdown, and md (an alias for Markdown), in any letter case. Forge ignores any other value, such as json, without a validation warning and moves on to the next level.

Automatic detection looks only at the model-name text. It does not check provider capabilities. For example, claude-sonnet-5 and anthropic/claude-sonnet-5 select XML, and gpt-5.4 selects Markdown.

Where prompt files live

Format	Extension	Exported location
XML	`.xml`	`.forge/prompts/xml/<target>/`
Markdown	`.md`	`.forge/prompts/markdown/<target>/`

To export the built-in prompts for editing, run:

bash

frg config export --prompts --target issue

Role prompts are exported to a role folder (for example markdown/role/product_manager.role.md), and task prompts to the target folder (for example markdown/issue/issue_plan.task.md).

If you customize prompts in one format only, set prompt_format so Forge loads that format. Otherwise the model name can select the other format. Forge does not guarantee identical output from equivalent XML and Markdown prompts, so keep their instructions aligned if you maintain both.

Examples

XML prompt structure:

xml

<task>
  <title>Task Name</title>
  <description>Task description</description>
  <process>
    <steps>
      <step>First step</step>
    </steps>
  </process>
  <output_requirements>
    <output_path>.forge/work/job_{{issue_id}}/</output_path>
  </output_requirements>
</task>

Markdown prompt structure:

markdown

# Task Name

Task description

## Process

1. First step

## Output Requirements

```yaml
output_path: .forge/work/job_{{issue_id}}/
```

Configure the format

Put prompt_format in the agent's section of .forge/config/agents.toml.

Agent-wide:

toml

[agent.github_copilot]
prompt_format = "markdown"

By target. Use the table form because the entry sets more than a model:

toml

[agent.github_copilot.targets]
issue = { model = "gpt-5.4", prompt_format = "markdown" }
code = { model = "claude-sonnet-5", prompt_format = "xml" }

By operation:

toml

[agent.github_copilot.operations]
"issue.plan" = { model = "claude-opus-5", prompt_format = "xml" }

Example: combined precedence

toml

[agent.github_copilot]
prompt_format = "markdown"

[agent.github_copilot.targets]
issue = { prompt_format = "xml" }

[agent.github_copilot.operations]
"issue.draft" = { prompt_format = "markdown" }

frg issue draft uses Markdown (operation).
frg issue plan uses XML (target).
frg code review uses Markdown (agent-wide).

Troubleshooting

Error: Prompt override file not found

Cause: A [[prompt_overrides]] entry in .forge/config/commands.toml points to a file that does not exist for the selected format.

Solution:

Read the Declared: and Expected: lines in the error. The expected path includes the format folder and extension.
Create the file at the expected path, or export the prompts in that format with frg config export --prompts.
Or set prompt_format to the format your custom files use.

For the full error text, see Agent Troubleshooting.

An override has no effect

Cause: The value is invalid, so Forge ignores it, or a higher-precedence entry applies.

Solution:

Use only xml, markdown, or md.
Put the setting in the section for the agent you actually run, [agent.<agent.default>], or the agent passed with --agent.
Use the table form for target and operation entries, and write operation keys as target.operation.
Check for a higher-precedence operation or target entry.

Verify: Run the command with --print-prompt to display the compiled prompt without running the agent.