跳到主要内容
AI教程

Skill Sunset 教程：审计并安全精简 AI Agent 规则

用确定性检查、行为实验与回滚机制治理陈旧 AI 指令

AI我搜编辑部阅读约 11 分钟

Skill Sunset 是什么

随着 AI 模型、开发工具和项目结构不断变化，过去为了弥补模型能力或工具限制而添加的规则，可能已经失效，却仍然占用上下文。Skill Sunset 是一个本地 CLI，用于审计长期积累的 AGENTS.md、CLAUDE.md 和通用 SKILL.md。

它会将能够确定的问题与需要实验验证的行为假设分开处理。核心审计只读运行，不调用 AI API、不消耗模型额度，也不读取模型提供商凭据。

审计发现不等于删除授权。尤其是 TEST 标签，只表示“应该验证这个假设”，不表示规则已经过时。

由仓库测试样本真实生成的 Skill Sunset 报告

上图报告由 CLI 扫描仓库测试样本真实生成。该样本扫描了 5 个文件并产生 11 条发现，将重复退役、失效引用更新、渐进披露和行为假设分别展示。

核心功能与支持范围

可以发现哪些问题

  • 失效的本地引用和已经陈旧的绝对路径。
  • 损坏的 Skill frontmatter。
  • 过大的常驻指令文件，以及适合下沉到渐进披露引用的细节。
  • 疑似明文凭据。
  • 同名 Skill 和完整重复的 Skill bundle。
  • 与工具、版本或模型时代相关的补偿规则。

对模型行为的判断采取保守策略。诸如“所有任务都必须调用某个工具”的规则会被标记为 TEST，而不是被直接认定为无效。自动退役范围还会排除领域知识、安全规则、授权门槛和项目不变量。

报告与交接材料

一次审计可以生成英文和简体中文 HTML、Markdown、JSON、Codex 与 Claude Code 交接 Prompt、评估计划、实验模板以及回滚清单。用户主目录下的路径会脱敏为 $HOME/...，其他绝对目标会以 $ABSOLUTE/<名称> 的形式显示。

运行环境

  • Node.js 20、22 和 24 已经过验证。
  • Ubuntu、macOS 和 Windows 已纳入 GitHub Actions 测试矩阵。
  • 预设支持 Codex 的 ~/.codex 和 Claude Code 的 ~/.claude。
  • 也可以审计显式传给命令的任意有边界目录。

其他 Linux 发行版在 Node.js 20 或更高版本下预期可用，但尚未进入当前 CI 矩阵。

安装与首次运行

Skill Sunset 不要求全局安装。确认本机使用受支持的 Node.js 版本后，直接通过 npx 调用最新版本即可。

扫描 Codex 配置

npx skill-sunset@latest audit --codex --open

--codex 选择 Codex 预设目录，--open 会在报告生成后打开结果。

扫描 Claude Code 配置

npx skill-sunset@latest audit --claude --open

扫描自定义目录

npx skill-sunset@latest audit /path/to/setup --format json --fail-on high

这个例子将结果输出为适合 CI 消费的 JSON，并利用严重度退出条件处理高严重度发现。传入自定义位置时，应选择边界清晰的目录，避免无意扩大扫描范围。

设置报告语言

CLI 默认使用 --lang auto。也可以通过以下参数指定主要报告语言：

npx skill-sunset@latest audit . --lang zh-CN
npx skill-sunset@latest audit . --lang en

无论主要语言如何设置，每个报告包仍会包含英文和简体中文 HTML。

理解审计结果标签

  • MERGE：完整重复或存在同名冲突的 Skill。
  • UPDATE：失效路径、引用、工具或与版本耦合的指令。
  • DEMOTE：内容仍然有用，但不适合常驻上下文，应转入渐进披露引用。
  • RETIRE：同一扫描根中名称相同且完整 bundle 字节一致的通用 Skill；工具只建议进行可恢复归档。
  • TEST：可能过时的行为假设，清理前必须进行新旧配置对照验证。

这些标签是治理建议，不是自动修改指令。特别是 RETIRE，只有在同一扫描根内核对完整 bundle 且字节一致时，才会给出保守的可恢复退役建议。

完整实践：从发现问题到安全回滚

第一步：准备输入并创建快照

假设项目的 AGENTS.md 含有以下规则和引用：

Always use Context7 for every task.
[Deployment runbook](docs/deploy.md)

但实际目录中并不存在 docs/deploy.md。修改前先创建可恢复副本，然后执行审计：

