/skill-ecosystem-doctor

name: skill-ecosystem-doctor
description: "Audit and safely repair cross-runtime Skill ownership, loading, duplication, scopes, budgets, lifecycle, quarantine, and retirement. Usage statistics alone belong to skill-usage-stats. Use when explicitly governing the Skill ecosystem; ignore mentions/traces."

Skill Ecosystem Doctor

Treat the local Skill collection as a governed software supply chain. Audit first, plan repairs from evidence, apply only authorized changes, and finish with fresh cross-runtime verification and a durable handoff.

This workflow is at `skill` maturity, not unattended `automation` maturity. Do not schedule or silently apply repairs.

Select the mode

| User intent | Mode | Routing | |---|---|---| | Inspect, review, inventory, or diagnose | `audit` | `execute_direct`; read-only | | Explain what should change | `plan` | `plan_first`; no mutations | | Fix, unify, quarantine, or retire | `repair` | `plan_first`; explicit scope and rollback | | Recheck an existing governance file | `verify` | `execute_direct`; read-only | | Rotate credentials, rewrite history, push, publish, or change remotes | external action | `clarify_first` unless the current request grants that exact action |

If the request mixes modes, run `audit` before `repair`. Do not infer repair authorization from a request to inspect or diagnose.

Operating Contract

• **Direct actions:** read-only discovery, deterministic audits, report drafts,

and local validation.

• **Escalate before:** destructive changes, credential actions, history

rewriting, remote publication, or any mutation not named by the current repair request.

• **Evidence-backed pushback:** challenge a proposed source, deletion, or

completion claim only with paths, state queries, tests, ownership records, or a concrete data-loss or security risk.

• **Feedback loop:** promote repeated false positives, runtime-layout changes,

and manual recovery steps into checks, fixtures, references, or evals.

1. Discover before creating

1. Search active roots and source repositories before creating a Skill, governance file, script, alias, or projection. 2. Locate every applicable `AGENTS.md` or equivalent before editing a source repository. 3. Read [runtime contracts](references/runtime-contracts.md) and classify each path as canonical source, managed projection, generated cache, or unknown. 4. Record the task goal, context, constraints, done-when conditions, dirty worktrees, runtime versions, and unavailable external permissions. 5. If work will span many files or sessions, use `flowguard` and keep the handoff outside parent context.

Common roots are discovery candidates, not declarations. Verify them on the current machine; no data means unknown, not a guessed source relationship.

2. Run the deterministic audit

Use an existing governance file when one exists. Otherwise read [the governance schema](references/governance-schema.md), adapt [the example](assets/skill-governance.example.json) from discovered facts, and show the proposed configuration before writing it.

The Doctor accepts both its portable schema and the deployed Loom-style `SKILL_GOVERNANCE_POLICY.json`; do not create a second policy when the latter already exists.

For a large deployed catalog, prefer `default_scope: "review"` with an explicit `global_allowlist`. Keep specialist Skills in named `profiles`, bind profiles to project roots only when needed, and enforce an `exposure_budget`. A retained profile Skill is still canonical and usable on demand; it is not globally injected until a declared profile scope projects it.

From this Skill directory, run:

python3 scripts/ecosystem_doctor.py --governance ./skill-ecosystem-governance.json
python3 scripts/ecosystem_doctor.py --governance ./skill-ecosystem-governance.json --json

Use `--skip-loom` only when Loom is intentionally outside scope. A missing Loom binary is an error when Loom validation is requested. Use `--fail-on-warn` for a strict release gate.

For the deployed policy, run the exposure reconciler without `--apply` first:

python3 scripts/ecosystem_reconcile.py \
  --registry ~/.loom-registry \
  --policy ~/.loom-registry/SKILL_GOVERNANCE_POLICY.json

The dry-run reports trigger hardening, global/project/profile/review exposure, catalog budgets, plugin-state changes, and stale registry state. Run the same command with `--apply` only during an explicitly authorized `repair` run. Plugin configuration receives a timestamped backup before its exact boolean values are changed. Re-run the dry-run afterward and require an empty plan.

If the policy declares exact progressive-disclosure splits, inspect them with:

python3 scripts/ecosystem_split.py \
  --registry ~/.loom-registry \
  --policy ~/.loom-registry/SKILL_GOVERNANCE_POLICY.json

Use `--apply` only after reviewing the extracted headings and destinations.

The audit checks:

• broken roots, links, and local support-file references
• source directories that look like Skills but have no `SKILL.md`
• declared-name versus directory-name mismatches
• divergent active projections for the same declared name
• dynamic project/worktree projections and additional declared source roots
• physical runtime copies without an exact source pin
• drift in pinned composite materializations
• active retired, quarantined, or projection-denied Skills
• active references to retired entry points
• high-confidence secret-like literals without printing their values
• missing per-Skill governance decisions when decision coverage is enabled
• review-by-default coverage, named profile bindings, and global catalog budgets
• declared enabled/disabled plugin state without rewriting unrelated TOML
• Loom health, projection drift, and pending remote synchronization

When the request concerns Skills that stopped triggering, aged out, or depend on possibly dead external projects, also read [lifecycle drift](references/lifecycle-