Agent plugin audit

Agent 插件安全审计

何时使用

• 在把一个技能 / 插件 / Agent / 命令合入主干或上架插件市场前，要跑一次端到端发布闸门，一次覆盖结构、质量、脚本、安全、市场合规、生态集成、代码评审。
• 想要可重复、可进 CI 的「准入/拒绝」判定，并自动修掉非关键问题、只在关键决策（破坏性变更、引入新依赖）上停下来问人。

不该用的边界：

• 只想做纯安全静态扫描（危险模式、提示注入、供应链）时，用更聚焦的 agent-skill-security-scanner，不必跑全 8 阶段。
• 不做运行时沙箱 / 动态执行，也不联网实时核验 CVE；安全阶段用的是内置静态规则。
• 强依赖本仓自带的校验脚本（skill_validator.py / quality_scorer.py / script_tester.py / skill_security_auditor.py）；脱离该工具链时按下方「指令」中的等价判据手工执行。

步骤

按顺序跑 8 个阶段，遇关键失败即停，非关键问题自动修复，最后出报告。

1. 发现（Discovery）：确认 {skill_path} 存在且含 SKILL.md；读 frontmatter 取 name/description/Category/Tier；探测子目录（scripts/→有脚本、references/→有参考、assets/→有模板、agents/→内嵌 Agent、skills/→复合技能、.claude-plugin/plugin.json→独立插件）；从路径推断 domain；在 commands/ 找同名命令。先打印发现摘要再继续。
2. 结构校验（Structure）：跑 skill_validator.py，取总分与合规级、失败检查项。闸门：分数 ≥ 75。低于则自动补全（缺字段→从正文补、缺小节→补桩标题、缺目录→建空目录加说明），重跑；仍 < 75 记 FAIL 但继续收集后续结果。
3. 质量评分（Quality）：跑 quality_scorer.py，取总分/等级、四维分（文档/代码质量/完整度/可用性）、改进路线项。闸门：分数 ≥ 60；低于则把路线项列为行动项。
4. 脚本测试（Scripts）：有 scripts/*.py 才跑 script_tester.py。闸门：所有脚本必须 PASS，任何 FAIL 即阻断，PARTIAL 触发警告。自动修：--help 失败查是否缺 argparse；若 stdlib-only 失败，标出该 import 并询问用户是否接受该依赖（关键决策）。
5. 安全审计（Security）：跑 skill_security_auditor.py --strict，取裁决（PASS/WARN/FAIL）、CRITICAL/HIGH/INFO 发现。闸门：CRITICAL 与 HIGH 均须为 0，任一即阻断（报出文件、行号、模式、修复建议）。安全问题不自动修，报告后交用户决定。
6. 市场与插件合规（Marketplace）：校验 plugin.json（仅允许 name/description/version/author/homepage/repository/license/skills 字段、版本须与仓库版本一致、skills 取约定值、name 与目录名一致）；校验 settings.json 中 commands 是否都有对应文件；核对 marketplace.json 条目与父域 plugin.json 的技能计数。自动修：更新陈旧计数、修版本不一致、删多余字段。
7. 生态集成（Ecosystem）：核对跨平台索引（如 .codex/ .gemini/ 索引）含本技能，缺则重跑同步脚本；校验关联命令的 YAML frontmatter、引用路径与文档导航；校验内嵌 Agent 的 frontmatter 与相对路径；核对 SKILL.md 中对其他技能的引用是否真实存在。自动修：补缺的导航/索引条目。
8. 领域化代码评审（Code Review）：按 domain 选对应 Agent 视角（如 engineering/→cs-senior-engineer、product-team/→cs-product-manager、其它→cs-senior-engineer），用其评审标准检查工作流可执行性、脚本正确性、参考准确性、模板可用性、无死链、署名齐全。这是借用 Agent 的书面视角组织评审，并非派生子 Agent。

指令

# 用法
/plugin-audit <skill-path>

# 各阶段核心命令（路径相对仓库根；{skill_path} 为待审目标）
python3 engineering/skill-tester/scripts/skill_validator.py {skill_path} --tier {tier} --json     # 阶段2 结构
python3 engineering/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json          # 阶段3 质量
python3 engineering/skill-tester/scripts/script_tester.py {skill_path} --json --verbose             # 阶段4 脚本
python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json   # 阶段5 安全

裁决逻辑：

条件	裁决
全部阶段通过	PASS —— 可合并/发布
仅有警告、无阻断	带警告 PASS —— 合并前先看警告
任一阶段有阻断	FAIL —— 列出阻断点与修复指引

阻断项（任一即 FAIL）：结构分 < 75；质量分 < 60；任一脚本 FAIL；任一 CRITICAL/HIGH 安全发现；plugin.json 无效或含非法字段；版本与仓库不一致。

非阻断（仅警告）：质量分在 60–75；脚本 PARTIAL；某平台索引缺失（自动修）；缺导航条目（自动修）；安全 INFO 发现。

示例

最终报告（结构示意）：

PLUGIN AUDIT REPORT: {skill_name}
  Phase 1 — Discovery     OK  {type}, {domain}
  Phase 2 — Structure     OK  {score}/100 ({level})    # 闸门 ≥75
  Phase 3 — Quality       OK  {score}/100 ({grade})    # 闸门 ≥60
  Phase 4 — Scripts       OK  {n}/{n} PASS
  Phase 5 — Security      OK  PASS (0 critical, 0 high)
  Phase 6 — Marketplace   OK  plugin.json valid
  Phase 7 — Ecosystem     OK  Codex + Gemini synced
  Phase 8 — Code Review   OK  {domain} review passed
  VERDICT: PASS — 可合并/发布
  Auto-fixes: {n}   Warnings: {n}   Action items: {n}

注意事项

• 阶段顺序固定，但关键失败即停：脚本非 stdlib-only 依赖、安全 CRITICAL/HIGH 都属关键决策，必须停下问人或交人裁决，不可静默放行。
• 安全发现绝不自动修——只报告（文件/行号/模式/建议），由人决定整改方式；其余非关键项（缺字段、陈旧计数、缺索引/导航）可自动修后重校。
• plugin.json 的 version 必须与当前仓库版本一致，且字段白名单严格；多余字段一律删除。
• 本条是全量发布闸门，与纯安全扫描 agent-skill-security-scanner 分工：前者覆盖结构/质量/脚本/合规/生态/评审 6 个非安全维度，后者把安全静态扫描做深；两者可串联（先安全扫描排雷，再跑全量闸门定准入）。

互见

• related：agent-skill-security-scanner —— 安装前纯安全静态扫描，本条第 5 阶段的深化与替代选项。
• related：agentic-actions-auditor —— 审计 Agent 实际可执行动作的越权与副作用，补足代码评审视角。
• related：dependency-auditor —— 依赖供应链与已知漏洞深度核验，承接脚本/合规阶段的依赖发现。
• combines_with：false-positive-check —— 复核安全阶段发现，过滤误报后再给最终裁决。

本条采编自 alirezarezvani/claude-skills（MIT）。