mirror of
https://github.com/openai/codex.git
synced 2026-11-15 21:50:46 +00:00
The Custom Prompts documentation (docs/prompts.md) was incomplete for named arguments: 1. Documentation for custom prompts was incomplete - named argument usage was mentioned briefly but lacked comprehensive canonical examples showing proper syntax and behavior. 2. Fixed by adding canonical, tested syntax and examples: - Example 1: Basic named arguments with TICKET_ID and TICKET_TITLE - Example 2: Mixed positional and named arguments with FILE and FOCUS - Example 3: Using positional arguments - Example 4: Updated draftpr example to use proper $FEATURE_NAME syntax - Added clear usage examples showing KEY=value syntax - Added expanded prompt examples showing the result - Documented error handling and validation requirements 3. Added Implementation Reference section that references the relevant feature implementation from the codebase (PRs #4470 and #4474 for initial implementation, #5332 and #5403 for clarifications). This addresses issue #5039 by providing complete, accurate documentation for named argument usage in custom prompts.
153 lines
5.2 KiB
Markdown
153 lines
5.2 KiB
Markdown
## Custom Prompts
|
||
|
||
Custom prompts turn your repeatable instructions into reusable slash commands, so you can trigger them without retyping or copy/pasting. Each prompt is a Markdown file that Codex expands into the conversation the moment you run it.
|
||
|
||
### Where prompts live
|
||
|
||
- Location: store prompts in `$CODEX_HOME/prompts/` (defaults to `~/.codex/prompts/`). Set `CODEX_HOME` if you want to use a different folder.
|
||
- File type: Codex only loads `.md` files. Non-Markdown files are ignored.
|
||
- Naming: The filename (without `.md`) becomes the prompt name. A file called `review.md` registers the prompt `review`.
|
||
- Refresh: Prompts are loaded when a session starts. Restart Codex (or start a new session) after adding or editing files.
|
||
- Conflicts: Files whose names collide with built-in commands (like `init`) stay hidden in the slash popup, but you can still invoke them with `/prompts:<name>`.
|
||
|
||
### File format
|
||
|
||
- Body: The file contents are sent verbatim when you run the prompt (after placeholder expansion).
|
||
- Frontmatter (optional): Add YAML-style metadata at the top of the file to improve the slash popup.
|
||
|
||
```markdown
|
||
---
|
||
description: Request a concise git diff review
|
||
argument-hint: FILE=<path> [FOCUS=<section>]
|
||
---
|
||
```
|
||
|
||
- `description` shows under the entry in the popup.
|
||
|
||
- `argument-hint` (or `argument_hint`) lets you document expected inputs, though the current UI ignores this metadata.
|
||
|
||
### Placeholders and arguments
|
||
|
||
- Numeric placeholders: `$1`–`$9` insert the first nine positional arguments you type after the command. `$ARGUMENTS` inserts all positional arguments joined by a single space. Use `$$` to emit a literal dollar sign (Codex leaves `$$` untouched).
|
||
- Named placeholders: Tokens such as `$FILE` or `$TICKET_ID` expand from `KEY=value` pairs you supply. Keys are case-sensitive—use the same uppercase name in the command (for example, `FILE=...`).
|
||
- Quoted arguments: Double-quote any value that contains spaces, e.g. `TICKET_TITLE="Fix logging"`.
|
||
- Invocation syntax: Run prompts via `/prompts:<name> ...`. When the slash popup is open, typing either `prompts:` or the bare prompt name will surface `/prompts:<name>` suggestions.
|
||
- Error handling: If a prompt contains named placeholders, Codex requires them all. You will see a validation message if any are missing or malformed.
|
||
|
||
### Running a prompt
|
||
|
||
1. Start a new Codex session (ensures the prompt list is fresh).
|
||
2. In the composer, type `/` to open the slash popup.
|
||
3. Type `prompts:` (or start typing the prompt name) and select it with ↑/↓.
|
||
4. Provide any required arguments, press Enter, and Codex sends the expanded content.
|
||
|
||
### Examples
|
||
|
||
#### Example 1: Basic named arguments
|
||
|
||
**File:** `~/.codex/prompts/ticket.md`
|
||
|
||
```markdown
|
||
---
|
||
description: Generate a commit message for a ticket
|
||
argument-hint: TICKET_ID=<id> TICKET_TITLE=<title>
|
||
---
|
||
Please write a concise commit message for ticket $TICKET_ID: $TICKET_TITLE
|
||
```
|
||
|
||
**Usage:**
|
||
|
||
```
|
||
/prompts:ticket TICKET_ID=JIRA-1234 TICKET_TITLE="Fix login bug"
|
||
```
|
||
|
||
**Expanded prompt sent to Codex:**
|
||
|
||
```
|
||
Please write a concise commit message for ticket JIRA-1234: Fix login bug
|
||
```
|
||
|
||
**Note:** Both `TICKET_ID` and `TICKET_TITLE` are required. If either is missing, Codex will show a validation error. Values with spaces must be double-quoted.
|
||
|
||
#### Example 2: Mixed positional and named arguments
|
||
|
||
**File:** `~/.codex/prompts/review.md`
|
||
|
||
```markdown
|
||
---
|
||
description: Review code in a specific file with focus area
|
||
argument-hint: FILE=<path> [FOCUS=<section>]
|
||
---
|
||
Review the code in $FILE. Pay special attention to $FOCUS.
|
||
```
|
||
|
||
**Usage:**
|
||
|
||
```
|
||
/prompts:review FILE=src/auth.js FOCUS="error handling"
|
||
```
|
||
|
||
**Expanded prompt:**
|
||
|
||
```
|
||
Review the code in src/auth.js. Pay special attention to error handling.
|
||
```
|
||
|
||
#### Example 3: Using positional arguments
|
||
|
||
**File:** `~/.codex/prompts/explain.md`
|
||
|
||
```markdown
|
||
---
|
||
description: Explain a concept
|
||
---
|
||
Explain $1 in simple terms.
|
||
```
|
||
|
||
**Usage:**
|
||
|
||
```
|
||
/prompts:explain "recursion"
|
||
```
|
||
|
||
**Expanded prompt:**
|
||
|
||
```
|
||
Explain recursion in simple terms.
|
||
```
|
||
|
||
#### Example 4: Draft PR helper
|
||
|
||
**File:** `~/.codex/prompts/draftpr.md`
|
||
|
||
```markdown
|
||
---
|
||
description: Create feature branch, commit and open draft PR
|
||
argument-hint: FEATURE_NAME=<name>
|
||
---
|
||
Create a branch named `tibo/$FEATURE_NAME`, commit the changes, and open a draft PR.
|
||
```
|
||
|
||
**Usage:**
|
||
|
||
```
|
||
/prompts:draftpr FEATURE_NAME=new-auth-flow
|
||
```
|
||
|
||
**Expanded prompt:**
|
||
|
||
```
|
||
Create a branch named `tibo/new-auth-flow`, commit the changes, and open a draft PR.
|
||
```
|
||
|
||
### Implementation reference
|
||
|
||
The named argument parsing and placeholder expansion for custom prompts is implemented in the prompt engine. Key features include:
|
||
|
||
- **Argument parsing:** Supports `KEY=value` syntax with optional double-quoted values for strings containing spaces
|
||
- **Placeholder expansion:** Named placeholders (e.g., `$FILE`, `$TICKET_ID`) are replaced with corresponding argument values
|
||
- **Validation:** All named placeholders found in the prompt template must have corresponding arguments provided at invocation time
|
||
- **Case sensitivity:** Placeholder names and argument keys are case-sensitive and must match exactly
|
||
|
||
For more details on the implementation, refer to the prompt parsing logic in the codebase (introduced in PRs #4470 and #4474, with clarifications in #5332 and #5403).
|