Skip to main content
You can create custom prompt files for specialized workflows that aren’t covered by the built-in presets.

Specifying a Custom Prompt

Pass the file path to the --prompt option:
The path can be absolute or relative to the current directory.

Required Structure

Custom prompts should follow this structure to work effectively with the loop system:

File References with @ Syntax

The @ prefix makes files available to the agent. Claude Code will read these files when processing the prompt:
Without the @ prefix, file paths are just text. With @, the agent can actually read and reference the file contents.

Completion Markers

The loop watches for two special markers in agent output: When either marker is detected, the loop exits early. The reason text is captured in the final result. Example usage in a custom prompt:

Best Practices

  1. Be specific: Clearly define what “done” means for your workflow
  2. One task per iteration: Instruct agents to complete exactly one unit of work
  3. Use the progress file: It is attached to every prompt; tell agents to append a note to it so the next iteration sees what was done
  4. Include quality checks: Add steps for running tests or type checks before completing
  5. Define completion criteria: Tell agents exactly when to output <loop-complete>
  6. Handle edge cases: Define when to output <loop-blocked> to avoid infinite loops