Marketplace Health Check

Run a comprehensive, evidence-based health check of this Claude Code skills marketplace repo using a parallel fan-out Dynamic Workflow. Use independent inspectors to cover these dimensions in parallel:

1. Code & script safety — dangerous deletes, NO-FALLBACK secret leaks, hardcoded real paths, bare except, injection, missing shebangs
2. Documentation / SSOT consistency — authoritative documentation checks, release-policy consistency, broken references, derived-value drift
3. Security / PII — keyword-free leaks gitleaks can't catch (real names, private domains), generic secret scans, case-file audits
4. Open-PR triage — classify every PR (worth-merging / needs-changes / decline-as-promotion)
5. Open-issue triage — real bugs vs skill-requests vs promotion, plus the broken-install-command bug class
6. Marketplace-manifest integrity — check_marketplace.sh + check_doc_skill_lists.py, orphans, suite registration

Then YOU verify the serious findings and report by priority. Use the bundled script (scripts/repo-health-check.workflow.js) for orchestration; this file is how to run and interpret it.

Why a workflow — and why it MUST run inline

The dimensions are independent, so fanning them out across parallel agents is far faster than one agent sweeping serially, and each inspector stays focused on one concern with its own structured output.

Use the script's explicit maximum task budget and its runtime refusal before fan-out. Review usage cost before adding an inspector or changing that budget; do not derive the limit from the current dimension list.

This skill must run inline (no context: fork). It orchestrates parallel agents through the Workflow tool, and a forked subagent cannot spawn subagents or launch a workflow — running it forked would silently break the fan-out. The Workflow tool also requires explicit user opt-in; a user asking to "run the health check" IS that opt-in, so proceed.

How to run

Step 1 — Scout the current scale and share the result with all inspectors

The workflow script takes an args object so all agents share one accurate snapshot instead of each re-discovering it. Gather:

Resolve this Skill's installed/source directory to <health-skill-dir>, confirm the selected repository root, and run:

python3 "<health-skill-dir>/scripts/scout_repository.py" --repo "<owner/name>" --root "<repo-root>"

Read the helper's JSON and exit status; its --help owns the output/exit contract. It parses manifest metadata as JSON and follows the github-ops GraphQL pagination recipe for PRs and issues, reconciling unique items with server totals. Preserve the complete output outside the source tree so inspectors can read it; include its exact path and a concise scope summary in scale. Pass the helper's absolute path there too when inspectors cannot resolve the installed bundle. A failed inventory retains partial items as not_checked; never report those items as ALL or a failed request as zero. A later inspector may complete that exact missing inventory with the same helper and use the newly validated result.

Confirm identity.isPrivate: false before applying public-publication PII judgments. If visibility is unavailable, keep that judgment unknown; if the target is private, apply its actual privacy boundary. Do not change accounts, permissions or global settings to make a scout appear ready.

Step 2 — Launch the workflow

