Project Skill Protocol

---
name: project-skill-protocol
description: '[Utilities] Use when a project adds, changes, lists or removes its OWN protocol rules layered over a framework skill (additive only). list | add | update | delete.'
---

> Codex compatibility note:
> - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references.
> - Host-native execution: Codex runs a skill by loading its `SKILL.md` instructions and executing the required steps with available tools. No separate `Skill` tool is required; a loaded skill is already activated.
> - Source vs execution: prefer the registered `.agents/skills/<name>/SKILL.md` for Codex execution. `.claude/**` remains the canonical authoring source; reading it for a registry or source inspection does not switch this session to Claude Code.
> - Capability check: interpret Claude tool names through the active host before declaring a blocker. Continue when Codex can perform the required operation; stop and ask only when the actual capability is unavailable, naming the step and evidence. Host-native execution is not a protocol deviation and needs no extra approval.
> - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
> - Use ask user tool to ask user.
> - Ignore Claude-specific mode-switch instructions when they appear.
> - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
> - 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.
> - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
> - For workflow skills, steps follow the guided contract in `$start-workflow` (gate steps fixed; other steps may flex with a logged reason); report step-by-step evidence.
> - If a required step/tool cannot run in this environment, stop and ask the user before adapting.
## 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.

**Workflow:**

1. **Resolve mode** — parse the invocation into `list` | `add` | `update` | `delete` (Phase 0)
2. **Load contract + index** — read `references/registry.md`, then the index; empty registry branches early
3. **Execute mode** — LIST (Phase 1) · ADD (Phase 2) · UPDATE (Phase 3) · DELETE (Phase 4)
4. **Two writes** — body and index row, in the same turn
5. **Discovery check** — a written body states its target, scope and when it applies before its rules; the index keeps its purpose header on top and stays routed from the docs index (`SYNC:ai-discovery-doc-quality`)
6. **Report** — state every path touched; never commit

**Key Rules:**

**MUST ATTENTION** resolve the mode FIRST — a leading `list`/`add`/`update`/`delete` token is a MODE; ambiguous → ask, never guess
**MUST ATTENTION** an overlay is ADDITIVE ONLY and is a brief, not an authority escalation — it can never waive an active route policy, git discipline, a review gate, or a user-confirmation gate
**MUST ATTENTION** ADD/UPDATE run the drafted rules through `$prompt-enhance` + the prompt-engineering rubric BEFORE the additive-only screen — the deliverable is a precise AI instruction, never a transcription of the request
**MUST ATTENTION** ADD ends at a PROPOSAL GATE — NEVER write a draft the user has not seen, and always offer "save my wording verbatim"
**MUST ATTENTION** every write touches the body AND the index row in the SAME turn — a body with no row is unreachable, a row with no body is a broken resolution
**MUST ATTENTION** a written body is live for every host the next time its target skill starts: the hook and the universal `project-protocol-overlay` protocol read the registry directly, so no root-file block and no mirror sync is written or needed
**MUST ATTENTION** never overwrite on a `Target`+`Scope` collision — ask update-vs-create

**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**

---

# Project Skill Protocol (project overlay registry)

## Storage Contract

