/auditing

name: auditing
description: "Use when reviewing a bundle-plugin for structural issues, version drift, skill quality, workflow integration, or security risks — before releasing, after changes, or after adding skills. Auto-detects scope (full project vs skill vs workflow)"
allowed-tools: Bash(bundles-forge audit-skill *) Bash(bundles-forge audit-security *) Bash(bundles-forge audit-docs *) Bash(bundles-forge audit-plugin *) Bash(bundles-forge audit-workflow *) Bash(bundles-forge checklists *) Bash(bundles-forge bump-version *) Bash(python *bundles-forge *)

Auditing Bundle-Plugins

Overview

Systematically evaluate a bundle-plugin project or a single skill across applicable quality categories — including security scanning — score each, and produce a diagnostic report. This skill is a pure diagnostic tool: it identifies and reports issues but does not orchestrate fixes.

**Core principle:** Measure and report. A scored audit gives orchestrating skills (blueprinting, optimizing, releasing) the information they need to decide what to fix. When sources contradict, apply the authority hierarchy in `references/source-of-truth-policy.md`.

**This skill includes security scanning.** No need to invoke a separate security skill — see Category 10 under Full Project Audit.

**Announce at start:** "I'm using the auditing skill to audit [this project / this skill]."

**Plugin context:** When installed as a plugin, operate on the user's project (`$CLAUDE_PROJECT_DIR` / `<target-dir>`), not the plugin's own cache. Read files from and detect scope in the target; write all outputs (reports, JSON baselines) to the workspace's `.bundles-forge/audits/`. See `references/input-normalization.md` for edge-case input types, naming conventions, and security rules. `<plugin-root>` in commands below resolves to `$CLAUDE_PLUGIN_ROOT` (Claude Code), `$CURSOR_PLUGIN_ROOT` (Cursor), or `.` (local development).

Resolve Input & Detect Scope

The target can be a local path, a GitHub URL, or a zip file. Normalize to a local directory, then detect scope. This applies to all three audit modes.

Input Normalization

**This is a mandatory step — do not skip it or improvise paths.** Resolve the target to a local directory before proceeding to Scope Detection or any audit Step 1.

1. **Resolve the workspace.** The workspace is `$CLAUDE_PROJECT_DIR` or `$CURSOR_PROJECT_DIR` (plugin mode), falling back to the current working directory. 2. **Normalize the target by type:**

• **Local path** — use directly; no transformation needed.
• **GitHub URL** — parse `<owner>` and `<repo>` from the URL. Shallow-clone to `<workspace>/.bundles-forge/repos/<owner>__<repo>/` using `--depth 1 --no-checkout`, then run `git checkout`. If the directory already exists, append a `__<YYYYMMDD>` timestamp to avoid collisions. **Do not clone to `/tmp/`, `~/`, or any path outside `.bundles-forge/repos/`.**
• **Zip/tar.gz** — extract to `<workspace>/.bundles-forge/repos/<archive-name>/`.

3. **Create the target subdirectory** if it does not exist. 4. **On failure** (network error, 404, auth required, rate limit): tell the user what failed and suggest providing a local path or zip file instead. Do not silently skip or proceed with partial data.

See `references/input-normalization.md` for the full naming convention (version/timestamp suffixes), GitHub subdirectory URLs, and security rules.

Scope Detection

After normalization, determine the audit scope from the resolved local path:

| Target | How to Detect | Mode | |--------|--------------|------| | Project root | Has `skills/` directory | **Full audit** — all 10 categories | | Project root + workflow request | User explicitly requests workflow audit, or specifies `--focus-skills` | **Workflow audit** — 3-layer workflow checks (W1-W11) | | Single skill directory | Contains `SKILL.md` but no `skills/` subdirectory | **Skill audit** — 4 applicable categories | | Single SKILL.md file | Path ends in `SKILL.md` | **Skill audit** — 4 applicable categories |

**If the target is a single skill, skip to the Skill Audit section below.** **If a workflow audit is requested, skip to the Workflow Audit section below.**

---

Full Project Audit

`audit-plugin` orchestrates `audit-security` (security), `audit-skill` (skill quality), `audit-workflow` (workflow integration), and `audit-docs` (documentation consistency D1-D9), then adds structure, manifest, version-sync, hook, and testing checks.

**Categories at a glance** (see `references/plugin-checklist.md` for 60+ individual checks):

| Category | Weight | |----------|--------| | Structure | High | | Platform Manifests | Medium | | Version Sync | High | | Skill Quality | Medium | | Cross-References | Medium | | Workflow | High | | Hooks | Medium | | Testing | Medium | | Documentation | Low | | Security | High |

**Security Scan (Category 10):** Scans 7 attack surfaces. See `references/security-checklist.md` for the full pattern list. `security-checklist.md` is the canonical source; the table below is a quick-reference summary.

| Target | Risk Level | |--------|-----------| | SKILL.md content | High | | Hook scripts | High | | Hook configs (HTTP hooks) | High | | OpenCode plugins | High | | Agent prompts | Medium | | Bundled scripts | Medium | | MCP configs | Medium |

Step 1 — Run Script Baseline

**Prerequisites:** Target directory resolved to a local path (via Input Normalization above) with a `skills/` directory (Full audit scope confirmed).

**Action:**

bundles-forge audit-plugin --json --output-dir .bundles-forge/audits <target-dir>

This collects the deterministic baseline — structure, manifests, version sync, skill quality, cross-references, hooks, documentation, and security patterns are verified with reproducible results regardless of agent behavior.

**Expected Output:** A JSON baseline file at `.bundles-forge/audits/audit_plugin-<YYYYMMDD-HHmmss>.json`. Verify the file exists and is valid JSON before proceedin