name: plugin-audit

description: |

Comprehensive audit pipeline for skills, plugins, agents, and commands. Validates structure,

quality, security, marketplace compliance, cross-platform compatibility, and ecosystem integration.

Runs all built-in validation tools, invokes domain-appropriate agents for code review,

and produces a pass/fail gate report. Usage: /plugin-audit <skill-path>

argument-hint: "<skill-path>"

/plugin-audit

Full audit pipeline for any skill, plugin, agent, or command in this repository. Runs 8 validation phases, auto-fixes what it can, and only stops for user input on critical decisions (breaking changes, new dependencies).

Usage

/plugin-audit product-team/code-to-prd
/plugin-audit engineering/agenthub
/plugin-audit engineering-team/playwright-pro

What It Does

Execute all 8 phases sequentially. Stop on critical failures. Auto-fix non-critical issues. Report results at the end.

Phase 1: Discovery

Identify what the skill contains and classify it.

1. Verify {skill_path} exists and contains SKILL.md
2. Read SKILL.md frontmatter — extract name, description, Category, Tier
3. Detect skill type:

• Has scripts/ → has Python tools
• Has references/ → has reference docs
• Has assets/ → has templates/samples
• Has expected_outputs/ → has test fixtures
• Has agents/ → has embedded agents
• Has skills/ → has sub-skills (compound skill)
• Has .claude-plugin/plugin.json → is a standalone plugin
• Has settings.json → has command registrations

1. Detect domain from path: engineering/, product-team/, marketing-skill/, etc.
2. Check for associated command: search commands/ for a .md file matching the skill name

Display discovery summary before proceeding:

Auditing: code-to-prd
  Domain: product-team
  Type: STANDARD skill with standalone plugin
  Scripts: 2 | References: 2 | Assets: 1 | Expected outputs: 3
  Command: /code-to-prd (found)
  Plugin: .claude-plugin/plugin.json (found)

Phase 2: Structure Validation

Run the skill-tester validator.

python3 engineering/skills/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json

Parse the JSON output. Extract:

• Overall score and compliance level
• Failed checks (list each)
• Errors and warnings

Gate rule: Score must be ≥ 75 (GOOD). If below 75:

• Read the errors list
• Auto-fix what's possible:
• Missing frontmatter fields → add them from SKILL.md content
• Missing sections → add stub headings
• Missing directories → create empty ones with a note
• Re-run after fixes. If still below 75, report as FAIL and continue to collect remaining results.

Phase 3: Quality Scoring

Run the quality scorer.

python3 engineering/skills/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json

Parse the JSON output. Extract:

• Overall score and letter grade
• Per-dimension scores (Documentation, Code Quality, Completeness, Usability)
• Improvement roadmap items

Gate rule: Score must be ≥ 60 (C). If below 60, report the improvement roadmap items as action items.

Phase 4: Script Testing

If the skill has scripts/ with .py files, run the script tester.

python3 engineering/skills/skill-tester/scripts/script_tester.py {skill_path} --json --verbose

Parse the JSON output. For each script, extract:

• Pass/Partial/Fail status
• Individual test results

Gate rule: All scripts must PASS. Any FAIL is a blocker. PARTIAL triggers a warning.

Auto-fix: If a script fails the --help test, check if it has argparse — if not, this is a real issue. If it fails the stdlib-only test, flag the import and ask the user whether the dependency is acceptable (this is a critical decision).

Phase 5: Security Audit

Run the skill security auditor.

python3 engineering/skills/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json

Parse the JSON output. Extract:

• Verdict (PASS/WARN/FAIL)
• Critical findings (must be zero)
• High findings (must be zero in strict mode)
• Info findings (advisory only)

Gate rule: Zero CRITICAL findings. Zero HIGH findings. Any CRITICAL or HIGH is a blocker — report the exact file, line, pattern, and recommended fix.

Do NOT auto-fix security issues. Report them and let the user decide.

Phase 6: Marketplace & Plugin Compliance

6a. plugin.json Validation

If {skill_path}/.claude-plugin/plugin.json exists:

1. Parse as JSON — must be valid
2. Verify only allowed fields: name, description, version, author, homepage, repository, license, skills
3. Version must match repo version (2.1.2)
4. skills must be "./"
5. name must match the skill directory name

Auto-fix: If version is wrong, update it. If extra fields exist, remove them.

6b. settings.json Validation

If {skill_path}/settings.json exists:

1. Parse as