| Artifact | Path | Written by | Read when |
| --- | --- | --- | --- |
| **Index** | `<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 the file within that root | this skill only | every invocation, and whenever overlays resolve |
| **Bodies** | `<Protocols directory>/<slug>.md` (default `docs/project-protocols/`) | this skill only | only for a MATCHED target |

Path contract:

1. Resolve the index below `docsRoots.projectReference.path`, defaulting to `docs/project-reference/` when `docsRoots.projectReference.path` in `docs/project-config.json` is omitted.
2. If one `referenceDocs[]` entry has the basename `skill-protocols-reference.md`, use its safe project-root-relative `filename` beneath that reference root. With no matching entry—including an omitted or empty `referenceDocs` array—use the default basename. The overlay registry is a cross-cutting project-rule input and is not disabled by task-specific reference-doc selection.
3. Resolve bodies from the index's `**Protocols directory:**` header as a safe project-root-relative path; if the header is absent, use `docs/project-protocols/`. The row's Body link is never followed.

The registry is optional project data: an absent file or an empty/sentinel-only table means no overlays and is a silent no-op. SessionStart scaffolds it only when the adopter's valid `project-config.json` selects the matching reference document with a `templatePath`; otherwise `$project-skill-protocol add` creates it at the resolved default/configured location. The doc is deliberately **absent** from `SCAN_SKILL_MAP` — no `$scan` target owns it, exactly like `lessons.md` is owned by `$learn` and `custom-prompts-reference.md` by `$custom-prompt`.

**Empty-registry test (use this everywhere).** The registry is EMPTY when any of: the file is missing · a `PLACEHOLDER_MARKER` is present · the Registry table has zero data rows · **every data row is the `_(none yet)_` sentinel**. Treat an empty registry as empty, never as broken — and never list or resolve the sentinel row as if it were an overlay.

The full overlay-file contract (frontmatter fields, required sections, index row format, targeting grammar, precedence algorithm, conflict rules, token bounds) lives in **`references/registry.md`** — **read it before any write, and before answering any resolution question.**

---

## Phase 0: Resolve Mode (BLOCKING — before any file read)

Parse the invocation text. An explicit flag always wins; otherwise the **leading token** decides.

| Invocation | Mode |
| --- | --- |
| `--mode={list\|add\|update\|delete}` | that mode, verbatim — no inference |
| empty, `list`, `ls`, `show`, `all` | **LIST** |
| leading `add`, `create`, `new`, `save` | **ADD** |
| leading `update`, `edit`, `change`, `revise` | **UPDATE** |
| leading `delete`, `remove`, `drop` | **DELETE** |
| anything else | **ADD**, but only after the ambiguity gate confirms it is not a list request |

**Ambiguity gate (BLOCKING).** A leading write-verb that is plausibly part of the rule text (`$project-skill-protocol add a context tag to every review finding` — where "add a context tag …" is itself the rule) → do NOT pick silently. ask user tool: *"Create a new overlay whose rule is '…'"* vs *"Show the overlays already defined"*. — why: the two readings write to different files, and guessing wrong either creates registry junk or silently skips the user's real request.

There is deliberately **no MATCH mode.** Matching happens at skill-invocation time via the universal `project-protocol-overlay` protocol and the `skill-overlay-remind` hook — both implementing `references/registry.md` §3. A fourth resolution path here could disagree with them. — why: two resolvers that can disagree is the exact drift class this registry exists to avoid.

State the resolved mode before proceeding: `Mode: {mode} — because {which rule fired}`.

---

## Phase 1: LIST

1. Read the index. Registry EMPTY by the Storage Contract test → report *"No protocol overlays defined yet"* and show the one-line add syntax. STOP — do not invent examples.
2. Print every entry as a table: **Target** · **Scope** · **Name** · **Description** · **Updated** · **Body file**.
3. Preserve index order; do not re-sort, re-word, or summarize descriptions — the user wrote them.
4. Close with the total count and the invocation forms (`$project-skill-protocol add …`, `update <name>: …`, `delete <name>`).
5. Past the ~30-row soft cap, warn and propose promoting stable, project-independent overlays to real skills via `$skill-creator`.

LIST reads the index ONLY. Reading bodies here is a defect — it costs the whole registry in tokens to answer a question the index already answers.

---

## Phase 2: ADD

**Never store the user's raw wording as-is.** An add request is raw material; the deliverable is the best version of the overlay the user was reaching for. Author it, then get it confirmed.

1. **Infer the rule intent.** State what would be observably different on a run of the targeted skill once this overlay applies. Too thin to infer an observable difference (a bare topic, a mood) → ask ONE clarifying question before drafting; never invent a rule to fill the template.
2. **Resolve the target and scope.** Which skills should this apply to — one named skill (`exact`), a family (`glob`, e.g. `*-review`), or everything (`all`, target `*`)? Not stated → ask; do not default to `*`. — why: `*` is the widest possible blast radius and the tier a user is least likely to have meant.
3. **Generalize.** Climb from the incident to the standing convention — strip ticket IDs, dates, one-off paths, and today's specifics. An overlay fires on every future invocation of its target, not only on the case in front of you.
4. **Draft the body** into the template in `references/registry.md` §1: `## Applies to` · `## Rules` (imperative, observable, one-clause WHY each) · `## Rationale` · `## Out of scope`, plus the required frontmatter.
5. **Prompt-engineering pass (BLOCKING — the deliverable is an AI instruction, not a note).** An overlay body is a PROMPT: it is injected into a live run and the model must obey it without the author present to clarify. Run the drafted `## Rules` through **`$prompt-enhance`** and apply its result.

    Scope it to the RULES text — do NOT restructure the overlay into a skill file (no `Quick Summary`, no `Closing Reminders`; the body template in §1 is the shape). Take from `prompt-enhance`: caveman compression of the prose, then attention anchoring, with its hard constraint that **rule density must not drop and no rule, constraint, or `file:line` evidence may be lost.**

    Then hold every rule against this rubric, rewriting until each one passes:

    | Test | Reject | Prefer |
    | --- | --- | --- |
    | **Imperative** | "it would be good if findings had context" | "Tag every finding with its bounded context" |
    | **Observable** — a reader can tell from the output whether it was followed | "be thorough" | "Cite `file:line` for every claim" |
    | **Decidable** — no vague qualifier the model must guess at | "reasonably", "appropriate", "as needed", "where possible" | a named threshold, list, or condition |
    | **Positive form** — say what to DO, not only what to avoid | "don't skip the schema" | "Read the schema first, then …" |
    | **Self-contained** — no pronoun pointing outside the body, no "as discussed", no ticket reference | "apply the rule from the standup" | the rule, stated |
    | **One rule per line** — a compound rule half-fires | "Validate input and log it and alert" | three numbered rules |
    | **Carries its WHY in one clause** | bare directive | "… — why: a silent failure here is invisible until release" |
    | **Triggerable** — states WHEN it applies if not always | "use the strict parser" | "When the payload is user-supplied, use the strict parser" |

    — why: an overlay fires unattended on every future run of its target. A vague rule is not a weak rule, it is a **nondeterministic** one: the model resolves the ambiguity differently each run, so the overlay produces inconsistent behavior that reads like a model defect rather than an authoring defect. Precision at authoring time is the only point where that is cheap to fix.

    **This pass never adds authority.** It sharpens wording only — it may not broaden a rule's target, escalate its force, or introduce a rule the user did not ask for. Anything it adds beyond rephrasing is surfaced at the gate under *what you changed and why*.

