用途
project-skill-protocol 用于管理项目级“协议覆盖”（protocol overlay）注册表。它允许在不修改框架技能自带协议的前提下，为指定技能叠加本项目的额外规则。覆盖项仅做叠加：它不会替换、覆盖、禁用或重新解释框架规则；删除所有覆盖项后，每个技能会恢复到其原本文档所述的行为。
主要能力
- 四种管理操作：list（列出注册表中全部覆盖项，以表格呈现 Target、Scope、Name、Description、Updated、Body file）、add（新增）、update（更新）、delete（删除）。模式由调用文本的显式标志或首个 token 决定；如果含义有歧义，它会先询问用户，不会猜测。
- 索引与正文分离存储：索引默认是
<docsRoots.projectReference.path>/skill-protocols-reference.md（默认docs/project-reference/，可由docs/project-config.json中的docsRoots.projectReference.path覆盖，匹配的referenceDocs[]文件名可在该根目录下重新定位）；正文是<Protocols directory>/<slug>.md，目录由索引头部**Protocols directory:**声明，默认docs/project-protocols/。正文只在目标匹配时读取，不会批量读取。 - 按具体度解析：匹配发生在技能被调用时，由通用 project-protocol-overlay 协议与 skill-overlay-remind 钩子实现，规则为 exact > glob > *，同一层级胜者全取；该排序只在覆盖项彼此之间比较，不与技能本身比较。
- 新增时先起草再确认：用户的原始措辞只作为素材，不会被直接存储。新增流程会推断意图、泛化为长期约定，套用
$prompt-enhance与提示工程准则（祈使、可观察、可判定、一行一条规则、每条携带 WHY），然后进入提案关卡，展示草稿全文、实际会匹配的技能名单、改动内容与原因，并提供“按原话保存”选项。 - 仅叠加筛查与冲突检查：凡是会忽略、跳过、替换、放宽、禁用或重新解释框架规则，或豁免路由策略、git 纪律、评审关卡、用户确认关卡的规则，都会被拒收。目标与作用域相同的已有条目不会被静默覆盖，而是询问更新还是新建。
- 两次写入、同一轮完成：正文与索引行必须在同一轮写入完成；正文没有索引行就不可达，索引行没有正文则是失效解析。报告所有触及的路径，不执行提交。
使用方式
典型调用形式包括 $project-skill-protocol add …、update <name>: …、delete <name>，或直接 list 查看。工作流为：解析模式（Phase 0）→ 读取注册表契约与索引 → 执行对应模式（LIST / ADD / UPDATE / DELETE）→ 写入正文与索引行 → 发现性检查 → 报告路径。注册表为空（文件缺失、存在占位标记、表格无数据行或仅有 (none yet) 哨兵行）时视为无覆盖，静默无操作，不会列出哨兵行。
适用场景
适合需要让项目自有规范在每次运行某个或某类技能时自动生效、又不希望改动可移植框架的团队；也适合由 $learn 路由而来的“为某个技能记住规则”的请求（$learn 会先询问承载方式，推荐覆盖）。宽泛、简短、与某技能自身步骤无关的项目级规则不属于覆盖，应写入根 CLAUDE.md 的项目规则区或参考文档。
限制
- 覆盖项只能叠加，不能作为权限升级手段。
- 没有独立的 MATCH 模式；匹配仅发生在技能调用时，以避免两个解析器产生分歧。
- 索引超过约 30 行的软上限时会警告，并建议将稳定、与项目无关的覆盖通过
$skill-creator晋升为真正的技能。 - 覆盖项存放在 docs/ 下，不放在 .claude/；撰写 .claude/** 后镜像由工具生成。
- 具体 frontmatter 字段、必填章节、索引行格式、目标语法、优先级算法、冲突规则与 token 上限等完整契约需查阅
references/registry.md，资料未给出这些细则的逐项内容。