Fix Custom Prompts documentation for named arguments + include canonical examples / reference.

Resolved 💬 4 comments Opened Oct 10, 2025 by 0xdevalias Closed Nov 13, 2025

💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What is the type of issue?

Documentation is incorrect

What is the issue?

The Custom Prompts documentation seems to be incomplete / outdated:

https://github.com/openai/codex/blob/main/docs/prompts.md

I know of at least 2 recent PR's that worked on this feature, one of them added/updated these docs, but the second one didn't seem to touch them at all:

It would be nice to have a canonical, complete reference (including examples maybe?) of what a custom prompt should look like.

Where did you find it?

https://github.com/openai/codex/blob/main/docs/prompts.md

View original on GitHub ↗

4 Comments

0xdevalias · 10 months ago

Here is what GitHub Codex (gpt-5) suggested, based on reviewing the codebase. I haven't deeply reviewed this to ensure it is correct, so take it as a starting point for exploring / validating deeper, rather than golden truth:

Prompt:

Can you look through the code and figure out what the correct current modern supported syntax is for creating custom prompts

Linked References:

Response:

Here’s the current, supported syntax for Custom Prompts in openai/codex based on the code paths that implement and test it. Where prompts live and how they’re named - Location: Markdown files in $CODEX_HOME/prompts (defaults to ~/.codex/prompts). Only .md files are loaded (case-insensitive extension). - Implementation: codex-rs/core/src/custom_prompts.rs (filters .md, reads content) link. - Command name: The filename (without .md) becomes the slash command name. Invoke with /prompts:<name>. - Prefix constant: PROMPTS_CMD_PREFIX = "prompts" link. - Optional frontmatter: You can include frontmatter fields description and argument_hint; the body after frontmatter is used as the prompt content. - Parsing and fields: discovery loads (description, argument_hint, body). Struct fields include description and argument_hint link. Two argument styles are supported, determined by the template content 1. Named arguments (recommended for modern usage) - In your .md content, reference variables as $NAME where NAME matches [A-Z][A-Z0-9_]* (uppercase, alnum, underscores). - Detection: prompt_argument_names scans for $[A-Z][A-Z0-9_]* link. - Invoke with key=value pairs after the command. Values can be quoted with "..." to include spaces (shlex parsing). - Parser: parse_prompt_inputs for key=value with shlex semantics [link](https://github.com/openai/codex/blob/ddcaf3dccd7a817b6307bff61a4604c4dff27621/codex-rs/tui/src/bottom_pane/prompt_args.rs#L94-L111, also comments at L112-L212). - Example: - Content: Review $USER changes on $BRANCH - Invoke: /prompts:review USER=Alice BRANCH=main - Quoted value: /prompts:review USER="Alice Smith" BRANCH=dev-main - Tested behavior: basic expansion, quoted values. - Missing required named args: the composer reports an error instead of submitting. - Test: custom_prompt_missing_required_args_reports_error link. - UI helper: When your template contains named placeholders, the UI can prefill a command like /prompts:name ARG="" ARG2="" and place the cursor inside the first quotes. - Implementation: prompt_command_with_arg_placeholders link. 2. Positional arguments - In your .md content, use: - $1..$9 for the first nine positional arguments - $ARGUMENTS to expand to all positional arguments joined by a single space - Detection of “positional mode”: presence of any $1..$9 or $ARGUMENTS triggers positional parsing. - prompt_has_numeric_placeholders and branching in expand_custom_prompt links: detection call sites shown in file, function signatures at. - Invoke by listing values after the command; values can be quoted with "..." (shlex). - Parser: parse_positional_args (shlex semantics) link. - Example: - Content: `` Header: $1 Args: $ARGUMENTS Ninth: $9 ` - Invoke: /prompts:my-prompt "Header value" foo bar - Tested behavior: selecting_custom_prompt_with_args_expands_placeholders [link](https://github.com/openai/codex/blob/ddcaf3dccd7a817b6307bff61a4604c4dff27621/codex-rs/tui/src/bottom_pane/chat_composer.rs#L2958-L2980). - If your template contains positional placeholders and you invoke without any args, the composer inserts the template into the editor instead of submitting it immediately (so you can fill in values). - Test: selecting_custom_prompt_with_no_args_inserts_template [link](https://github.com/openai/codex/blob/ddcaf3dccd7a817b6307bff61a4604c4dff27621/codex-rs/tui/src/bottom_pane/chat_composer.rs#L3027-L3050). **Escaping and literals** - $$ is preserved literally (remains $$). It does not collapse to a single $. - Test: escaped_placeholder_remains_literal [link](https://github.com/openai/codex/blob/ddcaf3dccd7a817b6307bff61a4604c4dff27621/codex-rs/tui/src/bottom_pane/prompt_args.rs#L393-L405). **Command form and parsing** - Slash command form: /prompts:<name> … where … are either positional args or key=value pairs depending on the template content. - Parsing: parse_slash_name and expand_custom_prompt [links](https://github.com/openai/codex/blob/ddcaf3dccd7a817b6307bff61a4604c4dff27621/codex-rs/tui/src/bottom_pane/prompt_args.rs#L60-L72), [expand entrypoint](https://github.com/openai/codex/blob/ddcaf3dccd7a817b6307bff61a4604c4dff27621/codex-rs/tui/src/bottom_pane/prompt_args.rs#L191-L212). **Docs vs code** - The current docs mention positional placeholders and $ARGUMENTS and quoting [docs/prompts.md](https://github.com/openai/codex/blob/ddcaf3dccd7a817b6307bff61a4604c4dff27621/docs/prompts.md#L3-L15), but the code additionally supports named placeholders ($NAME) with key=value invocation, quoted values, erroring on missing required named args, and frontmatter fields (description, argument_hint). These are covered and tested in the Rust TUI code linked above. **Canonical examples** **Named-arg prompt (recommended)** - File: ~/.codex/prompts/review.md Content: ` Review $USER changes on $BRANCH ` - Usage: ` /prompts:review USER="Alice Smith" BRANCH=dev-main ` **Positional prompt** - File: ~/.codex/prompts/header.md Content: ` Header: $1 Args: $ARGUMENTS ` - Usage: ` /prompts:header "My Header" foo bar ` If you want, I can open a PR to update docs/prompts.md` to include the named-argument syntax, examples, and the frontmatter fields.

0xdevalias · 10 months ago

Some improvements / iterations since I first opened this:

etraut-openai contributor · 9 months ago

This was recently added to the documentation.

0xdevalias · 9 months ago

This was recently added to the documentation.

@etraut-openai It would be helpful if you linked relevant PRs / etc when making statements like that.

I can see that these 3 PRs touched that docs file since I opened this issue:

And then there is this additional PR, which has yet to be merged:

https://github.com/openai/codex/pull/5910

I suspect it's this last PR that you were referring to as having been 'recently added to the documentation'; so traditionally I would have expected that this issue not been closed until that PR was merged.