Skill Audit 指南

spec-skill-audit 把 skills 当作工程协议审查，而不是只检查 prompt 文案。它先收集确定性事实，再由 LLM 判断这些事实对质量、治理和维护风险意味着什么。

入口

场景	Claude Code	Codex
审查全部 source skills	/spec:skill-audit	$spec-skill-audit
审查单个 skill	/spec:skill-audit skills/spec-debug	$spec-skill-audit skills/spec-debug
包含 runtime drift	/spec:skill-audit --runtime	$spec-skill-audit --runtime
生成 patch preview	/spec:skill-audit --patch-preview	$spec-skill-audit --patch-preview

也可以直接运行脚本：

node skills/spec-skill-audit/scripts/write-audit-artifacts.js --repo .
node skills/spec-skill-audit/scripts/write-audit-artifacts.js --repo . --target skills/spec-debug
node skills/spec-skill-audit/scripts/write-audit-artifacts.js --repo . --runtime --patch-preview

执行逻辑图

用户运行 /spec:skill-audit 或 $spec-skill-audit
  |
  v
读取 skills/、agents/、templates/、dual-host governance contract、runtime copies
  |
  v
脚本生成 source inventory、runtime drift、promise implementation、安全信号
  |
  v
LLM 从 trigger、scope、I/O contract、governance、safety、maintainability 审查风险
  |
  v
输出 scorecard、finding report、security report、improvement plan
  |
  +-- 只读审计
  |     |
  |     v
  |   停在 .spec-first/audits/skill-audit/latest/*
  |
  +-- 用户明确要求修复
        |
        v
      修改 source truth：skills/、agents/、templates/ 或 src/cli/contracts/
        |
        v
      用 spec-first init 重建 generated runtime copies

审查什么

维度	说明
Source inventory	skills/<name>/SKILL.md、脚本、references、assets 和 eval 组织
Trigger precision	触发条件是否清晰，是否容易误路由
Scope boundary	何时使用、何时不使用、是否跨 workflow 越权
Input/output contract	输入、输出、失败模式和产物路径是否明确
Runtime governance	dual-host governance、Claude/Codex delivery 和 generated runtime drift
Safety signals	remote script、secret access、destructive command、runtime hand-edit 等风险
Promise implementation	文档承诺、CLI 参数和脚本实际写出产物是否一致

输出产物

审计结果写入：

.spec-first/audits/skill-audit/latest/

常见文件：

文件	作用
skill-source-inventory.json	source skill inventory 和结构事实
skill-audit-report.json	P0/P1/P2/P3 finding 聚合
expert-scorecard.json	多维评分信号，作为 review signal 而非 gate
security-risk-report.json	安全风险信号
promise-implementation-report.json	文档承诺与实现一致性信号
governance-drift-report.json	source skills 与治理契约漂移
runtime-drift-report.json	generated runtime 缺失或漂移
skill-audit-summary.md	面向维护者的摘要入口
skill-improvement-plan.md	按风险分层的改进计划

.spec-first/audits/ 是 gitignored execution artifact，不是 source truth。

修复边界

默认审计是只读的。它可以写 .spec-first/audits/skill-audit/ 报告，但不应直接修改：

• skills/
• agents/
• templates/
• src/cli/contracts/
• .claude/
• .codex/
• .agents/skills/

如果发现 runtime drift，修复方式是重新运行 spec-first init --claude 或 spec-first init --codex，不是手改 generated runtime copies。

什么时候不该用

• 安装第三方 skills。
• 创建新 skill。
• 一般代码审查。
• 审查远程 marketplace 或 GitHub skill 包。
• 自动重写 source skills，除非用户明确要求应用某个具体修复。