# claude-plugins-validation - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 claude-plugins-validation 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86
- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/cpv-add-component-to-plugin/SKILL.md`, `skills/cpv-add-dependency/SKILL.md`, `skills/cpv-add-hook/SKILL.md`, `skills/cpv-batch-caching-audit/SKILL.md` 等 Claim：`clm_0005` supported 0.86

## 它能做什么

- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/cpv-add-component-to-plugin/SKILL.md`, `skills/cpv-add-dependency/SKILL.md`, `skills/cpv-add-hook/SKILL.md`, `skills/cpv-batch-caching-audit/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/plugin.json`, `skills/cpv-main-menu-skill/skill-menus/03-path-source-plugin.json`, `skills/cpv-main-menu-skill/skill-menus/09-validate-marketplace.json` Claim：`clm_0002` supported 0.86
- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md` Claim：`clm_0003` supported 0.86

## 怎么开始

- `npx misroute, xmllint correctly routes to the docker fallback on a bare runner, but` 证据：`CLAUDE.md` Claim：`clm_0006` supported 0.86

## 继续前判断卡

- **当前建议**：需要管理员/安全审批
- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。

### 30 秒判断

- **现在怎么做**：需要管理员/安全审批
- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装
- **先别相信**：工具权限边界不能在安装前相信。
- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86
- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/cpv-add-component-to-plugin/SKILL.md`, `skills/cpv-add-dependency/SKILL.md`, `skills/cpv-add-hook/SKILL.md`, `skills/cpv-batch-caching-audit/SKILL.md` 等 Claim：`clm_0005` supported 0.86
- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/cpv-add-component-to-plugin/SKILL.md`, `skills/cpv-add-dependency/SKILL.md`, `skills/cpv-add-hook/SKILL.md`, `skills/cpv-batch-caching-audit/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/plugin.json`, `skills/cpv-main-menu-skill/skill-menus/03-path-source-plugin.json`, `skills/cpv-main-menu-skill/skill-menus/09-validate-marketplace.json` Claim：`clm_0002` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md` Claim：`clm_0003` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`CLAUDE.md` Claim：`clm_0006` supported 0.86

### 现在还不能相信

- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/plugin.json`, `CLAUDE.md`, `skills/cpv-add-component-to-plugin/SKILL.md`, `skills/cpv-add-dependency/SKILL.md` 等
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/plugin.json`, `skills/cpv-main-menu-skill/skill-menus/03-path-source-plugin.json`, `skills/cpv-main-menu-skill/skill-menus/09-validate-marketplace.json`
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。
- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`CLAUDE.md`

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/plugin.json`, `CLAUDE.md`, `skills/cpv-add-component-to-plugin/SKILL.md`, `skills/cpv-add-dependency/SKILL.md` 等
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/plugin.json`, `CLAUDE.md`, `skills/cpv-main-menu-skill/skill-menus/03-path-source-plugin.json`, `skills/cpv-main-menu-skill/skill-menus/09-validate-marketplace.json`
- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CLAUDE.md`, `skills/cpv-canonical-pipeline/references/v2-1-80-features.md`, `skills/cpv-fix-validation/references/hook-fixes.md`, `skills/cpv-fix-validation/references/mcp-fixes.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）
- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45
- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/plugin.json`, `skills/cpv-main-menu-skill/skill-menus/03-path-source-plugin.json`, `skills/cpv-main-menu-skill/skill-menus/09-validate-marketplace.json` Claim：`clm_0008` supported 0.86
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md` Claim：`clm_0009` supported 0.86, `clm_0010` supported 0.86, `clm_0011` supported 0.86, `clm_0012` contradicted 0.20 等
- **源文档冲突：skill_count**：项目文档中存在数量表述不一致，AI Context Pack 必须提示用户不要把单一数字当作已验证事实。 处理方式：在 Human Manual 和 AI Context Pack 中共同标记为待核实，而不是强行选择一个数字。 证据：`CLAUDE.md`, `design/tasks/TRDD-20260519_162841+0200-9dd64dbf-the-skills-menu-canonical-method.md`, `design/tasks/TRDD-20260522_175413+0200-94e06820-body-tool-consistency.md`, `agents/cpv-plugin-fixer-agent.md` Claim：`clm_0009` supported 0.86, `clm_0010` supported 0.86, `clm_0011` supported 0.86, `clm_0012` contradicted 0.20 等
- **源文档冲突：agent_count**：项目文档中存在数量表述不一致，AI Context Pack 必须提示用户不要把单一数字当作已验证事实。 处理方式：在 Human Manual 和 AI Context Pack 中共同标记为待核实，而不是强行选择一个数字。 证据：`design/tasks/TRDD-20260519_140653+0200-478d9687-skills-index-universal-loader.md`, `design/tasks/TRDD-20260519_162841+0200-9dd64dbf-the-skills-menu-canonical-method.md`, `design/tasks/TRDD-20260531_084030+0200-88a1081c-recheck-exec-sink-indirection.md`, `CLAUDE.md` Claim：`clm_0009` supported 0.86, `clm_0010` supported 0.86, `clm_0011` supported 0.86, `clm_0012` contradicted 0.20 等
- **源文件冲突 skill_count**：发现多个值 `14, 32, 41, 200`，应在真实使用前核实。
- **源文件冲突 agent_count**：发现多个值 `11, 12, 14`，应在真实使用前核实。
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/cpv-add-component-to-plugin/SKILL.md`, `skills/cpv-add-dependency/SKILL.md`, `skills/cpv-add-hook/SKILL.md`, `skills/cpv-batch-caching-audit/SKILL.md` 等 Claim：`clm_0001` supported 0.86
- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/plugin.json`, `skills/cpv-main-menu-skill/skill-menus/03-path-source-plugin.json`, `skills/cpv-main-menu-skill/skill-menus/09-validate-marketplace.json` Claim：`clm_0002` supported 0.86
- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md` Claim：`clm_0003` supported 0.86

### 上下文规模

- 文件总数：514
- 重要文件覆盖：40/514
- 证据索引条目：80
- 角色 / Skill 条目：49

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 claude-plugins-validation 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 claude-plugins-validation 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 claude-plugins-validation 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 49 个角色 / Skill / 项目文档条目。

- **cpv-add-component-to-plugin**（skill）：Add a new component skill / agent / command / hook / mcp to an existing plugin. Use when scaffolding a single component into a plugin without re-running the generator. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-add-component-to-plugin”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-add-component-to-plugin/SKILL.md`
- **cpv-add-dependency**（skill）：Add plugin dependencies to a target plugin explicit --add specs or --from copy from another plugin's plugin.json . Use when adding/copying plugin.json::dependencies entries with atomic rollback on regression. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-add-dependency”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-add-dependency/SKILL.md`
- **cpv-add-hook**（skill）：Add a new hook entry to hooks/hooks.json in an existing plugin idempotent — skips duplicate entries; cross-platform-aware . Use when adding a new event-handler that must run identically on Linux/macOS/Windows. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-add-hook”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-add-hook/SKILL.md`
- **cpv-batch-caching-audit**（skill）：Fleet-wide read-only cache audit. Accepts local paths, GitHub URLs, marketplaces, lists, and @listfile shapes. One cpv-cache-optimizer-agent per plugin runs Phase 1 only — detects CA-01..CA-07 prompt-cache invalidation patterns, no fixes. Use when surveying cache-invalidation findings across many plugins without applying changes. Trigger with /cpv-batch-caching-audit. 激活提示：当用户任务与“cpv-batch-caching-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-caching-audit/SKILL.md`
- **cpv-batch-caching-optimize**（skill）：Fleet-wide parallel cache fix. Accepts local paths, GitHub URLs, marketplaces, lists, and @listfile shapes. One cpv-cache-optimizer-agent per plugin runs Phase 1 audit + Phase 2 fix + Phase 3 re-validate; Phase 4 broader refactor SKIPPED run the cpv-cache-optimizer-agent on a single plugin to opt in . Use when applying CA-01..CA-07 fixes across many plugins. Trigger with /cpv-batch-caching-optimize. 激活提示：当用户任务与“cpv-batch-caching-optimize”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-caching-optimize/SKILL.md`
- **cpv-batch-fix-protocol**（skill）：Schema reference for the /cpv-batch-fix parallel-shard fix protocol — manifest format, status format, planner/aggregator contracts. Use when implementing a new consumer of the batch protocol or extending the planner/aggregator. Used dynamically via cpv-the-skills-menu TRDD-478d9687 — any CPV agent can invoke. 激活提示：当用户任务与“cpv-batch-fix-protocol”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-fix-protocol/SKILL.md`
- **cpv-batch-fix**（skill）：Parallel fix for one OR many plugins. Accepts local paths, GitHub URLs, marketplaces, lists, and @listfile shapes. Single-plugin input → per-shard fan-out v2.91.0 protocol . Marketplace/list input → per-plugin fan-out one cpv-plugin-fixer-agent per plugin, internal sharding when needed . Use when applying validation fixes across many plugins. Trigger with /cpv-batch-fix. 激活提示：当用户任务与“cpv-batch-fix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-fix/SKILL.md`
- **cpv-batch-full-scan-and-fix**（skill）：Maximum-coverage same-turn sweep across a marketplace / list / single plugin. Each cpv-plugin-fixer-agent reads every source file ONCE and runs validate + security + caching audit + caching optimize + verify-FPs + fix inline. ~5× cheaper than running the four separate batch skills sequentially. Use when applying every-checker fixes across many plugins at once. Trigger with /cpv-batch-full-scan-and-fix. 激活提示：当用户任务与“cpv-batch-full-scan-and-fix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-full-scan-and-fix/SKILL.md`
- **cpv-batch-scope-diagnose-and-fix**（skill）：Same-turn scope-aware diagnose + fix across a fleet of project folders. One cpv-doctor-agent per project scans + verifies + applies obvious fixes inline NIT, CRITICAL, and safe MAJOR/MINOR auto; unsafe MAJOR/MINOR reported in pending fixes . Cuts per-project token cost ~2× vs running scope-diagnose + scope-fix separately. LOCAL paths only. Use when applying obvious scope-aware doctor fixes across many project folder… 激活提示：当用户任务与“cpv-batch-scope-diagnose-and-fix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-scope-diagnose-and-fix/SKILL.md`
- **cpv-batch-scope-diagnose**（skill）：Read-only fleet-wide scope-aware doctor. One cpv-doctor-agent per project diagnoses the requested scope — user the home .claude tree , project the project .claude tree , local settings.local.json , or full all + cross-scope conflict checker . LOCAL paths only — URL inputs are CRITICAL errors because the doctor needs filesystem access to the Claude installation. Use when surveying many project folders' .claude trees… 激活提示：当用户任务与“cpv-batch-scope-diagnose”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-scope-diagnose/SKILL.md`
- **cpv-batch-scope-fix**（skill）：Apply scope-aware doctor fixes across a fleet of project folders. One cpv-doctor-agent per project in batch scope fix mode handles the requested scope user / project / local / full . Auto-applies NIT and CRITICAL fixes; reports MAJOR / MINOR fixes in pending fixes for user approval. LOCAL paths only. Use when applying mechanical doctor fixes across many project folders. Trigger with /cpv-batch-scope-fix. 激活提示：当用户任务与“cpv-batch-scope-fix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-scope-fix/SKILL.md`
- **cpv-batch-security-audit**（skill）：Fleet-wide parallel security audit. Accepts local paths, GitHub URLs, marketplaces, lists, and @listfile shapes. One cpv-plugin-validator-agent per plugin runs ONLY validate security 5 external scanners + AI/security rules . Use when checking supply-chain risk across many plugins. Trigger with /cpv-batch-security-audit or 'security-audit every plugin in X'. 激活提示：当用户任务与“cpv-batch-security-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-security-audit/SKILL.md`
- **cpv-batch-validate-and-fix**（skill）：Same-turn parallel validate-and-fix across a marketplace / list / single plugin. Each cpv-plugin-fixer-agent reads every source file ONCE — scans + verifies false positives via v2.100.x AST/JSON/markdown classifier + llm-externalizer with file-range syntax + fixes inline. ~3× cheaper per plugin than running cpv-batch-validate + cpv-batch-fix separately. Use when applying validation fixes across many plugins and you… 激活提示：当用户任务与“cpv-batch-validate-and-fix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-validate-and-fix/SKILL.md`
- **cpv-batch-validate**（skill）：Fleet-wide parallel validation. Accepts local paths, GitHub URLs, marketplaces, lists, and @listfile shapes. Dispatches one cpv-plugin-validator-agent per plugin default 8 parallel, cap 16 . Use when validating many plugins at once — e.g. every plugin in a marketplace. Trigger with /cpv-batch-validate or 'validate every plugin in X'. 激活提示：当用户任务与“cpv-batch-validate”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-batch-validate/SKILL.md`
- **cpv-bump-version**（skill）：Bump plugin version and run the full publish pipeline plugin.json, pyproject.toml, README badge, CHANGELOG, push, release . Use when bumping version + publishing the current plugin via publish.py. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-bump-version”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-bump-version/SKILL.md`
- **cpv-cache-validation-skill**（skill）：Validate plugins / projects against Anthropic's prompt-cache invalidation patterns CA-01..CA-07 . Use when auditing for cache regressions or fixing CA-01..CA-07 findings. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-cache-validation-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-cache-validation-skill/SKILL.md`
- **cpv-canonical-pipeline**（skill）： 激活提示：当用户任务与“cpv-canonical-pipeline”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-canonical-pipeline/SKILL.md`
- **cpv-create-micro-agents-workflow**（skill）：EXPERIMENTAL RLM Recursive Language Model generator — build a minimal launcher agent plus a TypeScript Workflow coordinator that decomposes any task into skill-focused micro-agents near-empty context each , runs and verifies them. Use when you want skill-per-agent, low-context execution instead of one big prefilled agent. Trigger with "create a micro-agents workflow" or /cpv-create-micro-agents-workflow. 激活提示：当用户任务与“cpv-create-micro-agents-workflow”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-create-micro-agents-workflow/SKILL.md`
- **cpv-create-mono-agent**（skill）：EXPERIMENTAL prefill-everything generator — build one MONO-agent whose body inlines ALL of a plugin's non-meta skills, so it is ready from turn 1 with every skill already in its cached context one big cache-creation, then cheap cache-reads, no dynamic skill loading that would break the prompt cache . Use when you want a single always-loaded mega-agent. Trigger with "create a mono-agent" or /cpv-create-mono-agent. 激活提示：当用户任务与“cpv-create-mono-agent”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-create-mono-agent/SKILL.md`
- **cpv-create-plugin**（skill）： 激活提示：当用户任务与“cpv-create-plugin”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-create-plugin/SKILL.md`
- **cpv-deterministic-codemod**（skill）：Deterministic codemod CLI — bulk-fix backtick-path to markdown-link, add TOC stubs, dedup blank lines, and other mechanical text transforms issue 17 . Zero LLM cost. Use when mechanical fixes outnumber semantic ones. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-deterministic-codemod”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-deterministic-codemod/SKILL.md`
- **cpv-devitalize-threats**（skill）： 激活提示：当用户任务与“cpv-devitalize-threats”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-devitalize-threats/SKILL.md`
- **cpv-diagnose-plugin-architecture**（skill）：Advisory diagnostic that detects when a Claude Code plugin ships files not needed at runtime — build-only source, dependency trees, dev-only dirs, regenerable build caches — and recommends the existing CPV lean-separation. Use when the user asks 'is my plugin too big', 'what files ship', 'reduce install size', 'lean the plugin', 'diagnose plugin architecture', 'unneeded files shipped', or wants to know which paths b… 激活提示：当用户任务与“cpv-diagnose-plugin-architecture”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-diagnose-plugin-architecture/SKILL.md`
- **cpv-fix-marketplace-validation**（skill）： 激活提示：当用户任务与“cpv-fix-marketplace-validation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-fix-marketplace-validation/SKILL.md`
- **cpv-fix-validation**（skill）： 激活提示：当用户任务与“cpv-fix-validation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-fix-validation/SKILL.md`
- **cpv-harden-and-redact**（skill）： 激活提示：当用户任务与“cpv-harden-and-redact”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-harden-and-redact/SKILL.md`
- **cpv-link-plugin-marketplace**（skill）：Link an existing plugin to an existing marketplace local or GitHub source . Use when appending an existing plugin to a marketplace.json. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-link-plugin-marketplace”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-link-plugin-marketplace/SKILL.md`
- **cpv-main-menu-skill**（skill）：Routes the /cpv-main-menu Stop-hook menu via scripts/print menu.py + claude-menu-system. Used dynamically via cpv-the-skills-menu TRDD-478d9687 — used by the /cpv-main-menu flow. Use when navigating CPV's many commands via a single entry point. 激活提示：当用户任务与“cpv-main-menu-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-main-menu-skill/SKILL.md`
- **cpv-marketplace-authoring-contract**（skill）： 激活提示：当用户任务与“cpv-marketplace-authoring-contract”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-marketplace-authoring-contract/SKILL.md`
- **cpv-migrate-marketplace-architecture**（skill）： 激活提示：当用户任务与“cpv-migrate-marketplace-architecture”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-migrate-marketplace-architecture/SKILL.md`
- **cpv-pack-components**（skill）：Pack a folder of standalone components skill/agent/command/hook/mcp/lsp/monitor/output-style into a new installable plugin. Use when bundling loose components into a single publishable plugin. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-pack-components”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-pack-components/SKILL.md`
- **cpv-plugin-management**（skill）： 激活提示：当用户任务与“cpv-plugin-management”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-plugin-management/SKILL.md`
- **cpv-plugin-validation-skill**（skill）：Validates Claude Code plugins for structural correctness, quality, and marketplace readiness. Use when validating, fixing, migrating, upgrading, or scaffolding a plugin. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . Embeds canonical plugins-reference.md. 激活提示：当用户任务与“cpv-plugin-validation-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-plugin-validation-skill/SKILL.md`
- **cpv-publish-to-marketplace**（skill）： 激活提示：当用户任务与“cpv-publish-to-marketplace”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-publish-to-marketplace/SKILL.md`
- **cpv-refresh-readme**（skill）：Refresh AUTO- marker blocks in a plugin's README auto-detected components table . Use when the README's components list has drifted from the filesystem. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-refresh-readme”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-refresh-readme/SKILL.md`
- **cpv-register-mcp**（skill）：Register a new MCP server in an existing plugin's .mcp.json stdio default; supports HTTP transport via --http-url; cross-platform command via Python/Node . Use when adding a new MCP server entry. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-register-mcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-register-mcp/SKILL.md`
- **cpv-scaffold-agent**（skill）：Scaffold a new agent in an existing plugin creates agents/{NAME}.md with valid frontmatter that passes validate plugin out of the box . Use when adding a single agent to an existing plugin. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-scaffold-agent”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-scaffold-agent/SKILL.md`
- **cpv-scaffold-command**（skill）：Scaffold a new slash command in an existing plugin creates commands/{NAME}.md with valid frontmatter that passes validate plugin out of the box . Use when adding a single slash command to an existing plugin. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-scaffold-command”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-scaffold-command/SKILL.md`
- **cpv-scaffold-skill**（skill）：Scaffold a new skill in an existing plugin creates skills/{NAME}/SKILL.md with valid frontmatter that passes validate plugin out of the box . Use when adding a single skill to an existing plugin. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-scaffold-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-scaffold-skill/SKILL.md`
- **cpv-semantic-validation-skill**（skill）：Deep AI semantic validation for skills/agents. Use when checking triggering, clarity, examples. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 10x token cost. 激活提示：当用户任务与“cpv-semantic-validation-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-semantic-validation-skill/SKILL.md`
- **cpv-setup-github-marketplace**（skill）： 激活提示：当用户任务与“cpv-setup-github-marketplace”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-setup-github-marketplace/SKILL.md`
- **cpv-setup-marketplace-auto-notification**（skill）： 激活提示：当用户任务与“cpv-setup-marketplace-auto-notification”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-setup-marketplace-auto-notification/SKILL.md`
- **cpv-setup-plugin-repo**（skill）： 激活提示：当用户任务与“cpv-setup-plugin-repo”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-setup-plugin-repo/SKILL.md`
- **cpv-show-version**（skill）：Show the CPV management tools version. Use when reporting the installed CPV CLI version. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-show-version”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-show-version/SKILL.md`
- **cpv-skill-validation-skill**（skill）： 激活提示：当用户任务与“cpv-skill-validation-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-skill-validation-skill/SKILL.md`
- **cpv-standardize-plugin**（skill）： 激活提示：当用户任务与“cpv-standardize-plugin”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-standardize-plugin/SKILL.md`
- **cpv-strip-dev-submodules**（skill）：Move dev-only folders or compile source out of a plugin's MAIN repo into a SEPARATE repo referenced by pinned URL + SHA, so the installed plugin stops shipping them. Use when shrinking a plugin install before publishing, or when creating the PUBLIC compile-source repo the ship-only-binary canon requires. Used dynamically via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-strip-dev-submodules”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-strip-dev-submodules/SKILL.md`
- **cpv-the-skills-menu-create**（skill）：Convert any Claude Code plugin from static agent skill assignment to cpv-the-skills-menu method. Use when migrating a plugin so its agents load operational skills dynamically via the Skill tool instead of preloading static lists. Trigger with /cpv-the-skills-menu-create or when the user asks to migrate / standardize / decouple a plugin's skill discovery. Used via cpv-the-skills-menu TRDD-478d9687 . 激活提示：当用户任务与“cpv-the-skills-menu-create”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-the-skills-menu-create/SKILL.md`
- **cpv-the-skills-menu**（skill）：Agent-facing à-la-carte menu of every claude-plugins-validation CPV skill, agent, and script: classifies a plugin-quality request — validate, security-scan, fix, cache-optimize, create, publish, marketplace, manage, semantic-grade — and routes it to the right tool. Use when a request mentions CPV, the CPV skills menu, or validating / fixing / publishing / scanning / cache-optimizing a plugin and the exact tool is un… 激活提示：当用户任务与“cpv-the-skills-menu”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/cpv-the-skills-menu/SKILL.md`

## 证据索引

- 共索引 80 条证据。

- **Claude Plugins Validation CPV**（documentation）：! Version https://img.shields.io/badge/version-3.23.1-blue ! Tests https://img.shields.io/badge/tests-10000%2B%20passed-brightgreen ! Validation https://img.shields.io/badge/validation-0%20issues-brightgreen ! License https://img.shields.io/badge/license-MIT-green 证据：`README.md`
- **cpv-fix-marketplace-validation — References Stub**（documentation）：cpv-fix-marketplace-validation — References Stub 证据：`skills/cpv-fix-marketplace-validation/references/README.md`
- **Plugin Validation Skill**（documentation）：Comprehensive validation skill for Claude Code plugins, marketplaces, hooks, skills, and MCP servers. 证据：`skills/cpv-plugin-validation-skill/README.md`
- **cpv-add-component-to-plugin**（skill_instruction）：Adds a new component skill / agent / command / hook / mcp to an existing plugin without re-running the generator or hand-editing scaffolds. Each component lands as a minimal but valid stub with frontmatter that passes validate plugin / validate skill out of the box. Loaded dynamically via cpv-the-skills-menu, reached via the Manage → Add component menu branch. 证据：`skills/cpv-add-component-to-plugin/SKILL.md`
- **cpv-add-dependency**（skill_instruction）：Adds one or more plugin dependencies to a target plugin's plugin.json::dependencies array. Two input modes that can be combined; the engine deduplicates by name last-write-wins , sorts the result alphabetically, writes atomically, and rolls back from a .bak if the post-write validation introduces any new CRITICAL/MAJOR finding. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Add dependencies menu branch. 证据：`skills/cpv-add-dependency/SKILL.md`
- **cpv-add-hook**（skill_instruction）：Adds a new hook entry to a plugin's hooks/hooks.json . The scaffold is idempotent — re-running with the same event+command is a no-op. The new hook command MUST be cross-platform: prefer Python or Node.js delegation. Bash-only constructs set -euo pipefail , , $ <file , process substitution, brace expansion will trigger validate hook MAJOR findings. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Add hook menu branch. 证据：`skills/cpv-add-hook/SKILL.md`
- **cpv-batch-caching-audit**（skill_instruction）：Read-only parallel cache audit. Runs Phase 1 Audit of the cpv-cache-optimizer-agent workflow across every plugin in the user's input spec — detecting the seven documented prompt-cache invalidation patterns CA-01..CA-07 per plugin without applying fixes. Apply fixes later with /cpv-batch-caching-optimize which uses the same input grammar . 证据：`skills/cpv-batch-caching-audit/SKILL.md`
- **cpv-batch-caching-optimize**（skill_instruction）：Parallel cache-fix skill. Runs Phase 1 Audit → Phase 2 Fix → Phase 3 Re-validate of the cpv-cache-optimizer-agent workflow across every plugin in the user's input spec. Phase 4 Broader refactor is deliberately skipped in batch mode because every Phase 4 step requires interactive per-step approval and that doesn't compose with a parallel dispatch. 证据：`skills/cpv-batch-caching-optimize/SKILL.md`
- **cpv-batch-fix-protocol**（skill_instruction）：/cpv-batch-fix slices a plugin's validation findings into parallel-fix shards and dispatches N cpv-plugin-fixer-agent agents from the main session — one per shard, each with a fresh context window whose size depends on cpv-plugin-fixer-agent.model per-model — never assume a fixed limit . This skill documents the data contract that ties the planner, the shard agents, and the aggregator together. Loaded by cpv-plugin-fixer-agent when it sees mode: batch shard in its context block and by the /cpv-batch-fix slash command body. 证据：`skills/cpv-batch-fix-protocol/SKILL.md`
- **cpv-batch-fix**（skill_instruction）：Parallel fix skill for one OR many plugins. Two dispatch shapes: 证据：`skills/cpv-batch-fix/SKILL.md`
- **cpv-batch-full-scan-and-fix**（skill_instruction）：Same-turn maximum-coverage sweep. Each cpv-plugin-fixer-agent subagent reads every source file ONCE and triggers EVERY applicable in-process checker validate, security, caching, lint, xref, encoding, … , classifies findings via the v2.100.x context classifier, verifies uncertain findings via llm-externalizer with file-range syntax ≤ 200 LOC per call , applies confirmed-real fixes inline, then runs one clean-room re-check. 证据：`skills/cpv-batch-full-scan-and-fix/SKILL.md`
- **cpv-batch-scope-diagnose-and-fix**（skill_instruction）：Same-turn variant of the scope-aware doctor batch family. Each cpv-doctor-agent subagent reads each scope-anchored file ONCE, classifies findings, and applies the obvious mechanical fixes inline. Cuts per-project token cost ~2× vs running cpv-batch-scope-diagnose + cpv-batch-scope-fix separately. 证据：`skills/cpv-batch-scope-diagnose-and-fix/SKILL.md`
- **cpv-batch-scope-diagnose**（skill_instruction）：Read-only scope-aware doctor across a fleet of project folders. Each cpv-doctor-agent subagent diagnoses one of: 证据：`skills/cpv-batch-scope-diagnose/SKILL.md`
- **cpv-batch-scope-fix**（skill_instruction）：Counterpart to cpv-batch-scope-diagnose ../cpv-batch-scope-diagnose/SKILL.md . After the doctor has diagnosed each project, this skill dispatches one per project in fix mode to apply the obvious mechanical fixes. The same scope semantics apply. 证据：`skills/cpv-batch-scope-fix/SKILL.md`
- **cpv-batch-security-audit**（skill_instruction）：Parallel security-audit skill. Runs ONLY the validate security checker 5 external scanners — cc-audit, tirith, trufflehog, semgrep, Cisco AI Defense skill-scanner — plus the in-process AI and security rule packs across every plugin in the user's input spec. Skips ~36 non-security validators that the full pipeline runs, so wall-time is lower when you only care about supply-chain risk. Both pipelines benefit from v2.103.0's per-file parallel scanning — the relative gap depends on plugin shape. 证据：`skills/cpv-batch-security-audit/SKILL.md`
- **cpv-batch-validate-and-fix**（skill_instruction）：Same-turn variant of the parallel validate + fix pipeline. Each cpv-plugin-fixer-agent subagent reads every source file ONCE, scans + verifies FPs inline via the v2.100.x context classifier + llm-externalizer with file-range syntax — minimum-token FP verification , applies confirmed-real fixes, and runs one clean-room re-check. 证据：`skills/cpv-batch-validate-and-fix/SKILL.md`
- **cpv-batch-validate**（skill_instruction）：Parallel-validation skill for a fleet of Claude Code plugins. Resolves the user's input via scripts/cpv marketplace input.py every shape from §Inputs , builds a batch plan via scripts/cpv batch orchestrator.py , dispatches one cpv-plugin-validator-agent subagent per plugin in batch validate mode, and aggregates per-plugin status JSONs into a CMS-shaped status table spec which is queued via scripts/cpv menu.py . The claude-menu-system Stop hook emits the table to the user post-turn zero token cost — never enters the agent transcript . 证据：`skills/cpv-batch-validate/SKILL.md`
- **cpv-bump-version**（skill_instruction）：Bumps the plugin version AND runs the full publish pipeline TRDD-bbff5bc5 — single entry point . publish.py is the canonical entry point — it bumps the version in plugin.json + pyproject.toml + version vars, refreshes the README badge, regenerates the CHANGELOG, refreshes .plugin-self-hashes.json if present , commits + tags + pushes, then creates the GitHub release. Every gate must pass before any push no --skip- flags exist . Loaded dynamically via cpv-the-skills-menu, reached via the Manage → Bump version menu branch. 证据：`skills/cpv-bump-version/SKILL.md`
- **Cache-Audit Skill loaded by cpv-cache-optimizer-agent**（skill_instruction）：Cache-Audit Skill loaded by cpv-cache-optimizer-agent 证据：`skills/cpv-cache-validation-skill/SKILL.md`
- **Canonical Plugin Pipeline Standard**（skill_instruction）：Defines the standard files, workflows, hooks, and release pipeline that every Emasoft Claude Code plugin repository MUST have. Covers Python, JavaScript/TypeScript, Rust, Go, and Shell plugins. Pipeline supports all three CPV layouts A: separate plugin and marketplace repos; B: nested monorepo; C: marketplace-in-plugin self-referential single repo . 证据：`skills/cpv-canonical-pipeline/SKILL.md`
- **cpv-create-micro-agents-workflow**（skill_instruction）：Generates the RLM Recursive Language Model architecture into a target plugin — the opposite of cpv-create-mono-agent . Instead of prefilling one huge agent, each skill is run as a FOCUSED micro-agent with almost no context just that skill and one clear input , and a coordinator sequences them. Small context ⇒ the pattern is more likely "in-distribution" better training-memory recall and every turn is cheap. Only ONE agent is created — a thin launcher — because the per-skill micro-agents are spawned dynamically by the Workflow tool, not hand-authored one-per-skill. 证据：`skills/cpv-create-micro-agents-workflow/SKILL.md`
- **cpv-create-mono-agent**（skill_instruction）：Generates a mono-agent into a target plugin: one agent agents/ -mono-agent.md whose body is the plugin's entire non-meta skill set concatenated together. This is the prefill-everything cache optimization — the whole skill set enters the agent's cached context prefix ONCE a single cache-creation cost, then ~1/10-price cache-reads , so the agent is ready from turn 1, never needs to dynamically load a skill which would break the prompt cache each time , and is nudged to actually USE its skills. It is the opposite of cpv-create-micro-agents-workflow which shrinks context instead of prefilling it . 证据：`skills/cpv-create-mono-agent/SKILL.md`
- **Create Plugin / Marketplace**（skill_instruction）：Scaffolds complete Claude Code plugin or marketplace repositories with standard files, CI/CD workflows, git hooks, and release pipeline. 证据：`skills/cpv-create-plugin/SKILL.md`
- **cpv-deterministic-codemod**（skill_instruction）：Bulk-applies the inverse of CPV's detection regexes — read-only audit becomes read-write fix at zero LLM cost. Designed for high-volume mechanical fixes where the cpv-plugin-fixer-agent agent is the wrong tool because the work is line-local and predictable. Addresses GitHub issue 17 https://github.com/Emasoft/claude-plugins-validation/issues/17 and the high-volume Categories C and D of issue 16 https://github.com/Emasoft/claude-plugins-validation/issues/16 . Loaded dynamically via cpv-the-skills-menu, reached via the Fix → Deterministic codemod menu branch. 证据：`skills/cpv-deterministic-codemod/SKILL.md`
- **Devitalize Threats — execution-shape to inert-data transformation catalog**（skill_instruction）：Devitalize Threats — execution-shape to inert-data transformation catalog 证据：`skills/cpv-devitalize-threats/SKILL.md`
- **cpv-diagnose-plugin-architecture**（skill_instruction）：This skill detects when a Claude Code plugin ships files that are not needed at install/runtime, and recommends the EXISTING CPV lean-separation machinery for each. It is the DETECTION front-end; the actual separation is a SEPARATE step cpv strip-dev-parts , .gitignore , the ${CLAUDE PLUGIN DATA} install-on-first-use pattern . 证据：`skills/cpv-diagnose-plugin-architecture/SKILL.md`
- **Fix Marketplace Validation — Error-to-Fix Index**（skill_instruction）：Fix Marketplace Validation — Error-to-Fix Index 证据：`skills/cpv-fix-marketplace-validation/SKILL.md`
- **Fix Validation — Error-to-Fix Index**（skill_instruction）：Fix Validation — Error-to-Fix Index 证据：`skills/cpv-fix-validation/SKILL.md`
- **Harden and Redact — leak-redaction and safeguard-hardening catalog**（skill_instruction）：Harden and Redact — leak-redaction and safeguard-hardening catalog 证据：`skills/cpv-harden-and-redact/SKILL.md`
- **cpv-link-plugin-marketplace**（skill_instruction）：Appends an existing plugin to an existing marketplace's marketplace.json , preserving entries for other plugins. If a plugin with the same name is already listed, its entry is replaced in place with fresh metadata so re-runs stay idempotent — one entry per name, never duplicated . Uses the correct source.source schema key not the legacy source.type . Loaded dynamically via cpv-the-skills-menu, reached via the GitHub setup → Link plugin menu branch. 证据：`skills/cpv-link-plugin-marketplace/SKILL.md`
- **CPV Main-Menu Routing Skill**（skill_instruction）：Backing skill for /cpv-main-menu . Holds the FIXED menu specs shipped as JSON files in skill-menus/NN- .json , per-leaf execution recipes, AND the FIXED-KEY ROUTING CONTRACT letter→action maps for every menu in the tree. Every menu is rendered by the claude-menu-system plugin's Stop-hook emitter — the orchestrator queues a spec via scripts/print menu.py and ENDS its turn; the hook prints the menu post-turn via the hook JSON systemMessage field, so the menu is shown to the user but NEVER enters the transcript or prompt cache. print menu.py keeps the queue Bash card tiny: a FIXED menu is queued with just its index print menu.py fixed NN ; a DYNAMIC menu rows vary at runtime is queued with onl… 证据：`skills/cpv-main-menu-skill/SKILL.md`
- **Marketplace Authoring Contract**（skill_instruction）：Seven sub-rules make marketplace.json authoring deterministic. Agents internalise them and emit correct entries on the FIRST try; validate marketplace.py --strict upstream cross-validation runs unconditionally becomes a safety net. 证据：`skills/cpv-marketplace-authoring-contract/SKILL.md`
- **Migrate Marketplace Architecture**（skill_instruction）：Converts a non-CPV marketplace into one of three CPV layouts: A hub-and-spoke , B nested single-repo , or C marketplace-in-plugin self-referential . Preserves per-plugin git history and logs every decision. 证据：`skills/cpv-migrate-marketplace-architecture/SKILL.md`
- **cpv-pack-components**（skill_instruction）：Converts a folder of standalone Claude Code components into a single installable plugin. Useful for recovering from "Phase 0 plugin-shape detection refused" — wrap the detected components into a real plugin shape that loads correctly. Also useful for rolling skills / agents / commands from disparate projects into a shared plugin, or migrating ad-hoc component folders to publishable plugins without hand-editing manifests. The script discovers every supported component type, validates the selection, then scaffolds a fresh plugin and copies the components into their canonical locations. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Pack components menu branch. 证据：`skills/cpv-pack-components/SKILL.md`
- **Plugin Management**（skill_instruction）：Scripts at ${CLAUDE PLUGIN ROOT}/scripts/ for the full plugin lifecycle. 证据：`skills/cpv-plugin-management/SKILL.md`
- **Plugin Validation Skill**（skill_instruction）：Phase 0 — plugin-shape detection MANDATORY before any other action 证据：`skills/cpv-plugin-validation-skill/SKILL.md`
- **Publish Plugin to Marketplace**（skill_instruction）：Publishes a validated Claude Code plugin to a GitHub-hosted marketplace repo. Configures notification workflow, PAT secret, and publish pipeline. 证据：`skills/cpv-publish-to-marketplace/SKILL.md`
- **cpv-refresh-readme**（skill_instruction）：Auto-refreshes the block in a plugin's README.md so it never drifts out of sync with what the plugin actually ships agents, skills, commands, hooks, MCP servers . Detects components from the filesystem and renders a markdown table inside the markers. Custom prose around the block stays user-owned. Loaded dynamically via cpv-the-skills-menu, reached via the Manage → Refresh README menu branch. 证据：`skills/cpv-refresh-readme/SKILL.md`
- **cpv-register-mcp**（skill_instruction）：Registers a new MCP server in a plugin's .mcp.json . The default transport is stdio executable spawned per session . HTTP transport is also supported via the --http-url flag. The server's command MUST be cross-platform — invoke it via node , python3 , uv run , or npx so it runs identically on Linux, macOS, and Windows. A bare relative shell-script command e.g. ./run.sh is a portability footgun: validate mcp flags a relative file path that omits ${CLAUDE PLUGIN ROOT} as a MINOR finding, and a .sh entry point will not run on Windows at all — always wrap it in a cross-platform interpreter. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Add MCP server menu branch. 证据：`skills/cpv-register-mcp/SKILL.md`
- **cpv-scaffold-agent**（skill_instruction）：Adds a new agent to an existing plugin. The scaffold lands at /agents/ .md with valid frontmatter so the plugin still passes validate plugin immediately. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Add agent menu branch. 证据：`skills/cpv-scaffold-agent/SKILL.md`
- **cpv-scaffold-command**（skill_instruction）：Adds a new slash command to an existing plugin. The scaffold lands at /commands/ .md with valid frontmatter so the plugin still passes validate plugin immediately. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Add slash command menu branch. 证据：`skills/cpv-scaffold-command/SKILL.md`
- **cpv-scaffold-skill**（skill_instruction）：Adds a new skill to an existing plugin. The scaffold lands at /skills/ /SKILL.md with valid frontmatter so the plugin still passes validate plugin immediately. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Add skill menu branch. 证据：`skills/cpv-scaffold-skill/SKILL.md`
- **Semantic Validation Skill**（skill_instruction）：Deep AI analysis. Opus 1M, ~10-50× tokens of script validation. 证据：`skills/cpv-semantic-validation-skill/SKILL.md`
- **Setup GitHub Marketplace**（skill_instruction）：Automates creation of a GitHub-hosted Claude Code plugin marketplace. Handles CI/CD setup, batch plugin linking, and cross-marketplace migration. 证据：`skills/cpv-setup-github-marketplace/SKILL.md`
- **Setup Marketplace Auto Notification**（skill_instruction）：Setup Marketplace Auto Notification 证据：`skills/cpv-setup-marketplace-auto-notification/SKILL.md`
- **Setup Plugin Repository**（skill_instruction）：Creates a Claude Code plugin GitHub repo with CI/CD, git hooks, and marketplace notification. 证据：`skills/cpv-setup-plugin-repo/SKILL.md`
- **cpv-show-version**（skill_instruction）：Shows the CPV management CLI version by invoking manage plugin.py --version . Loaded dynamically via cpv-the-skills-menu, reached via the Help → Show CPV version menu branch. 证据：`skills/cpv-show-version/SKILL.md`
- **Skill Validation Skill**（skill_instruction）：Validates skill directories using 190+ validation rules from: - AgentSkills OpenSpec — 44 rules - Nixtla Quality Standards — 52 rules - Meta-Skill Validation — 47 rules - Component Validators — 25 rules 证据：`skills/cpv-skill-validation-skill/SKILL.md`
- **Standardize Plugin / Marketplace**（skill_instruction）：Audits existing plugin or marketplace repositories against CPV standards and auto-fixes missing files, workflows, and hooks. 证据：`skills/cpv-standardize-plugin/SKILL.md`
- **cpv-strip-dev-submodules**（skill_instruction）：Shrinks a plugin install by moving dev-only folders — or the compile source of a compiled component — out of the plugin tree into a SEPARATE GitHub repository, and recording a {path, url, sha} reference in .claude-plugin/plugin.json under cpv.strip.extract . The extracted directory is REMOVED from the plugin tree and no .gitmodules is written, so the content stops shipping. --restore re-clones each reference pinned to its SHA for local development. Loaded dynamically via cpv-the-skills-menu, reached via the Manage → Strip dev parts menu branch. 证据：`skills/cpv-strip-dev-submodules/SKILL.md`
- **cpv-the-skills-menu-create — universal skill-discovery migrator**（skill_instruction）：cpv-the-skills-menu-create — universal skill-discovery migrator 证据：`skills/cpv-the-skills-menu-create/SKILL.md`
- **cpv-the-skills-menu — universal CPV router + catalog**（skill_instruction）：cpv-the-skills-menu — universal CPV router + catalog 证据：`skills/cpv-the-skills-menu/SKILL.md`
- **Plugin**（structured_config）：{ "name": "claude-plugins-validation", "version": "3.23.1", "description": "Comprehensive validation, management, and standardization suite for Claude Code plugins and marketplaces. Includes 190+ validation rules, plugin lifecycle management, marketplace operations, health checks, security auditing, GitHub repo validation, plugin/marketplace repo scaffolding, and standardization tooling. Features severity hierarchy, --strict mode, language-aware token estimation, and universal plugin/marketplace templates.", "author": { "name": "Emasoft", "email": "713559+Emasoft@users.noreply.github.com" }, "homepage": "https://github.com/Emasoft/claude-plugins-validation", "repository": "https://github.co… 证据：`.claude-plugin/plugin.json`
- **CLAUDE.md — claude-plugins-validation CPV**（documentation）：CLAUDE.md — claude-plugins-validation CPV 证据：`CLAUDE.md`
- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`
- **Changelog**（documentation）：All notable changes to the Claude Plugins Validation plugin will be documented in this file. 证据：`CHANGELOG.md`
- **CPV — general router agent**（documentation）：You are the general-purpose worker for the claude-plugins-validation CPV plugin. A caller hands you a free-form request about plugin quality; your job is to classify it, run the right CPV tool, and return the result — without the caller needing to know any script names, agent names, or flags. 证据：`agents/cpv-agent.md`
- **Plugin Devitalizer Agent**（documentation）：You are a self-sufficient security devitalization agent. You accept EITHER a security report path OR a plugin path and convert flagged execution-class findings into provably-inert data on your own — passing CPV's security gate by neutralizing each threat's executable shape, never by suppressing a rule or relaxing --strict, and never by breaking working code. 证据：`agents/cpv-plugin-devitalizer-agent.md`
- **Plugin Diagnoser Agent**（documentation）：You are the deep diagnostic auditor for Claude Code plugins: you produce a structured, read-only diagnosis of an existing plugin and then orchestrate fixes — you NEVER mutate the plugin yourself. Every fix is dispatched to a specialised agent cpv-plugin-fixer-agent, cpv-marketplace-fixer-agent, cpv-plugin-creator-agent only after the user explicitly chooses an option from the Phase 9 follow-up menu. 证据：`agents/cpv-plugin-diagnoser-agent.md`
- **Plugin Fixer Agent**（documentation）：You are a self-sufficient fix agent. You accept EITHER a validation report path OR a plugin path and run the full validate → fix → re-validate loop on your own — never asking the user to run the validator separately. Load skills on demand with the Skill tool any agent may invoke any skill; skills: frontmatter is a pre-loading hint, not an ACL ; load only what each task needs: 证据：`agents/cpv-plugin-fixer-agent.md`
- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `skills/cpv-fix-marketplace-validation/references/README.md`, `skills/cpv-plugin-validation-skill/README.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `skills/cpv-fix-marketplace-validation/references/README.md`, `skills/cpv-plugin-validation-skill/README.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **Overview, Installation & Two Usage Modes**：importance `high`
  - source_paths: README.md, CHANGELOG.md, pyproject.toml, .claude-plugin/plugin.json
