skill-governance

Skill 治理

治理用户实际体验到的 Skill 界面：预期的热入口或路由器入口在全新主机上完全可见，冷能力仍可访问，可编辑行为有唯一的规范归属方，并且每项退役操作都可恢复。目录数量减少并非目标。

必需结果约定

开始操作前，用一句话说明：

• 哪些入口或路由器必须对模型可见；
• 哪些能力必须保持冷态可用；
• 用户授权更改哪一层；
• 哪些全新主机证据能够证明成功。

如果请求只是“有多少／加载了什么／为什么”，则只读操作。

系统模型

切勿将以下层级混为一谈：

1. 规范源 — 可编辑自有行为的位置。
2. 已安装清单 — 磁盘上存在的套件和版本。
3. 发现策略 — Claude 或 Codex 可以发现的内容。
4. 模型可见目录 — 全新模型提示词中的元数据。
5. 运行时资源 — 路由器仍需使用的隐藏脚本、参考资料和资源。

已安装不代表已启用；已启用不能证明可见；可见也不能证明可用。数量和字节总量仅用于诊断。

权限顺序

以当前运行时事实为准，不要依赖记忆中的惯例：

• 对于可编辑的 Skill 行为，以自有源代码仓库及其清单为准；
• 对于当前 Claude marketplace／安装状态，以 claude plugin ... --json 为准；
• 对于受管理的 Daymade 链接，以明确的源同步启用清单为准；
• Codex 当前的用户 Skill 根目录为 ~/.agents/skills；
• 对于 Codex 发现禁用项，以精确路径 ~/.codex/config.toml 中的策略为准；
• 对于实际的全新 Codex 目录，以 codex debug prompt-input 为准；
• 对于第三方冷资源，以已安装的供应商套件为准。

除非当前本地约定明确赋予 ~/.codex/skills 其他用途，否则它属于旧版／系统兼容目录。切勿仅为让归属看起来完整，就将第三方清单移入自有源启用清单。

路由请求

使用该工作流前，请完整阅读 references/skill-surface-governance.md 中所列章节。

请求	阅读并使用
明确的交付约定；验证源归属方、注册情况和已安装路由	§16，然后执行 §14 中所需的全新主机门槛
Codex 实际加载的内容；数量、截断、重复身份、缺失的路由器	§3–4，然后 §11
核对自有源链接或 ~/.agents/skills 启用情况	§2–5，然后 §11
让 gstack/Lark/IMA/UiPath 或其他套件保持冷态，并通过路由器访问	§2–4、§6，然后 §11
Claude marketplace／插件源或已安装状态偏差	§2–3、§7，然后 §11
旧缓存版本	§2 和 §7“特殊手动缓存修复”
被套件取代的独立插件	§7–8，然后 §11
项目 .claude/skills 与 .agents/skills 偏差	§9，然后 §11
退役松散或重复的 Skill 目录	§2–3、§10–11
决定哪些 Skill 对模型可见，哪些仅供用户调用	§15，然后 §11

快速只读 Codex 审计

对于本地使用属于交付内容的新注册 Skill，在将其视为就绪之前，先运行 references/skill-surface-governance.md §14 中的目标名称检查。 这涵盖 Claude 的全新命令目录和 Codex 的全新提示词。 名称必须来自用户要求的交付内容，而不能仅来自当前白名单。

从此 Skill 包运行：

python3 scripts/audit_codex_skill_surface.py --json

仅添加用户或激活 SSOT 实际声明的策略：

python3 scripts/audit_codex_skill_surface.py \
  --require-visible gstack-router \
  --json

该脚本会将 codex debug prompt-input 与 Codex 自身 app-server skills/list 解析出的完整元数据，以及精确的激活／发现策略进行比较。 退出码 0 表示无问题，1 表示存在压力或漂移，需要分类处理，2 表示证据无效。 该脚本为只读脚本。不要将退出码 1 转换为自动清理。

对于项目的双根目录：

python3 scripts/audit_project_skill_roots.py <project-root> --json

该审计会按 frontmatter 中的 name 配对直接子级包，只识别其明确声明的、 故障可见的兼容性路由器契约，并区分共享目标、完全相同的副本、实际漂移和无效状态。

不可妥协的安全边界

• 漂移检查为只读。配置编辑、链接同步、安装、卸载、移动、缓存修复和 Marketplace 源变更均须获得授权。
• 保留 Claude 插件的作用域。在弃用旧标识之前，先验证替代项。
• 切勿通过直接复制缓存来安装或同步源文件。
• 不要强制要求“缓存只保留一个版本”。当前 Claude Code 会为运行中的会话管理孤立版本的宽限期；手动删除缓存仅限特殊修复场景。
• 不要盲目地先移除再添加 Marketplace。移除最后一个有作用域的 Marketplace 可能会卸载其插件。
• 将候选项判定为冗余之前，先阅读其所有独有的说明、脚本、参考资料和资源。 旧或简短并不意味着没有价值。
• 根据使用证据（§15），逐个确定 Skill 是模型可见还是仅限用户调用；绝不能仅凭其描述或安装位置判断。
• 保持冷门第三方资源处于已安装状态；仅隐藏其精确的发现路径，然后证明路由器仍能解析一个代表性能力。
• 通过可恢复的移动操作并附上文件／可执行文件／哈希清单来弃用，绝不要使用 rm -rf。
• 现有会话会保留启动时的元数据。重新启动后，才能将交互式目录视为验证结果。

源与激活的所有权

对于 Daymade 基于源的 Codex 激活流程，请使用当前的 claude-switch-models-setup dry-run/apply 工作流。其显式的 codex-active-skills.json 仅管理从声明的源 Marketplace 创建的链接。 不要在此处重新实现其冲突、符号链接或清理逻辑。

对于 Claude 插件，检查当前的 Marketplace 和安装 JSON，在原作用域通过官方 CLI 更新或重新安装，并单独读取回查结果。将缓存文件夹视为派生的运行时产物。

对于套件拓扑变更，使用 marketplace-dev 编辑源清单； 仅使用此 Skill 在当前主机上协调已完成的迁移。

只读交付契约审计

对于明确的交付审查，请阅读 §16 并运行 scripts/audit_skill_delivery.py <skill-path> --delivery-contract <private-contract.json> --json。 它会将源所有权委托给 skill-creator；运行时可见性和对原始需求的忠实度仍是独立证据。 即使 Skill 可以运行，源错误也会阻止交付。

完成定义

所有适用的声明都必须经过独立验证：

• 已明确指出权威来源和当前负责人；
• 在新建的提示词中，所选直接条目/路由器会根据请求的发现策略出现；另行报告描述截断情况，包括仅安装目标门禁通过时；
• 计划冷加载的条目不会出现在该目录中；
• 一项具有代表性的冷加载能力仍可解析并正常工作；
• 有来源依据的链接或 Claude 安装项读回后，具有预期的身份、来源/版本和作用范围；
• 任何已弃用的套件及其恢复清单仍然存在；
• 明确说明未解决的所有权问题、宿主版本行为或有意保留的例外。

仅当实际任务执行属于交付内容时，才使用参考中的任务行为检查；仅在目录中可见并不能证明任务执行结果。

到此为止。除非请求的结果仍缺少证据，否则不要新建钩子、清单、报告层或清理项目。