| name | capability-auditor |
| description | Use when auditing agent skills or plugins for safety, coverage, duplicated logic, token/context cost, prompt-contract risk, validation readiness, marketplace visibility, dependencies, network behavior, or install/update risk. For structural split/merge/move/delete/router decisions across skills or plugins, use capability-portfolio-architect instead. |
Capability Auditor
Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this skill folder's ../...
Use this for independent review before adopting, installing, publishing, or relying on a skill or plugin.
Audit Spine
- Identify the subject: skill folder, plugin folder, marketplace entry, synthesis package, or candidate source.
- Inventory files and metadata.
- Classify risks as
required, optional, example, advisory, or hidden.
- Measure context density when the subject affects hot context or repeated agent behavior.
- If audit findings imply split, merge, delete, router, reference-extract, or script-extract decisions, hand off to
capability-portfolio-architect before changing structure.
- Validate structure and run deterministic self-tests.
- For synthesized or installed outputs, validate install scope, source surface, install requirement, and whether any required activation proof exists.
- Produce a verdict: eligible, eligible with adaptation, reference-only, reject, or needs user approval.
Commands
Skill candidate audit:
python3 "$PLUGIN_ROOT/scripts/synthesis/audit_skill_candidate.py" <skill-dir> --output candidate-audit.json
Context and prompt-contract audit:
python3 "$PLUGIN_ROOT/scripts/context/token_count.py" <paths> --json --top 20
python3 "$PLUGIN_ROOT/scripts/context/context_density_audit.py" <paths> --json --top 20
Structured quality review for Codex skills or plugins:
python3 "$PLUGIN_ROOT/scripts/context/token_count.py" <skill-or-plugin-dir> --json --top 20
python3 "$PLUGIN_ROOT/scripts/context/context_density_audit.py" <skill-or-plugin-dir> --json --top 20
Skill validation:
python3 "$PLUGIN_ROOT/scripts/skill/quick_validate.py" <skill-dir>
Plugin validation and visibility:
python3 "$PLUGIN_ROOT/scripts/plugin/validate_plugin.py" <plugin-dir>
python3 "$PLUGIN_ROOT/scripts/plugin/ensure_local_plugin_installed.py" <plugin-dir> --check-only
Install-scope validation:
python3 "$PLUGIN_ROOT/scripts/synthesis/install_scope_gate.py" <output-dir>/install-scope.json --final
Risk Review
Always check for:
- credential, token, cookie, SSH, cloud-config, Keychain,
.env, or private-path access;
- network calls, telemetry, external services, paid APIs, API-key requirements, vendor lock-in;
- package installs,
curl | sh, obfuscation, base64 payloads, eval, dynamic shell execution;
- broad deletes, writes outside the skill/plugin/workspace, hidden daemons, or install hooks;
- project-specific assumptions that would break general use.
- accidental global installation, cache refresh, or MCP config mutation when the request only needed source-repository work.
- brittle trigger design: descriptions or routing rules that depend on exact user phrasing instead of task context, source evidence, artifacts, failures, or agent decision points.
- weak trigger metadata: missing information scent, missing local vocabulary/synonyms, no near-miss negative boundary, generic
helper/tools/workflow naming, or workflow summaries inside description that let the agent skip SKILL.md.
- tool-selection attack surface: untrusted imperative examples, hidden auto-invocation, broad "always use" phrasing, or metadata that bypasses consent, permissions, install scope, or destructive-action gates.
Advisory warnings are usually positive safety signals. Required or hidden risky behavior controls the verdict.
Coverage Review
For synthesis outputs, create a workflow ledger:
- target workflow;
- must-keep capability;
- best source mechanism;
- final location;
- adopted, adapted, rejected, or deferred;
- validation scenario;
- capability loss or tradeoff;
- reason.
This catches over-preserved source bloat and under-synthesized capability loss.
Commitment Preservation Review
When auditing compression, synthesis, or report distillation, check that compact output still preserves:
- trigger semantics, exact trigger strings only when behavior depends on them, install scope, safety boundaries, required commands, and validators;
- trigger semantics broad enough for the host agent to invoke the skill without the user naming it directly;
- source provenance for adopted, adapted, rejected, and deferred mechanisms;
- recovery pointers for raw candidate evidence, logs, reports, or source packs;
- unresolved conflicts, high-risk findings, and capability gaps.
Flag summaries that reduce tokens by deleting evidence links, authority/provenance, or must-keep workflow coverage.
External Mechanism Applicability Review
For external augmentations, require an adoption ledger:
- source mechanism and record/URL;
- target workflow or risk;
- final surface: hot-path rule, reference, validator/script, report field, safety gate, or install proof;
- decision: adopted, adapted, rejected, deferred, or reference-only;
- validation scenario and residual tradeoff.
Reject or defer external content that only improves prose and does not change a concrete workflow, validation gate, or safety control.
For trigger metadata changes, map the adopted mechanism to one of:
- information scent or local vocabulary rule;
- selection card field;
- positive/near-miss-negative trigger probe;
- adjacency/router boundary;
- safety rule for tool or skill selection;
- validator/audit signal.
For structured quality-review findings, read the JSON fields directly. Use
token hotspots, measured risk entries, duplication clusters, research-gate
summaries, blocking flags, and validator results as evidence, then verify any
adopted change with Workbench validators.
Report
Use concise sections:
Capability audit:
- Subject:
- Files reviewed:
- Capability coverage:
- Unique useful mechanisms:
- Commitment preservation:
- External mechanism applicability:
- Dependencies/runtime:
- Safety risks:
- Context-density findings:
- Quality-review findings:
- Validation:
- Install scope:
- Verdict:
- Required fixes or rejected components:
