/plugin-audit

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

4. Detect domain from path: `engineering/`, `product-team/`, `marketing-skill/`, etc. 5. 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 JSON — must be valid 2. Version must match repo version 3. If `commands` field exists, verify each command has a matching file in `commands/`

6c. Marketplace Entry

Check if the skill has an entry in `.claude-plugin/marketplace.json`:

1. Search the `plugins` array for an entry with `source` matching `./` + skill path 2. If found: verify `version`, `name`, and that `source` path exists 3. If not found: check if the skill's domain bundle (e.g., `product-skills`) would include it via its `source` path

6d. Domain plugin.json

Check the parent domain's `.claude-plugin/plugin.json`:

• Verify the skill count in the description matches reality
• Verify version matches repo version

**Auto-fix:** Update stale counts. Fix version mismatches.

---

Phase 7: Ecosystem Integration

7a. Cross-Platform Sync

Verify the skill appears in platform indexes:

grep -l "{skill_name}" .codex/skills-index.json .gemini/skills-index.json

If missing from either index:

pytho