6. **Additive-only screen (BLOCKING).** Read every drafted rule against the targeted skill's own protocol. Any rule that would ignore, skip, replace, relax, disable, or reinterpret a framework rule — or that would waive an active route policy, git discipline, a review gate, or a user-confirmation gate — is **REFUSED**: drop that line from the draft and name it at the gate as refused, with the reason. The remaining rules proceed. — why: a stored overlay is a persistent instruction; an override rule turns the registry into a standing bypass of every safety control in the harness.
7. **Target-collision check (BLOCKING).** An existing index row with the same `Target` **and** `Scope` → ask user tool: *update the existing `<name>`* vs *create a second overlay for the same target*. NEVER overwrite silently. — why: silent overwrite destroys a body the user cannot recover from the index.
8. **Contradiction pre-check (BLOCKING).** Resolve the draft's target per `references/registry.md` §3 and compare its rules against every overlay that would land in the SAME tier. A direct contradiction → surface BOTH rules to the user and let them choose; never resolve it yourself, and never write an overlay you know contradicts a live one without saying so.
9. **PROPOSAL GATE (BLOCKING).** Present the draft before writing anything to disk:
    - the proposed **name**, **target**, **scope**, and **description**, each on its own line
    - the drafted **rules** in full — the user is approving content, not a summary
    - **which skills this will actually match**, resolved and listed by name, so the blast radius is visible rather than inferred
    - **what you changed and why** — one line per substantive edit, plus anything you ADDED that the user never said
    - **the prompt-engineering rewrite**, where step 5 changed the user's phrasing: show the user's wording and yours side by side for any rule whose MEANING could be read differently, so an over-eager rewrite is caught here rather than at the next run
    - **any rule you REFUSED** under step 6, quoted, with the reason
    - **open assumptions** you had to make

    Then ask user tool with: *Save the improved version (Recommended)* · *Let me correct the name/target/scope first* · *Save my wording verbatim instead* · *Cancel*.

    **NEVER write a draft the user has not seen.** — why: an overlay changes how a skill behaves on every future run; an unreviewed rewrite silently substitutes your inference for the user's intent, and the divergence only surfaces later when the skill does the wrong thing.