- **Repository Structure & Component Map**：importance `high`
  - source_paths: agents/cpv-agent.md, commands/cpv-main-menu.md, scripts/cli.py, scripts/manage_plugin.py
- **Pipeline & CLI Architecture**：importance `high`
  - source_paths: scripts/remote_validation.py, scripts/validate_plugin.py, scripts/cpv_validation_common.py, scripts/cpv_batch_orchestrator.py, scripts/cpv_batch_aggregator.py
- **Validation Engines (25 validate_*.py Scripts, 190+ Rules)**：importance `high`
  - source_paths: scripts/validate_plugin.py, scripts/validate_skill.py, scripts/validate_hook.py, scripts/validate_security.py, scripts/validate_marketplace.py
- **Security Scanning & Skillaudit (FP-handling Pipeline)**：importance `high`
  - source_paths: scripts/cpv_skillaudit_native.py, scripts/_skillaudit_python_context.py, scripts/_skillaudit_shell_context.py, scripts/_skillaudit_markdown_context.py, scripts/validate_security.py
- **AI Agents — Routing, Diagnose, Fix, Devitalize, Harden**：importance `high`
  - source_paths: agents/cpv-agent.md, agents/cpv-plugin-validator-agent.md, agents/cpv-plugin-fixer-agent.md, agents/cpv-plugin-devitalizer-agent.md, agents/cpv-plugin-leaks-preventer-agent.md
