Prompt Template System

# Prompt Template System

Last reviewed: 2026-05-22.

## Purpose

This reference defines how Codex Agent Skills stores reusable prompt templates.
The goal is to make prompts like a high-quality launch brief: they should tell
Codex what outcome matters, which plugins/skills to use, what inputs to gather,
where the safety boundaries are, how to verify the result, and what to return.

## Template Shape

Every template in `prompt-templates/` has:

- frontmatter for catalog/discovery
- a short "Use When" section
- a copy/paste prompt
- placeholders wrapped in `{BRACES}`
- safety notes
- expected outputs
- color-coded plugin/capability badges in `PROMPT_GALLERY.md` or the catalog
  when the template is meant for public discovery

The prompt body should be directly usable. It should not depend on hidden
personal context or private accounts unless the template clearly marks that as
a user-provided input.

## Prompt Anatomy

Use this structure for substantial templates:

1. **Role**: tell Codex what job it is doing.
2. **Objective**: state the concrete outcome.
3. **Available tools**: name plugins, skills, files, or connectors that should
   be used when available.
4. **Inputs**: list placeholders such as `{REPO_PATH}`, `{APP_IDEA}`, or
   `{TARGET_AUDIENCE}`.
5. **Workflow**: specify search, planning, implementation, safety checks, and
   validation.
6. **Guardrails**: secrets, account-control, destructive actions, untrusted
   source, payments, browser/session, and production constraints.
7. **Output format**: require a plan, files changed, validation results, links,
   or a ready-to-copy artifact.

## Quality Bar

A template is worth adding when it:

- reduces prompt-writing time for a repeated workflow
- routes Codex to the right skills or plugins
- prevents unsafe tool use
- preserves a useful project pattern
- gives a clear final artifact shape
- makes plugin lanes obvious through concise badges or labels
- can be validated or reviewed

Avoid templates that are just generic "be helpful" instructions. Each template
should have a job.

## Screenshot-Inspired Pattern

The screenshot prompt works because it gives Codex a map of capability lanes:

- app building: database, hosting, GitHub, AI gateway
- documents: spreadsheets, documents, presentations
- human interface: browser/computer control
- administrative work: email, calendar, Slack, Linear, Drive
- video/media: transcript, editing, motion graphics, diagrams, research,
  assets

This repository turns that idea into reusable templates with placeholders and
safety gates, rather than one personal mega-prompt.

For GitHub display, use Shields-style badges for color. Keep the badges
secondary to the workflow: the badge should signal a lane, not replace the
instructions, validation, or safety gate.

## Safety Rules

- Do not include real API keys, OAuth tokens, cookies, session exports, private
  document IDs, or account names in templates.
- Use connector/plugin names as capability hints, not requirements.
- Add `$mcp-safety-review` for MCP/tool/install boundaries.
- Add `$auto-skill-safety-mcp-secret-guard` for MCP config snippets.
- Add explicit confirmation gates before destructive writes, account actions,
  payments, production changes, messaging, or broad cloud operations.

## Validation

Run: