project-skill-protocol

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 protocol overlays — extra project rules layered onto framework skills — with create / read / update / delete over that registry, so a skill picks up this project's conventions on every run without the portable framework being edited.

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

• Two files, two jobs. The INDEX defaults to <docsRoots.projectReference.path>/skill-protocols-reference.md (default docs/project-reference/; docsRoots.projectReference.path in docs/project-config.json overrides it); a matching referenceDocs[] filename may relocate it within that root. The BODY is <Protocols directory>/<slug>.md, where the index header declares a project-relative directory and docs/project-protocols/ is the default. The registry is independent from task-specific referenceDocs selection; omission or [] never disables overlay lookup. Never bulk-read bodies.
• ADDITIVE ONLY — the rule that governs every other rule. An overlay ADDS rules on top of a skill's protocol; it never replaces, overrides, disables, or reinterprets one. Invariant: removing every overlay returns each skill to exactly its documented behavior.
• Resolution is specificity-based, not order-based. exact > glob > *, winner tier takes all — and that ordering ranks overlays against EACH OTHER, never against the skill.
• Project payload, not framework. Overlays live under docs/, never .claude/. A rule that stabilizes and generalizes gets PROMOTED to a real skill via $skill-creator.
• ADD authors the best version, then confirms it. The user's raw wording is raw material, NEVER the artifact. Infer intent, generalize past the incident, draft the body, then run the rules through $prompt-enhance and the prompt-engineering rubric (imperative · observable · decidable · one rule per line · carries its WHY) — an overlay is an AI instruction that fires unattended, so a vague rule is a nondeterministic one. Show what changed and why, and always offer "save my wording verbatim".
• $learn routes here. When a user asks to learn/remember a rule for one skill, or for the kind of task a skill owns, $learn asks the user which carrier to use (overlay recommended) and then calls this skill's add/update; read .claude/skills/learn/SKILL.md § Skill-Specific Project-Protocol Route when invoked from $learn. Every gate below still applies in full. A broad, short, project-wide rule that is not about one skill's own steps is not an overlay: $learn routes it to the root CLAUDE.md project-rules section or a reference doc instead.
• Two writes, one turn. Body + index row, nothing else: the skill-overlay-remind hook reads the registry at runtime and names the matched bodies when a skill starts, so no CLAUDE.md block and no mirror sync is involved. Report every path touched. Never commit.