Prompt Builder

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)

Gate fields (description + application) are mandatory — brain-qa fails without both.

brain-qa Scoring (4 points)

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.

---
description: "What this prompt does"
application: "When to use this prompt"
agent: Alex
---

Key rules:

• Use agent: to name the target agent (Alex, Researcher, Validator, etc.)
• Do NOT use mode: or tools: — those are for loop prompts
• Body should be 20+ lines with clear instructions

Loop Prompts (.github/prompts/loop/*.prompt.md)

Sidebar buttons in the extension Loop tab. Loaded by loopMenu.ts.

---
mode: agent
description: "What this prompt does"
application: "When to use this prompt"
tools: ["read_file", "create_file", "run_in_terminal"]
---

Key rules:

• Always include mode: agent
• Always include tools: array with relevant tool names
• Do NOT use agent: — loop prompts use mode-based routing
• Body should be 20+ lines with phase-based instructions

Field Writing Rules

description vs application

These are distinct fields — do not duplicate content between them.

Anti-pattern: Making application a rephrasing of description.

tools Array (Loop Prompts Only)

Include only tools the prompt actually needs:

Body Structure

Minimum Viable Body (20+ Lines)

# {Title}

{1-2 sentence intro describing the workflow}

## Phase 1: {Discovery/Setup}

{Steps for initial context gathering}

## Phase 2: {Execution}

{Core workflow steps}

## Phase 3: {Validation}

{How to verify the work}

## Output

{What the user should expect}

Using Variables

• $ARGUMENTS — User's input text (root prompts)
• ${{input}} — VS Code variable for selected text
• Reference skills with: "Load .github/skills/{name}/SKILL.md"

Checklist Before Commit

Run mentally before saving any .prompt.md:

• description: present and meaningful
• application: present and distinct from description
• Root prompt has agent: OR loop prompt has mode: agent + tools:
• Body exceeds 20 lines
• No duplicate of existing prompt (check .github/prompts/)
• If loop prompt: registered in .github/config/loop-menu.json

Common Failures and Fixes