This eliminates redundant user documentation and allows us to focus our
documentation investments.
I left tombstone files for most of the existing ".md" docs files to
avoid broken links. These now contain brief links to the developers docs
site.
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>
Expand the custom prompts documentation and link it from other guides. Show saved prompt metadata in the slash-command popup, with tests covering description fallbacks.
Adds custom `/prompts` to `~/.codex/prompts/<command>.md`.
<img width="239" height="107" alt="Screenshot 2025-08-25 at 6 22 42 PM"
src="https://github.com/user-attachments/assets/fe6ebbaa-1bf6-49d3-95f9-fdc53b752679"
/>
---
Details:
1. Adds `Op::ListCustomPrompts` to core.
2. Returns `ListCustomPromptsResponse` with list of `CustomPrompt`
(name, content).
3. TUI calls the operation on load, and populates the custom prompts
(excluding prompts that collide with builtins).
4. Selecting the custom prompt automatically sends the prompt to the
agent.
