Prompt Authoring Guide

Learn how to write effective prompt files for use with prompts-gpt — including Markdown structure, YAML frontmatter for sweeps, variables, and best practices.

Basic Prompt Structure

A prompt file is a Markdown document with optional YAML frontmatter:

---
title: Code Review
slug: code-review
category: Code Review
difficulty: Intermediate
outputType: Text
supportedTools: [Codex, Claude, Cursor]
tags: [review, quality]
---

# Code Review

Review the codebase for code quality issues, focusing on:

1. **Code organization** — module structure, file layout
2. **Error handling** — proper try/catch, error boundaries
3. **Type safety** — TypeScript usage, type coverage
4. **Performance** — unnecessary re-renders, memory leaks
5. **Security** — input validation, XSS prevention

## Focus Areas

- Functions longer than 50 lines
- Deeply nested conditionals (>3 levels)
- Unused imports and dead code
- Missing error boundaries in React components

## Output Format

Provide findings as a numbered list with severity (HIGH/MEDIUM/LOW),
file path, and specific recommendation.

YAML Frontmatter

Required Fields

Optional Fields

Sweep-Specific Frontmatter

---
title: Security Audit
slug: security-audit
sweep:
  defaultIterations: 5
  maxIterations: 10
  summaryLines: 40
  eval:
    criteria: [correctness, completeness, thoroughness]
    passThreshold: 0.8
---

Variables

Prompts can include variables that are resolved at runtime:

Review the `{{targetDir}}` directory for {{severity}} issues.
Focus on {{language}} files only.

Variables are declared in frontmatter:

---
variables:
  - targetDir
  - severity
  - language
---

Writing Effective Prompts

Be Specific

<!-- Bad -->
Review this code.

<!-- Good -->
Review all TypeScript files in `src/lib/billing/` for:
1. Incorrect price calculations
2. Missing currency conversion
3. Race conditions in concurrent checkout flows

Structure with Sections

# Task

What the agent should do.

## Context

Background information the agent needs.

## Constraints

Rules the agent must follow.

## Output Format

How results should be formatted.

## Success Criteria

How to determine if the task is complete.

Include Examples

## Example Output

FINDING-001 [HIGH] src/lib/auth.ts:42 Missing rate limiting on login endpoint. Recommendation: Add express-rate-limit middleware.

Scope Appropriately

• Too broad: "Review the entire codebase" (agent may miss details)
• Too narrow: "Check line 42 of auth.ts" (too specific for a prompt file)
• Just right: "Review authentication middleware in src/middleware/ for OWASP Top 10 vulnerabilities"

Sweep Prompts

Sweep prompts should be written for iterative refinement:

---
title: Progressive Security Hardening
sweep:
  defaultIterations: 5
---

# Progressive Security Hardening

Review and fix security vulnerabilities in the codebase.

## Iteration Guidance

- **Iteration 1**: Scan for critical vulnerabilities (SQL injection, XSS, CSRF)
- **Iteration 2**: Review authentication and authorization flows
- **Iteration 3**: Check data validation and sanitization
- **Iteration 4**: Audit dependency security and supply chain
- **Iteration 5**: Final review and verification of all fixes

## Per-Iteration Output

After each pass, summarize:
1. Issues found (with severity)
2. Fixes applied
3. Remaining concerns for next iteration

Generating Prompts

From the CLI

prompts-gpt generate --goal "Review Next.js app for performance" \
  --context "App uses App Router, Prisma, Redis" \
  --tool Codex

From the API

const prompt = await client.generatePrompt({
  goal: "Review for accessibility compliance",
  context: "React + Tailwind CSS application",
  constraints: "Must meet WCAG 2.1 AA",
  tool: "Codex",
});

File Organization

Recommended directory structure:

.prompts-gpt/
├── manifest.json
├── prompts/
│   ├── code-review.md
│   ├── security-review.md
│   └── performance-check.md
├── sweeps/
│   ├── security-audit.md
│   ├── accessibility-audit.md
│   └── performance-audit.md
└── orchestrations/
    ├── parallel-review.json
    └── pipeline-steps/
        ├── research.md
        ├── implement.md
        └── review.md

Validating Prompts

prompts-gpt validate

Checks:

• YAML frontmatter syntax
• Required fields present
• Slug uniqueness
• Variable declarations match usage

See Also

• Generate CLI
• Generate Sweep CLI
• Sweep CLI
• Sweep vs Prompts