custom-prompt

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

Quick Summary

Goal: Give a project a registry of named, reusable prompts — each with a name, a one-line description, and a prompt body that reads like a mini-skill — and route a free-text user request to the right one, always confirming the match with the user before executing it.

Summary: read-this-if-nothing-else digest —

• Two files, two jobs. The INDEX (custom-prompts-reference.md under the reference-docs root — default docs/project-reference, overridable via docsRoots.projectReference.path in docs/project-config.json) holds only name + description + triggers and is what you read to MATCH. The BODY (docs/project-prompts/<slug>.md) holds the actual protocol and is read only AFTER the user confirms. Never read all bodies to answer a match.
• Matching NEVER auto-executes. Score candidates from the index, then ask user question tool with the top matches plus an explicit escape option. A confident match is still a guess about intent — only the user can confirm it.
• Project payload, not framework. These prompts live under docs/, never under .claude/. .claude/ is the portable harness; custom prompts are this project's content. A prompt that stabilizes and generalizes gets PROMOTED to a real skill via $skill-creator — it is not born as one.
• Save = author the best version, then get it confirmed. The user's raw wording is raw material, never the artifact. Infer the goal, generalize it, rewrite it into a crisp name + one-line description + imperative steps + falsifiable success criteria — then show the draft, say what you changed and why, and let the user accept, correct, or keep their own wording verbatim. Also run the match pass first to catch a near-duplicate and offer update-instead-of-create.
• Never auto-commit. Report what changed and stop.

Workflow:

1. Resolve mode — parse the invocation into list | match | save | update | delete (Phase 0)
2. Load index — read the index doc; if missing or empty, branch to the empty-registry path
3. Execute mode — LIST (Phase 1) · MATCH + confirm (Phase 2) · RUN (Phase 3) · SAVE/UPDATE (Phase 4) · DELETE (Phase 5)
4. Sync index — any body write updates the index row in the same turn; the two never drift
5. Discovery check — a written body leads with its goal and when to use it and ends with its success criteria and guardrails; the index keeps its purpose header on top and stays routed from the docs index
6. Report — state the file(s) touched and the mode taken; never commit

Key Rules:

MUST ATTENTION resolve the mode FIRST — a leading list/save/update/delete token is a MODE, everything else is a MATCH request; ambiguous → ask, never guess MUST ATTENTION MATCH mode ends at an ask user question tool confirmation gate — NEVER execute a matched prompt without explicit user confirmation, no matter how high the score MUST ATTENTION read the index to match, read ONE body to execute — never bulk-read bodies MUST ATTENTION SAVE authors an improved version and ends at a proposal gate — NEVER write a rewrite the user has not seen, and always offer "save my wording verbatim" MUST ATTENTION every write updates BOTH the body file and its index row atomically in the same turn