- **Skill Catalog & The Skills Menu**：importance `high`
  - source_paths: skills/cpv-the-skills-menu/SKILL.md, skills/cpv-the-skills-menu/references/skills-catalog.md, skills/cpv-main-menu-skill/SKILL.md, skills/cpv-main-menu-skill/references/menu-tree.md, skills/cpv-plugin-validation-skill/SKILL.md
- **Canonical Pipeline, publish.py & CI/CD**：importance `high`
  - source_paths: scripts/publish.py, scripts/validate_marketplace_pipeline.py, scripts/cpv_ci_preflight.py, scripts/cpv_ci_parity_checks.py, scripts/setup_plugin_pipeline.py

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `3f0f6cc763fece2ef5b2b3522328403f091ec6b7`
- inspected_files: `README.md`, `pyproject.toml`, `requirements.txt`, `uv.lock`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 失败模式：security_permissions: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-...

- Trigger: Developers should check this security_permissions risk before relying on the project: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause). Context: Observed when using python
- Why it matters: Developers may expose sensitive permissions or credentials: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/169 | Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 失败模式：security_permissions: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note descrip...

- Trigger: Developers should check this security_permissions risk before relying on the project: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156). Context: Observed during installation or first-run setup.
- Why it matters: Developers may expose sensitive permissions or credentials: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/178 | skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 失败模式：security_permissions: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed on...

