core/core-agent-ide
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix documentation errors for Custom Prompts named arguments and add canonical examples (#5910)

Browse source 
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.

---------

Co-authored-by: Eric Traut <etraut@openai.com>
This commit is contained in:
Abkari Mohammed Sayeem 2025-11-15 22:55:46 +05:30 • committed by GitHub
parent 3f1c4b9add
commit 326c1e0a7e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 44 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
docs/prompts.md
View file

@ -42,16 +42,55 @@ Custom prompts turn your repeatable instructions into reusable slash commands, s
### Examples
**Draft PR helper**
### Example 1: Basic named arguments
`~/.codex/prompts/draftpr.md`
**File**: `~/.codex/prompts/ticket.md`
```markdown
---
description: Create feature branch, commit and open draft PR.
description: Generate a commit message for a ticket
argument-hint: TICKET_ID=<id> TICKET_TITLE=<title>
---
Create a branch named `tibo/<feature_name>`, commit the changes, and open a draft PR.
Please write a concise commit message for ticket $TICKET_ID: $TICKET_TITLE
```
Usage: type `/prompts:draftpr` to have codex perform the work.
**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.
```