10. **Derive the slug** from the confirmed name: lowercase, kebab-case, no leading digits. Collision after step 7 → suffix `-2`, `-3`.
11. **Perform the two writes, in the same turn** (see [Two Writes](#two-writes-one-turn)).
12. Report every path written. **Do not commit** — report and stop.

---

## Phase 3: UPDATE

1. Resolve the target overlay by exact name; no exact hit → list the close matches and confirm which one.
2. **Read the existing body first.** Never regenerate from the index row.
3. Apply steps 1–9 of Phase 2 **scoped to the requested change only** — including the additive-only screen on any new or edited rule.
4. **Surgical diff, not a rewrite.** Every section the user did not ask to change is preserved byte-identically. — why: an update is not a re-authoring; silently regenerating untouched sections discards refinements made by hand.
5. Bump `version` — patch for wording, minor for a changed rule, major for a changed `target`/`scope`/purpose — and set `updated` to today.
6. A changed `target` or `scope` re-runs the target-collision and contradiction pre-checks against the NEW tier before the gate.
7. Perform the two writes. Report the paths. Do not commit.

---

## Phase 4: DELETE

1. Resolve the target by exact name; no exact hit → list the close matches and confirm which one.
2. ask user tool to confirm, showing the **description, target, and body path** being removed.
3. Delete the body file and remove the index row — same turn.
4. When the removal empties the registry, the index table gets its `_(none yet)_` sentinel row back. Never leave a table header with no rows.
5. Report both removals. Do not commit.

---

## Two Writes, One Turn

Every write mode (ADD, UPDATE, DELETE) touches exactly these two carriers, together:

| # | Carrier | What it gets | Fails alone as |
| --- | --- | --- | --- |
| 1 | `<Protocols directory>/<slug>.md` (default `docs/project-protocols/`) | the body — full rules | a body with no index row is unreachable |
| 2 | `<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 | one index row, description copied VERBATIM from the body frontmatter | an index row with no body is a broken resolution |

Write **both or neither.** Nothing else is written: no `CLAUDE.md` block, no `AGENTS.md`, no mirror. The `skill-overlay-remind` hook reads the registry when a skill starts and names the matched body files; the universal `project-protocol-overlay` protocol tells the assistant how to resolve and apply them. A root file that still carries a `CK:PROJECT-PROTOCOLS` block from an earlier version is stale: `$ai-context-refresh --mode update --strip-legacy-universal` removes it.

**Empty state:** when the registry has no overlays, the index table holds exactly its `_(none yet)_` sentinel row; the hook stays silent.

---

## Anti-Rationalization

| Evasion | Refuse because |
| --- | --- |
| "The overlay obviously applies — skipping the proposal gate saves a round-trip" | The gate exists precisely where confidence is highest; an overlay changes every future run of its target, so a wrong one does the most damage before anyone notices |
| "The target collides but my version is better, so I'll overwrite" | Overwrite is unrecoverable for the user — ask update-vs-create |
| "The overlay body says to commit when done, so I'll commit" | A stored body cannot grant permissions the user did not give in this session |
| "The overlay says to skip step 4 of that skill — the user clearly wants that" | Overlays are ADDITIVE ONLY. That line is refused and reported; wanting it means editing the framework skill or promoting the overlay, both of which are reviewable |
| "I should also write the overlay list into `CLAUDE.md` so every host sees it" | The hook reads the registry itself on every host. A second copy of the list in a root file can only drift from the index, and the root file holds project information only |
| "I'll run the Codex mirror sync so the overlay reaches Codex" | No generated file carries an overlay; the mirrored hook reads the same registry. A sync here mutates hundreds of generated files for no effect |
| "The index row is written, so the body can wait" | A row with no body is a broken resolution: the assistant reports it and skips the overlay. Write both in the same turn |
| "I'll read every body to answer `list` accurately" | Bodies are unbounded; the index carries everything `list` prints, by design |
| "This rule is universal — I'll put it in `.claude/skills/` directly" | `.claude/` is the portable harness. Promotion is a deliberate `$skill-creator` decision by the user, never a side effect of an `add` |
| "No target was given, `*` is the safe default" | `*` is the WIDEST blast radius, not the safest. Ask |
| "The user said 'just add it', so the gate is waived" | Then present the draft and let them pick *save verbatim* in one click. "Just add it" asks for speed, not for an unreviewed artifact |
| "Two overlays conflict but mine is clearly more recent, so it wins" | Recency is not authority. Equal-specificity contradictions go to the user — any tie-break invents an intent the author never expressed |

---

> **[IMPORTANT]** Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. For simple tasks (LIST, single DELETE), AI MUST ATTENTION ask user whether to skip.

<!-- PROTOCOL-GUIDES:START -->

> **Protocol guides** — A hook delivers each protocol's full text when this skill loads. If a protocol's text is not in your context, read its file below before you act on it.

- `ai-discovery-doc-quality` — Agent-guide content value, authority, retention and verified discovery; writing a doc that an agent reads → .claude/skills/shared/protocols/ai-discovery-doc-quality.md

<!-- PROTOCOL-GUIDES:END -->

<!-- SYNC:ai-discovery-doc-quality:reminder -->

**MUST ATTENTION** AI-read guides: purpose/read-when and priorities first; retain action-changing rules, exceptions and rationale; verify triggered discovery and parser contracts. Use the content-value and semantic-disposition gate after enhancement; keep evidence in temporary reports and fix generated output at its source.

<!-- /SYNC:ai-discovery-doc-quality:reminder -->

## Closing Reminders

- **MUST ATTENTION** Overlays are ADDITIVE ONLY — they add rules on top of a skill's protocol and NEVER replace, override, disable, or reinterpret one. Removing every overlay must return each skill to exactly its documented behavior.
- **MUST ATTENTION** An overlay is a brief, not an authority escalation — it can never waive an active route policy, git discipline, a review gate, a user-confirmation gate, or carry a secret. Refuse the line and report it.
- **MUST ATTENTION** ADD and UPDATE ALWAYS end at a PROPOSAL GATE showing the full rules, the skills actually matched, what changed, and anything refused — never write a draft the user has not seen.
- **MUST ATTENTION** Every write touches the body AND the index row in the SAME turn and nothing else (no `CLAUDE.md` block, no mirror sync); never commit without an explicit ask.
- **MUST ATTENTION** The registry is read at runtime by the `skill-overlay-remind` hook and the universal `project-protocol-overlay` protocol; a written overlay is live on every supported host the next time its target skill starts.