- Trigger: Developers should check this security_permissions risk before relying on the project: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag. Context: Observed when using python, docker
- Why it matters: Developers may expose sensitive permissions or credentials: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/165 | standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 来源证据：Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release s…

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/180 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 失败模式：installation: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build...

- Trigger: Developers should check this installation risk before relying on the project: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets. Context: Observed when using python, macos, linux
- Why it matters: Developers may fail before the first successful local run: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/180 | Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 失败模式：installation: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability...

- Trigger: Developers should check this installation risk before relying on the project: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately. Context: Observed when using playwright
- Why it matters: Developers may fail before the first successful local run: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/174 | Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 失败模式：installation: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)

- Trigger: Developers should check this installation risk before relying on the project: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently). Context: Observed when using python
- Why it matters: Developers may fail before the first successful local run: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/175 | feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 失败模式：installation: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zs...

- Trigger: Developers should check this installation risk before relying on the project: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc). Context: Observed during installation or first-run setup.
- Why it matters: Developers may fail before the first successful local run: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/177 | skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 失败模式：installation: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex mis...

- Trigger: Developers should check this installation risk before relying on the project: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia.... Context: Observed when using python
- Why it matters: Developers may fail before the first successful local run: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
- Evidence: failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/167 | v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 可能修改宿主 AI 配置

- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Evidence: capability.host_targets | https://github.com/Emasoft/claude-plugins-validation | host_targets=mcp_host, claude_code, claude
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。