Create Custom Prompt

Create Custom Prompt

Workflow

Create a new Codex custom prompt file in ~/.codex/prompts/ following the Codex custom prompts format, then open it in VS Code.

1) Gather requirements (ask first)

Ask the user what they want to achieve with the prompt, then ask only the minimum clarifying questions needed to generate a usable prompt:

• Goal: What should the slash command accomplish, and what “done” looks like?
• Scope: Is the prompt repo-specific (e.g. this microfrontend) or general-purpose?
• Inputs / arguments:
  • Do they want named args (FILES=..., TICKET_ID=...) or positional args ($1, $2, …)?
  • Which args are required vs optional?
  • Any quoting expectations (paths with spaces, multi-line text, etc.)?
• Output style: concise vs detailed; include steps/checklists; include code blocks?
• Safety constraints: anything the prompt must never do (e.g., “don’t run destructive commands”)?

If the user is unsure about arguments, propose a small set of named placeholders (uppercase) and confirm.

Make it more concrete (recommended): If you have ideas that materially improve the prompt’s clarity or reliability, surface them as suggestions and confirm with the user. Keep this tight (1–5 bullets) and focus on high-leverage concreteness, for example:

• Add/adjust arguments to avoid ambiguous input (e.g., FEATURE_NAME=..., PLAN_FILE=..., OUT=..., SCOPE_DIR=...).
• Nail down output artifacts and filenames (where to write results, overwrite vs append).
• Specify required output structure (sections/headings) and verification criteria.
• Add explicit “blocking questions only” vs “ask first” behavior when appropriate.
• Add tool/command expectations (e.g., use git diff, run pnpm lint) and guardrails (“no new tooling unless requested”).

2) Choose a command/file name

Pick a short, memorable, lowercase name (letters/digits, optionally hyphens). It becomes:

• File: ~/.codex/prompts/<name>.md
• Slash command: /prompts:<name>

If the user did not specify a name, propose one derived from the goal (e.g. draftpr, summarize-log, review-diff) and confirm.

3) Create the prompt file

Follow the Codex custom prompts guidance (see references/custom-prompts.md):

• Ensure the prompts directory exists: ~/.codex/prompts/ (create it if missing).
• Create the prompt file directly under that directory (no subfolders).
• Add YAML front matter:
  • description: short, user-facing summary
  • argument-hint (optional): a compact “usage” string that matches the placeholders
• Write the prompt body in Markdown and include placeholders as needed (e.g. $FILES, $TICKET_ID, $1, $ARGUMENTS).

Prefer using the helper script so directory creation, naming, and opening are consistent:

cat <<'EOF' | scripts/create_prompt.sh \
  --name "<name>" \
  --description "<one-line description>" \
  --argument-hint "[OPTIONAL_ARG=<value>] [OTHER_ARG=\"<value>\"]" \
  --open
<prompt body markdown here>
EOF

This path is intentionally relative to the skill folder so it works whether the skill is installed globally (under a Codex home) or locally (inside a repository).

If the user wants to update an existing prompt, edit the existing ~/.codex/prompts/<name>.md instead of creating a new one.

4) Open in VS Code

Always open the created/updated prompt file via the VS Code CLI if available:

• Use code -g "<path>:1"
• If code is unavailable, print the full path and tell the user to open it manually.

5) Remind about reload

Remind the user: after adding/editing custom prompt files, restart Codex (new CLI session; reload IDE extension) so it loads the updated prompt metadata and placeholders.