cp AGENTS.md AGENTS.md.skill-sunset.bak
npx skill-sunset@latest audit . --out .skill-sunset --open

第二步：阅读发现

针对这个输入，报告可能给出以下结果：

  • UPDATE / broken-reference：部署文档目标无法解析。
  • UPDATE / context7-assumption：需要核验当前运行时是否提供 Context7。
  • TEST / unconditional-tooling：“每个任务都调用”属于需要新旧配置对照验证的无条件工具规则。

失效引用属于可以通过文件系统核对的确定性问题，而工具使用策略会影响 Agent 行为，因此不能仅凭静态扫描直接删除。

第三步：修改并重新验证

先确认真实文档路径和当前工具列表，只修复已经证实失效的引用。将无条件工具规则作为独立候选，随后重新运行审计和项目测试：

npx skill-sunset@latest audit . --out .skill-sunset --format json
npm test

对于 TEST 项，填写生成的实验模板，然后先执行不运行命令的验证：

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root .

默认模式只进行验证。若确实要执行清单中的命令，必须显式添加 --run：

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root . --run

实验通过只表示清单中编码的验收条件通过，并不能自动证明所有真实任务都不会退化。

第四步：出现退化时回滚

如果引用、测试或实际任务行为发生退化，恢复备份并再次审计：

cp AGENTS.md.skill-sunset.bak AGENTS.md
npx skill-sunset@latest audit . --out .skill-sunset

生成的 rollback-manifest.json 默认保持为空。只有获得授权的执行 Agent 才应写入真实改动和哈希。

检查生成的报告包

默认输出目录包含以下文件：

.skill-sunset/
├── index.html
├── index.en.html
├── index.zh-CN.html
├── audit-report.md
├── audit.json
├── execution-prompt-codex.md
├── execution-prompt-claude.md
├── eval-plan.md
├── experiment-template.json
└── rollback-manifest.json
  • index.html 是主要 HTML 入口。
  • audit-report.md 和 audit.json 分别适合人工阅读与自动化处理。
  • 两个 execution Prompt 用于向 Codex 或 Claude Code 交接后续工作。
  • experiment-template.json 用于描述待验证的行为实验。
  • rollback-manifest.json 用于在授权执行后记录可回滚改动。

高级用法与安全建议

接入 CI

在持续集成中，使用 JSON 格式和严重度退出条件更便于自动处理：

npx skill-sunset@latest audit ./agent-config --format json --fail-on high

项目当前已经实现 CI 严重度退出码，可据此阻止高严重度问题被忽略，但仍应由维护者判断具体发现是否需要修改。

谨慎执行行为实验

实验命令不经过 shell，并且默认只继承最小的不含凭据环境变量。若可信命令确实需要完整环境，可以在 --run 之外显式添加 --inherit-env：

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root . --run --inherit-env

完整环境可能包含模型提供商凭据，因此只能对可信命令使用该选项，也不要把任何凭据写进实验清单。

预检和结果文件仅保留可执行文件名、参数数量、命令哈希、输出大小与输出哈希，不保存命令参数或输出正文。

不要把凭据检测当作绝对保证

项目在 GitHub Actions 中运行 Gitleaks，并包含完整的操作系统与 Node.js 版本矩阵。Gitleaks 是发布防线，但不能证明世界上所有凭据格式都能被识别。发现疑似凭据后仍应进行人工核验，并遵循项目自身的密钥轮换流程。

本地开发与验证

如果要参与项目开发或验证仓库样本，可以运行：

npm test
npm pack --dry-run
node ./bin/skill-sunset.js audit ./test/fixtures/sample-setup --out ./demo-report --open

更多项目资料可查看 CHANGELOG、CONTRIBUTING 和 SECURITY。

当前边界

版本 0.2.0 已实现静态检查、保守重复退役、双语报告、路径脱敏、带执行门槛的命令实验框架、CI 严重度退出码和对抗性输出测试。当前提供商能力快照、使用量适配器和任务质量适配器仍属于后续证据层，不能把它们视为现有功能。

结语

Skill Sunset 的价值不在于自动删除旧规则，而在于建立一条可审计的治理路径：先扫描并分类，再核验确定性问题，对行为假设进行受控实验，最后保留明确的回滚能力。对于长期维护 Codex、Claude Code 或自定义 Agent 配置的团队，这种保守流程可以在减少上下文负担的同时，避免误删安全规则、领域知识和项目不变量。