Read the bundled script and launch it inline via the script parameter (pass its contents, so there's no dependency on where the skill is installed):

Workflow({
  script: <full contents of scripts/repo-health-check.workflow.js>,
  args: { repo: "<owner/name>", scale: "<one-line summary from Step 1>" }
})

Tell the user this launches parallel model work and consumes the current plan's usage; do not quote a fixed time/token estimate as a guarantee. Keep the host's actual permission gate. Before editing the saved script, load Claude Code's /workflow-authoring bundled Skill when available; consult the official Workflow contract for host prerequisites and script limits.

Distinguish launch from completion: an initial error means the run did not produce an audit; async_launched only confirms startup. Wait for that run's final completion event and inspect its returned report. On failure, cancellation or unavailable Workflow tooling, report the audit as unfinished with the missing prerequisite; do not turn a launch receipt or scout into a completed audit.

The final payload is { complete, checks: [...] }. Preserve one row per expected dimension with dimension, status (checked / not_checked), the existing health, summary, findings[] and stats fields. complete means all dimension reports completed, including reports of critical defects; it does not mean the repository is healthy. A missing, failed or invalid inspector becomes an empty not_checked placeholder with health: needs-attention. For a schema-valid partial report, retain its findings and statistics with the same conservative health value; explain that overall repository health remains undetermined. Incomplete coverage does not retract observed findings: counter-review and report them by severity as usual.

While it runs you can do other useful prep, but don't start editing files the inspectors are reading.

Step 3 — Counter-Review the serious findings BEFORE reporting

Agent findings are HYPOTHESES, not conclusions. Never relay them verbatim. For every high/critical finding, verify it yourself with a quick command — grep the leaked value, sed -n the broken line, gh repo view the claimed state — confirming it's (a) real, (b) located where the agent says, and (c) not over-reach. This catches false alarms AND, just as important, agent recommendations that are actively wrong. (In the session this skill was distilled from, a security inspector recommended adding the real private domains into the public .gitleaks.toml — an anti-target move that had to be rejected; see the methodology reference.)

Filter every finding through these questions: probability (does it really happen?), cost (fix vs ignore), real scenario (does it bite in practice?), verifiable (can a 1-line command confirm or refute it?).

Report format

Lead with the table, then layer by priority. Classify — don't dump:

• One-line verdict + a dimension table with status, health and scope; keep every expected row. For not_checked, lead with “not checked”, name the missing evidence and recovery action, and avoid an overall healthy verdict
• 🔴 Must-fix — each VERIFIED high/critical, with exact location + a concrete fix
• 🟠 Backlog — PR/issue triage outcomes and incomplete checks (decisions, often outward-facing — flag that they affect external contributors)
• 🟢 Optional — low/info nits, one line each
• 💡 Key insights — the meta-findings worth surfacing (a structural blind spot in tooling, a recurring bug class)

Tag each surfaced item ✅ real / ⚠️ partly / ❌ false-alarm. Most raw agent output is noise; your job is to surface the real risks the owner didn't already know, not to forward raw findings for them to sift.

Judgment principles

Apply these when interpreting findings and proposing fixes. Full reasoning + the real failure cases behind each are in references/health-check-methodology.md — read it before acting on PII or PR/issue findings.

• Anti-target: never "fix" a PII leak by listing the real value in a public allowlist (e.g. the repo's own .gitleaks.toml) — a public list enumerating real assets is itself a leak. Sanitize the value in place; detection rules for real private values belong in the owner's private global guard, not in this public repo.
• History note: sanitizing the working copy cleans the current version, but a pre-existing leak still sits in git history. Flag the history exposure honestly; a history rewrite (force-push) is a separate high-risk decision that affects every fork — never do it unprompted.
• Public scan evidence: follow the methodology reference for marker interpretation and isolated scans. Run generic checks plus semantic sample reads; missing local receipts or optional private asset rules do not establish an unscanned/unsafe public package.
• Release and contribution decisions: read the current release owner and CONTRIBUTING.md. Use their change classification, registered plugin identity and maintainer follow-up rules; do not invent a member version or require every contributor to do maintainer bookkeeping. External PR merges require the human owner's decision.
• Promotion is declined by default: third-party directory / tool / marketplace promotion PRs and issues are declined — the repo is a personal curated marketplace, not an ecosystem directory. The decline-policy template is a reference doc at the repo root (outside this skill's bundle).

Bundled resources

• scripts/repo-health-check.workflow.js — the parallel inspection Dynamic Workflow. Run it via the Workflow tool's script param (Step 2). Edit it when you add/retire an inspector dimension.
• scripts/scout_repository.py — the read-only JSON scout; use its --help for arguments and exit semantics.
• references/health-check-methodology.md — Counter-Review, privacy, isolated scan handling, and contribution-policy interpretation.
• tests/test_health_check.py — deterministic scout and Workflow-body contract tests; run with python3 -m unittest discover -s "<health-skill-dir>/tests" -v. These do not replace native Workflow execution or model judgment.

Next step

Deliver the read-only report, including unresolved coverage. Continue fixes only within the user's existing authorization; obtain any missing authorization for repository writes, external comments, third-party merges or history rewrites. An audit request alone does not authorize those actions.