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/governance-schema.md
View on GitHub# Governance schema
Use one machine- or workspace-specific JSON document as the declared input to
the deterministic validator. Keep facts in the document and workflow rules in
`SKILL.md`.
## Required fields
| Field | Type | Meaning |
|---|---|---|
| `schema_version` | integer | Must be `1`. |
| `source_policy` | object | Canonical local registry, active projections, and additional inventory roots. |
| `source_policy.local_only_canonical_registry` | string | Registry root that contains a `skills/` directory. `~` is expanded. |
| `source_policy.projection_roots` | string array | Existing runtime directories to audit. Include only in-scope roots. |
| `projection_runtimes` | string array | Optional (legacy schema). Runtimes receiving automatic global/project projections, from `codex`, `claude`, `gemini`, `cursor`. Defaults to `["codex", "claude"]`; Codex resolves to `.agents/skills`, not the legacy `.codex/skills` path. Set it explicitly to `[]` to disable automatic links; `managed_global_sources` remain explicit per-Skill exceptions. Drives `projection_roots` and the per-project `<dir>/skills` globs. |
| `source_policy.projection_globs` | string array | Optional absolute path patterns for dynamic project/worktree projection roots. A pattern matching nothing is an error. |
| `source_policy.inventory_roots` | object array | Additional roots with explicit `path`, `kind`, and `owner`. |
| `source_policy.managed_physical_skills` | object | Exact physical runtime Skills mapped to the installer or source owner that manages them. |
## Optional governance fields
| Field | Meaning |
|---|---|
| `retired_skills` | Entry points that must not exist or be referenced in active Skills. |
| `quarantined_skills` | Sources that may remain stored but must not be projected. |
| `projection_denials` | Named policy records whose `projection` is `deny`. |
| `pinned_materializations` | Physical runtime copies verified against an exact source. |
| `retired_reference_allowlist` | Narrow `(skill, retired_name)` exceptions for non-invocation text. |
| `external_actions` | Account, remote, history, or review actions outside local proof. |
| `skill_decisions` | One evidence-backed decision per discovered name; when present, incomplete coverage is an error. |
Arrays default to empty. Do not invent a value to make validation pass.
Unknown top-level or `source_policy` fields are errors so misspelled safety
controls cannot silently become no-ops.
## Existing Loom-style policy
`ecosystem_doctor.py` also accepts an existing
`SKILL_GOVERNANCE_POLICY.json` containing trigger boundaries, project scopes,
worktree globs, cold storage, retired names, runtime mirrors, managed global
sources, and split declarations. It normalizes that document in memory for
auditing; it does not rewrite or migrate the file.
Legacy policy may also declare top-level `inventory_roots` using the same
`path`/`kind`/`owner` objects as `source_policy.inventory_roots`. Use this with
`projection_runtimes: []` to audit a package-managed physical catalog such as
`~/.agents/skills` without turning it into a symlink destination. Leave
`managed_global_sources` empty as well when the required plan is zero-link.
Deployed exposure fields are:
| Field | Meaning |
|---|---|
| `default_scope` | `global` for backward compatibility or `review` for explicit exposure. |
| `global_allowlist` | Canonical registry Skills allowed in every managed runtime. |
| `profiles` | Named, mutually exclusive groups retained for on-demand or project use. |
| `profile_scopes` | Exact project roots mapped to profile names. |
| `profile_scope_globs` | Dynamic project/worktree globs mapped to profile names. |
| `exposure_budget` | Maximum managed-global Skill count and description characters after planned trigger hardening or overrides. |
| `plugin_states` | Exact configured plugin IDs mapped to enabled booleans. |
| `evidence_policy` | Read-only evidence controls such as the bulk-audit threshold. |
Every canonical registry Skill must resolve to one class: global, project,
profile, cold, review, or hidden. Profile names may not overlap. With
`default_scope: "review"`, undeclared Skills stay retained but unprojected.
Reconciliation removes matching project links for explicit `retired` or
`quarantined` skills within the currently declared `projection_runtimes`.
Ordinary scope changes do not prove historical root-skill ownership: even a
link to a canonical source can have been created by the user. Those project
links are preserved, including links at empty bindings. Links in removed or
never-governed runtimes are also preserved, for both project and global homes.
After changing scopes or shrinking `projection_runtimes`, inspect the old links
and confirm ownership manually before removing them. The reconcile plan does
not claim or delete them automatically. Unexpected links and physical files at
a requested projection location cause a conflict and are preserved.
Standard `compatibility` environment text is portable frontmatter: a non-empty
string of at most 500 characters. Legacy `compatibility` mappings still require
an explicit per-Skill `frontmatter_extension_exceptions` entry. Other unknown
frontmatter keys also remain subject to that exception policy.
Use `ecosystem_reconcile.py` for dry-run/apply exposure changes and
`ecosystem_split.py` for declared progressive-disclosure moves. These commands
consume the same policy, so do not create a second machine policy carrying
competing scope or retirement decisions.
## Additional inventory roots
Each root requires a path, a role, and the component responsible for it:
```json
{
"path": "~/src/spellbook/skills",
"kind": "canonical_source",
"owner": "spellbook"
}
```
Supported `kind` values are:
- `canonical_source`: a writable source collection; every visible child
directory must contain a usable `SKILL.md`
- `repository_source`: an independent repository whose root `SKILL.md` is a
Skill and whose immediate child directories may also contain Skills; the root
entry point is required and unrelated repository directories are ignored
- `managed_projection`: active runtime content owned by a package manager or
runtime; physical copies do not require local source pins
- `managed_cache`: inactive package cache retained for provenance and conflict
discovery
- `archive`: inactive recovery or evidence collection; archives are scanned
recursively because dated recovery layouts add container directories, but
archived content is never treated as active
Do not list the canonical Loom `skills/` path or a normal projection twice.
Managed roles document ownership; they do not authorize editing package caches.
## Per-Skill decisions
Each `skill_decisions` record requires `name`, `decision`, `reason`, and
`owner`:
```json
{
"name": "example-skill",
"decision": "keep",
"reason": "Distinct capability with a maintained source and passing checks.",
"owner": "spellbook",
"canonical_path": "~/src/spellbook/skills/example-skill",
"evidence": ["source review", "fresh validator run"]
}
```
Allowed decisions are `keep`, `repair`, `merge`, `quarantine`, `retire`,
`managed`, and `archive`. Optional `target` and string-array `evidence` fields
record the chosen source and proof. Use `canonical_path` when reviewed same-name
source variants intentionally coexist. The validator requires that path to
match a discovered instance; a verified declaration turns inactive divergence
into an informational finding, while divergent active projections remain an
error. Unknown ownership must be recorded as unresolved rather than guessed.
## Pinned materializations
Each item requires:
```json
{
"name": "example-skill",
"path": "~/.agents/skills/example-skill",
"source_path": "~/src/example/skills/example-skill",
"reason": "Installed by a source-controlled generator."
}
```
For composite installers, add exact file mappings:
```json
{
"name": "queue-skill",
"path": "~/.agents/skills/queue-skill",
"source_path": "~/src/example/skills/queue-skill",
"reason": "Skill plus a locked shared resource.",
"resource_mappings": [
{
"source_path": "~/src/example/integrations/shared.md",
"destination_path": "references/shared.md"
}
]
}
```
`destination_path` must be relative and remain inside the materialization.
Duplicate destinations, self-sources, missing source files, or digest drift are
errors.
`source_path` may identify either a directory Skill or a canonical
`skills/<name>.SKILL.md` file Skill. File sources materialize as `SKILL.md` in
the pinned runtime directory.
## Projection denials
Use denials for sources that may be retained for evidence but cannot be active:
```json
{
"name": "experimental-skill",
"status": "expired_experimental",
"projection": "deny",
"reason": "Access contract and redistribution rights are not current."
}
```
Keep reasons factual. A denial does not authorize deleting the retained source.
## Path rules
- Use discovered paths, not copied machine assumptions.
- Prefer `~` to embedding a username when the path is user-relative.
- Add only roots that should be required for this run; configured missing roots
are errors.
- Declare plugin caches as `managed_cache` and package-manager runtime roots as
`managed_projection`; keep both outside writable source policy.
- Use `projection_globs` for repeated project worktrees instead of copying a
changing list of roots. Globs are expanded without a shell and every match is
scanned as an active managed projection.
- Never put credentials or credential values in the governance document.
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 |