Files
codex/docs/prompts.md
T
Abkari Mohammed Sayeem 2d3387169c Fix documentation errors for Custom Prompts named arguments and add canonical examples
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.
2025-10-29 17:53:23 +05:30

153 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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).