majiayu000/spellbook / skills/skill-ecosystem-doctor
skill-ecosystem-doctor
VerifiedAudit and safely repair cross-runtime Skill governance: canonical-source ownership, divergent or duplicate projections, exposure scopes and budgets, lifecycle drift, quarantine, and retirement. Use when the user explicitly requests cross-runtime or cross-scope Skill governance; ignore project-local Skill inventory, product/runtime loading or enablement checks, usage statistics, and mentions/traces.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.8 KB |
| agents/openai.yaml | config | 354 B |
| assets/remediation-log-template.md | markdown | 1.1 KB |
| assets/skill-governance.example.json | config | 1.2 KB |
| evals/evals.json | config | 5.1 KB |
| references/governance-schema.md | markdown | 9.4 KB |
| references/lifecycle-drift.md | markdown | 2.1 KB |
| references/remediation-playbook.md | markdown | 3.7 KB |
| references/runtime-contracts.md | markdown | 4.3 KB |
| requirements.txt | manifest | 7 B |
| scripts/ecosystem_checks.py | script | 14.1 KB |
| scripts/ecosystem_doctor.pyexecutable | script | 2.1 KB |
| scripts/ecosystem_exposure.py | script | 7.3 KB |
| scripts/ecosystem_governance.py | script | 11.9 KB |
| scripts/ecosystem_legacy.py | script | 11.8 KB |
| scripts/ecosystem_model.py | script | 8.6 KB |
| scripts/ecosystem_plugins.py | script | 2.6 KB |
| scripts/ecosystem_reconcile.py | script | 34.7 KB |
| scripts/ecosystem_runtimes.py | script | 4.6 KB |
| scripts/ecosystem_scans.py | script | 25.3 KB |
| scripts/ecosystem_split.py | script | 8.5 KB |
references/runtime-contracts.md
View on GitHub# Runtime and ownership contracts
Use these as discovery hints, then verify actual paths, links, Git history, and
installer behavior on the current machine.
## Ownership classes
| Class | Evidence | Default treatment |
|---|---|---|
| Independent Git source | `.git`, remote or explicit local ownership, source tests | Canonical when ownership is verified. Edit in a clean worktree. |
| Local registry source | Registry metadata plus tracked Skill directory | Canonical for local-only Skills. |
| Managed projection | Symlink, copy record, lock, or installer manifest | Regenerate from source; do not edit directly. |
| Generated/plugin cache | Package-manager or plugin-owned path | Read-only evidence; change the upstream package or plugin. |
| Unknown physical copy | No source record or exact pin | Warn, preserve, and resolve ownership before mutation. |
## Common discovery candidates
- Codex: the current user Skill root is `~/.agents/skills`; `~/.codex` remains
the configuration home and `~/.codex/skills` is a legacy projection path.
- Claude Code: the active user or project Skill roots, commonly
`~/.claude/skills`.
- Gemini CLI: commonly `~/.gemini/skills`.
- Cursor: commonly `~/.cursor/skills`.
The governed runtime ids and their home directories are defined once, in
`scripts/ecosystem_model.py::RUNTIME_HOME_DIRS`. The same mapping supplies each
runtime's per-project projection directory (`<project>/<dir>/skills`), its
`--<runtime>-home` CLI override, and its Loom target id. Add a runtime there and
nowhere else.
During migration, reconciliation recognizes both the current Codex Loom target
id (`target_codex_agents_skills`) and the retired
`target_codex_codex_skills` id so stale mirror rules and projections are removed.
A policy projects into `codex` and `claude` unless it sets
`projection_runtimes`; `managed_global_sources[].runtimes` may name any governed
runtime independently of that list. Plugin enablement stays Codex-only because
it edits Codex's `config.toml`.
An explicit empty `projection_runtimes` list disables automatic projections;
leave `managed_global_sources` empty too for a zero-link contract. In that
mode, declare active physical roots such as `~/.agents/skills` as
`managed_projection` inventory roots. The reconciler may still validate
classification, frontmatter, state, and plugin policy, but it must not create
global or project links. Remove obsolete Loom bindings and projection records
through Loom's own commands; never satisfy their drift by recreating links.
- Loom: its configured workspace, commonly `~/.loom-registry`, plus registered
targets, bindings, projections, provenance locks, and `workspace doctor`.
- VibeGuard: installed snapshot, source revision, manifest, rules, workflows,
and install verification command.
- Spellbook: Git source under `skills/`, generated registry files, installer,
and runtime symlinks.
- Plugin bundles: cache directories exposed by the runtime. Treat them as
package-owned unless the plugin contract says otherwise.
Never assume that a common candidate exists or is active. Use runtime commands,
link resolution, registry records, and fresh state queries.
## Source precedence
1. Prefer a verified independent Git source over a copied local directory.
2. Prefer an explicit local registry record over an untracked runtime copy.
3. Treat an exact pinned materialization as a projection, not a second source.
4. Treat equal names with different digests as unresolved until ownership and
tests identify the intended source.
5. Keep restricted, expired, or unreviewed third-party content retained but
unprojected when reuse rights or runtime behavior are uncertain.
## Repository boundaries
- Read every applicable high-context instruction file before editing.
- Preserve dirty user work; do not stage or commit unrelated files.
- Use the repository's own generator for registry, lock, or manifest output.
- Run source-specific tests before replacing runtime projections.
- Commit or push only when the current request grants that exact action and any
repository review gate is satisfied.
## Handoff fields
Record at least:
```yaml
handoff:
mode: plan_first
objective:
artifacts: []
runtime_snapshot:
writable_paths: []
verification_owner:
stop_conditions: []
external_actions: []
```
Blank means unknown or not applicable. Do not fill it with a plausible guess.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |