Support project-scoped custom prompts in `.codex/prompts` (repo root + cwd)

Resolved 💬 5 comments Opened Jan 25, 2026 by vjain419 Closed Jan 25, 2026

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

Summary

Custom slash prompts are currently only loaded from $CODEX_HOME/prompts. Please also load prompts from project-scoped .codex/prompts directories (repo root and any .codex directories between repo root and CWD), similar to how skills are loaded.

Why this matters

In monorepos and large repos, teams want to share prompts at the project/team level without requiring per-user setup or symlinks. Keeping prompts in the repo makes them versioned, reviewable, and portable across machines/CI.

Current behavior (code pointers)

codex-rs/core/src/custom_prompts.rs:
default_prompts_dir() returns only $CODEX_HOME/prompts.
discover_prompts_in(...) reads a single directory.
codex-rs/core/src/codex.rs:
list_custom_prompts only calls default_prompts_dir() and then discover_prompts_in(...).
There is no project/CWD prompt discovery path.

Proposed behavior

Discover prompts from project-scoped .codex/prompts directories, in order of precedence from CWD → repo root (same traversal as project config layers).
Keep $CODEX_HOME/prompts as a fallback (lowest precedence).
De-duplicate by prompt name with “highest precedence wins”.
Apply the same trust rules used for project layers (i.e., if a .codex dir is untrusted/disabled, consider skipping its prompts or marking them disabled).

Suggested precedence order:

CWD/.codex/prompts
Parent .codex/prompts up to repo root
$CODEX_HOME/prompts

Implementation notes (sketch)

Add a prompt-roots helper that mirrors skills::loader::skill_roots_from_layer_stack but returns .codex/prompts directories for project/user layers.
In codex::list_custom_prompts, enumerate all roots in precedence order and call discover_prompts_in_excluding(...) (or add a similar helper) to avoid duplicates by name.
Add tests to custom_prompts.rs or config/skills tests to cover:
Repo root + nested .codex/prompts both present
CWD precedence over repo root
Fallback to $CODEX_HOME/prompts
Trust/untrusted behavior if applicable

View original on GitHub ↗

5 Comments

etraut-openai contributor · 7 months ago

We are planning to deprecate custom prompts in the near future. The newer skills feature provides a superset of the functionality provided by custom prompts, so please switch to skills. Support for project-scoped skills is already supported.

vjain419 contributor · 7 months ago

what is reason for deprecate of custom prompts? is there any reasoning which is shared which explain how skills replace custom prompts.

e.g Claude code has consolidate how custom prompts and skill get called but in my point of view - both has its own benefit in my view.

etraut-openai contributor · 7 months ago

Skills provide a superset of the functionality of prompts. We don't want to maintain two overlapping ways to do the same thing. Doing so will create confusion for users, since it will be unclear which mechanism to use. We (and other providers of agentic harnesses) are rallying behind skills, and that's where we're making our investments going forward — in terms of features, user experience, administration, etc.

If there are aspects of custom prompts that you feel are not addressed by skills, let us know.

vjain419 contributor · 7 months ago

Hi @etraut-openai

Thanks for the explanation — appreciate the context.

I’d be very happy if skills and custom prompts eventually converge, as long as users don’t have to change their existing workflow and skills reach feature parity with custom prompts.

One concrete gap I see today is argument passing.

The current skills documentation
https://developers.openai.com/codex/skills/
doesn’t clearly describe support for $ARGUMENTS or positional arguments. This is something we rely on heavily with custom prompts, and it’s a blocker for fully switching. Clear support (and docs) for named + positional arguments in skills would go a long way.

Another concern is invocation UX.
Today, users are used to calling custom prompts via /. Skills require $, which means:

re-education of users
migration of existing custom prompts to skills
a high chance of partial or inconsistent adoption

That kind of change is always tricky and, frankly, frustrating for teams with established workflows.

If custom prompts are going to be deprecated, it would be ideal if skills could be invoked the same way as custom prompts (i.e., /), so users don’t have to change something that already works for them.

For what it’s worth, this concern closely mirrors what’s discussed in this Claude Code issue, which articulates the UX and migration pain very well:
https://github.com/anthropics/claude-code/issues/19355

Overall, I’m aligned with the direction — skills make sense — but argument passing, invocation parity, and a low-friction migration path feel critical to making the transition successful.

Happy to switch fully once those pieces are in place.

etraut-openai contributor · 7 months ago

Thanks for the feedback.

We're still very early in the agentic coding era, and we're all collectively discovering the best patterns, tools, and workflows. I understand that changing workflows can involve some reeducation, but given that these tools didn't even exist a year ago, it's clear that developers can readily adapt to changes like this. Switching from / to $ is pretty straightforward.

Migrating existing custom prompts to skills should be easy to automate. Just tell codex to do it for you.

As for your point about explicit $ARGUMENTS, skills are more flexible and don't generally require such rigidity with respect to argument positions. If you want that level of specificity, you can include it in the skill's prompt ("treat the first argument as a user ID and the second as a ticket number"). Give it a try and let us know if you run into problems.