Skill Optimizer

目标与边界

把 Skill 当成可执行产品，以一条可复核证据链完成诊断和优化：

权威源码 → 发行载荷 → Agent 安装入口/软链 → Agent 实际加载 → 真实任务

一个规则、资源和版本坐标只有一个主人；开发、发行、安装和运行职责分离。依赖允许存在，但必须说明用途、阶段、体积、引入路径和替代边界。优化不能删除必要的正确性、安全、权限、许可证、来源或用户入口。

每次只处理一个目标 Skill。范围外问题记录证据和建议，不擅自扩大修改面。

选择模式

• 用户说“审计、诊断、评估”时保持只读，只交付问题、影响、证据和建议。
• 用户说“优化、精简、修复”时先用通俗中文说明处理方向。已有明确授权且范围未变时直接实施，不重复确认；只有范围不清或新增高风险操作尚未获准时才询问。
• 只读审计不写文件；修改不得超出已授权范围，不自动删除候选文件或猜测软链目标。
• 目标用户、核心任务或输出合同需要改变时，说明这已是新 Skill，改用 skill-creator，不静默重建。

按改动范围选择流程

• 说明文字、排版、已明确的调用偏好：确认权威文件和受影响的安装入口，检查改动差异、引用及元数据格式；无需例行运行全量审计、重新打包或启动新 Agent。
• 提示词或工作流行为：检查规则冲突，用代表性输入推演预期分支；改动依赖模型实际表现时，再做真实调用验证。文字推演不能当作实际运行证据。
• 脚本、依赖、文件删除、安装或发行变化：读取相关判据，检查受影响的链路，运行相应测试；删除候选仍须满足生命周期判据中的完整确认链。
• 用户要求完整生命周期审计或全链路验收时，覆盖源码、发行、安装和真实调用；不要把这套流程强加给局部修改。

先读哪份规则

审计软链、发行 manifest、版本、死重或结构时，必须按需读取 生命周期审计判据。它定义证据图、引用入边、候选分类、结构矩阵、阻断级别和死重确认流程。

检查 Codex 或 RedSkill 的 frontmatter/目录政策时，再读取 平台 Schema Profile。平台推荐结构与通用正确性分开报告；RedSkill 的上传白名单、identifier、审核阈值和线上版本仍归 redskill-pack，不迁入本 Skill。

审计测试脚本膨胀、case-by-case、重复 runner 或测试结构时，必须读取 测试体系审计合同。测试语义归目标 Skill 的权威源码仓所有；本 Skill 只校验仓内声明、执行边界与文件覆盖，不靠通用正则替源仓决定哪些测试应该合并。

建立问题合同

先明确本次要解决的问题、权威修改位置、预期结果和验证方式。涉及发行或安装时，再核对谁维护、谁发布、谁安装、谁执行；故障诊断补充实际行为、最小复现和失败信号。

完整生命周期审计需分开核对以下项目；局部修改只检查受影响的项目：

• 权威源码及 Git HEAD/dirty；本地 upstream 不是实时远端，需要当前远端事实时才只读查询。
• 发行目录或压缩包、发行 manifest、source_commit 与文件哈希。
• 每个 Agent 的入口原路径、readlink 每一跳和最终 realpath。
• 安装副本是否为软链、共享目录或独立副本，内容是否漂移。
• Agent 是否真的加载该 Skill 并完成代表任务；静态解析成功不能冒充真实运行成功。

不通过目录名猜开发仓或发行仓。只有目标本身是显式 source、显式 --source，或发行 manifest 的可信关系能确立权威边。发现无关未提交改动时保留；与目标重叠且无法安全区分时暂停确认。

按需运行只读审计

结构、入口、发行、依赖或测试体系审计使用下列工具；纯文字调整不要求运行。

python3 <本 Skill 目录>/scripts/audit_skill.py <目标 Skill 目录> \
  --surface <auto|source|release|installed> \
  --profile <auto|general|review> \
  --schema-profile <auto|codex|redskill> \
  --source <权威源码 Skill 目录> \
  --release-manifest <发行 manifest 路径> \
  --agent-entry codex=<Codex 安装入口> \
  --agent-entry agents=<Agents 安装入口> \
  --supported-node-majors 22,24 \
  --metafile <esbuild metafile 路径> \
  --test-system-contract <源仓 test-system.json> \
  --format json

除目标目录外，其余参数按证据可用性提供：

• --surface auto 不确立发行或安装权威，因此不输出可删除候选。
• --profile auto 在 release 使用 review，其他载体使用 general。
• --schema-profile auto 保持 Codex 合同；只有显式目标为 RedSkill 时使用 redskill。
• --agent-entry 可重复；逐条解析，禁止依赖 shell 空格分词生成或修复软链。
• --supported-node-majors 由调用方按当前官方支持矩阵传入；审计器离线运行，不把内置值冒充实时事实。
• --test-system-contract 可显式指定源仓测试体系声明；相对路径按 Git 根解析，非 Git 目标按目标根解析。未提供时只发现标准仓内位置，不执行仓内测试命令。
• 未提供 metafile 时只查找常见文件名。未知 Skill 的 doctor/build/install 不自动执行，不联网、不安装依赖、不自动修改或删除内容。

审计结果在既有 findings/summary/surfaces/metrics 外增加：

• lifecycle：源码、发行、安装入口的节点、边和逐跳解析。
• version_coordinates：Git、manifest、文件哈希、frontmatter、安装副本分别记录。
• runtime_verification：只允许 not-run / passed / failed；静态审计固定为 not-run。
• reachability：功能、文档、发行、完整性、来源、法律入边和保守分类。
• test_system：源仓测试合同、机制、共享或独立 runner、case 所有权、未登记文件和边界检查；没有合同不做语义判定。
• structure：逐项规则、状态和证据；不输出含糊总分。

退出码保持兼容：0 表示没有确定性结构阻断，1 表示断链、循环、非法入口、哈希破坏或已采用测试合同的确定性违约，2 表示参数、路径或审计运行失败。缺少测试合同、候选、结构建议和平台政策警告不导致退出码 1。

形成系统性结论

沿生命周期证据图定位表面症状、直接原因、公共根因和促成条件，再枚举共享同一规则主人或失败机制的入口。以下结论不能互相替代：

• 在 Git 中保留，不等于进入发行包。
• 进入发行包，不等于模型会读取或运行会调用。
• 被 manifest 列出，不等于有功能用途。
• realpath 正确，不等于 Agent 已成功调用。
• Git SHA、frontmatter 语义版本和平台线上版本不是同一个版本数字。
• 静态零有效入边只产生 deadweight-candidate，不产生“已确认可删”。
• 测试文件多，不等于测试体系差；无源仓合同只能报告文件与入口事实，不能自动判断重复机制。

依赖按开发/测试、构建/CI、发布打包、用户运行时和可选能力分类。替代顺序是“系统原生能力 → 已有依赖 → 新增依赖”，但只有调用路径、功能等价和回归证据同时成立才建议替代；审计器不自动删除依赖。

出现以下任一情况，不得称为系统性修复：只补用户点名的一个入口；把开发仓直接当用户包；把测试、生成器、大文件或未读文档简单称为无用；仅凭 manifest、来源标签或文件名确认用途；用通用正则替源仓判断测试语义；借发行瘦身改变权威源码；用 fallback 掩盖错误合同；用结构审计或一次成功输出代替新 Agent 的真实任务。

先给人话方案

先说清哪个 Skill 有什么问题、准备怎么改、如何判断改好了。简单改动用几句话说明；复杂审计再补充原因、影响、保留内容和风险。

只报告本次相关的证据，先解释文件或技术名词的用途。不要默认输出整套版本坐标、平台矩阵、原始 JSON 或固定多栏模板。需要用户决定时，说清具体选择；已经授权时继续实施。

在授权范围内实施

1. 检查 Git 状态和目标路径，保留已有改动；涉及安装或发行时，再复核对应入口和发行证据。
2. 在唯一规则主人上做最小完整改动；同一根因散落多处时一次收敛，范围外保持不变。
3. 开发资产留在源码，发行包排除已证实的开发专用内容；保留优化前已有且仍有效的 README、LICENSE/NOTICE/署名、安装入口和用户示例，不为原本没有的自用 Skill 强造空壳。
4. 详细判据放进按需 reference，确定且重复的工作放进无额外运行依赖的脚本；Agent metadata 保持薄层，不复制业务合同。
5. 测试优化由目标源仓声明机制、唯一规则主人、共享 runner、case 数据和受治理例外；案例可以增长，但执行器和规则主人不能随案例线性增长。先迁移覆盖再移除旧入口，不把不同机制强塞进一个大脚本。
6. 任何死重删除先在隔离发行副本完成完整确认链；移除第三方内容时复核 LICENSE/NOTICE。用户确认前不修改权威源码。
7. 若需要修软链，逐条给出明确源、目标和预期 realpath，逐条执行、逐条复核；禁止批量猜路径。
8. 不默认 commit、push、发布、安装依赖或执行未知目标代码。

验证与停止标准

验证覆盖本次改变的行为和相关风险，不以检查数量作为完成标准。

• 文字与元数据：复核差异、引用和格式，确认必要的安装副本同步；已有的无关改动保持不变。
• 脚本与测试：运行覆盖受影响机制的检查；只有变更影响构建、安装或发行时才执行对应流程。未知目标代码、安装依赖和外部操作仍需符合授权边界。
• 安装与发行：核对入口实际指向；发行内容变化时，从临时干净发行包校验清单中的文件和哈希，并检查实际文件是否都被清单覆盖。
• 真实调用：工作流依赖实际模型行为、删除候选确认链或完整验收要求真实运行时，使用明确入口完成代表任务，记录输入、预期结果和实际输出。只有需要证明新会话加载或判据明确要求时，才使用新 Agent 会话。
• 多平台支持：只检查本次影响或明确要求的平台和 Agent；没有实测的组合不宣称已验证支持。

必要检查通过、没有未解决的相关疑点后停止；只有新增改动、失败或疑点才补充检查。清理本次不再需要的临时产物和辅助进程，保留用户验收所需的文件。

静态检查不能证明 Agent 已实际调用。未运行时保留 runtime_verification=not-run；可以交付已完成的局部修改，但不能称为真实调用已验证或全链路完成。若本次必需的真实验证无法执行，明确说明缺口。

交付

先说改好了什么、如何检查、结果怎样，再说明仍与本次任务有关的风险或未验证项。提供修改文件的绝对路径和必要的人工验收步骤；有提交、服务或待保留临时产物时再补充对应信息。

完整审计再附相关链路和平台验证状态；候选文件未经确认不得写成“可删”。只读审计明确说明“未改文件”。