fix-plugin-paths 是一个面向插件技能(skill)与智能体(agent)文件的路径可移植性修复技能,其身份定位为“插件路径可移植性执行器”,用于审计、修复并持续改进技能与智能体文件中的路径引用,确保它们通过 npx skills add、插件安装器或 uvx 安装后仍能正常工作。
【核心规则】 技能被安装后,只有它自身的目录存在,结构为 .agents/skills/<skill-name>/,其中包含 SKILL.md、scripts/、assets/、references/。不存在 plugins/ 文件夹,不存在 CLAUDE_PLUGIN_ROOT,也不存在源码仓库结构。该规则同样适用于技能调用的 Python 脚本:脚本在运行时不得使用 PROJECT_ROOT / "plugins/other-plugin/..." 这类路径。跨插件的脚本引用必须使用 .agents/skills/<skill>/scripts/<script> 或自包含的副本。完整规则集位于 references/fix-plugin-paths.prompt.md。
【使用方式:阶段 0 信息收集】 如果用户指定了文件或目录,确认后继续;否则询问一个问题,涉及两方面:范围(单个文件 / 插件目录 / 整个仓库)与模式(A 单次审计,立即修复一个文件;B 仓库审计,生成任务跟踪器并修复所有被标记文件;C 会话内进化,在每次编辑后持续为 SKILL.md 评分)。如果上下文可推断出范围则自动检测;如果请求中已明确模式则跳过询问。
【阶段 1:审计文件】 对每个目标文件,使用审计脚本判断适用哪些规则:python ./scripts/audit_plugin_paths.py <directory-or-file>。审计脚本运行两轮:标准轮(支持白名单)—— 标记 .md 与 .py 文件中的 plugins/<name> 和 /Users/ 引用,误报可通过 scripts/plugin_paths_whitelist.json 抑制;CRITICAL 轮(不可白名单)—— 标记 .py 文件中使用 PROJECT_ROOT、ROOT、SCRIPT_DIR 或 Path(file) 构造指向 plugins/<name> 的运行时 Path() 路径,此类问题不可白名单,必须修复。对于 CRITICAL 违规,正确修复方式为以下之一:替换为相对路径 scripts/<script>.py(自包含、可移植);替换为 .agents/skills/<skill-name>/scripts/<script>.py(跨技能已安装引用);通过 uvx / subprocess 调用 GitHub 原生安装器(用于安装器引导)。如果标准轮标记的问题在功能上是必需的(如结构示意图或明确的文档引用),不要修改该文件,而应使用 Edit 工具更新 scripts/plugin_paths_whitelist.json,加入针对性模式消除误报,然后重新运行审计器确认其被干净跳过。
【阶段 2:应用修复】 使用 Edit 工具手动应用 references/fix-plugin-paths.prompt.md 中的每条规则。每次更改后用 diff 验证,确认差异正确后再应用。
【阶段 3:验证】 修复后重新运行审计器,确认没有残留的失效引用:python ./scripts/audit_plugin_paths.py <directory-or-file>。结果为零即表示干净。
【模式 B:任务跟踪器工作流(仓库级修复)】 仓库级修复遵循三步循环。第一步,生成任务跟踪器:运行 python ./scripts/audit_plugin_paths.py .,初始化 scripts/portability-audit-report.md 作为事实来源,该报告为每个文件带复选框,并逐条列出问题所在行。第二步,逐条处理:审计(读取报告定位下一个未勾选的违规项)、修复(手动对相应文件进行修正以消除引用)、白名单(若该项为结构上必需的路径,如 URL 或示意图树节点,则不修改源文件,而是在 scripts/plugin_paths_whitelist.json 中添加针对性全局正则或文件特定字符串模式以豁免)、重新生成并验证(重新运行审计器更新报告,确认问题从活动报告中消失)、重复(持续循环上述步骤,反复运行脚本、读取报告并修复或加白,直到所有问题处理完毕)。第三步,最终验证:仅当审计器返回完全干净的扫描结果(python ./scripts/audit_plugin_paths.py . 零结果)时循环才结束。
【模式 C:会话内直接进化协议】 用于在活跃会话中将本技能自身 SKILL.md 的进化作为后台线程运行。不使用工作树,不使用外部仓库,由智能体自身作为提议者。C.1 搭建评估(若缺失):检查 evals/evals.json 是否存在,若缺失则根据描述与 <example> 块起草 8 个 should_trigger: true 与 4 个 should_trigger: false 的用例,写入 evals/evals.json、evals/results.tsv(表头)和 references/program.md。C.2 建立基线:运行评估脚本并提交基线,继续主工作前报告基线分数。C.3 每次 SKILL.md 编辑后评分:每次修改后运行评估脚本,KEEP(退出码 0)则提交,DISCARD(退出码 1)则自动回退并尝试其他方式,内联报告分数变化。C.4 会话结束:完成后或用户说“stop”时,打印 evals/results.tsv 中的完整分数轨迹,若分数提升超过 0.05 则标记待回移审查。
【强制自评】 在完成完整仓库审计或重要的会话内进化批次后,记录:哪些文件最难分类(误报风险)、哪些规则违规最常见(用于未来评估)、任务跟踪器是否始终准确(是否有遗漏更新)、对 fix-plugin-paths.prompt.md 的哪一处改动能改善下次运行。写入 temp/retrospectives/audit_<YYYYMMDD>_fix-plugin-paths.md。
【操作原则】 一次只处理一个文件:绝不在单次编辑中批量修复多个文件。零容忍:直到 grep 确认零违规,文件才算“完成”。跟踪器保真:立即更新任务跟踪器,绝不追溯更新。全部评分:每次 SKILL.md 变更在提交前都须评分。严格严谨:误报(标记正确路径)与漏报同样有害。