prompt-builderlisted

# Prompt Builder > Build `.prompt.md` files that pass brain-qa on first attempt — no regressions --- ## When to Use - Creating a new `.prompt.md` file - Fixing a failing prompt in brain-qa - Adding prompts to the loop menu config - Reviewing prompt frontmatter for completeness --- ## Prompt Anatomy Every `.prompt.md` has two parts: **YAML frontmatter** and **Markdown body**. ### Frontmatter (Required Fields) | Field | Required | Gate | Purpose | |-------|----------|------|---------| | `description` | **Yes** | **Yes** | What the prompt does (1 sentence) | | `application` | **Yes** | **Yes** | When/why to use it (distinct from description) | | `mode` | Conditional | No | Set to `agent` for loop prompts | | `agent` | Conditional | No | Named agent for root prompts | | `tools` | Conditional | No | Tool array for loop prompts | **Gate fields** (`description` + `application`) are mandatory — brain-qa fails without both. ### brain-qa Scoring (4 points) | Flag | Points | Rule | |------|--------|------| | `desc` | 1 | `description:` exists in frontmatter | | `app` | 1 | `application:` exists in frontmatter | | `agent` | 1 | `agent:` OR `mode: agent` exists | | `>20L` | 1 | Body exceeds 20 lines | **Pass** = both gates (`desc` + `app`) AND score >= 3. --- ## Two Archetypes ### Root Prompts (`.github/prompts/*.prompt.md`) Invoked directly by name. Typically route to a named agent. ```yaml --- description: "What this prompt does" application: "When to use this prompt"