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: