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 |
scripts/ecosystem_split.py
View on GitHub#!/usr/bin/env python3
"""Move exact SKILL.md sections into references using governance policy."""
from __future__ import annotations
import argparse
import json
import os
from dataclasses import dataclass
from pathlib import Path
class SplitError(RuntimeError):
"""Raised when a split boundary or destination is unsafe."""
@dataclass(frozen=True)
class SplitPlan:
skills: tuple[str, ...]
references: tuple[str, ...]
final_lines: dict[str, int]
def to_dict(self) -> dict:
return {
"skills": list(self.skills),
"references": list(self.references),
"final_lines": self.final_lines,
}
def _load_policy(path: Path) -> dict:
try:
value = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise SplitError(f"policy does not exist: {path}") from exc
except OSError as exc:
raise SplitError(f"policy cannot be read: {path}: {exc}") from exc
except json.JSONDecodeError as exc:
raise SplitError(f"invalid JSON in {path}: {exc}") from exc
if not isinstance(value, dict):
raise SplitError(f"{path} must contain a JSON object")
return value
def _line_index(lines: list[str], heading: str, start: int = 0) -> int | None:
return next((index for index in range(start, len(lines)) if lines[index] == heading), None)
def _skill_source(registry: Path, skill: str) -> Path:
relative = Path(skill)
if (
relative.is_absolute()
or len(relative.parts) != 1
or relative.name != skill
or relative.name in {".", ".."}
):
raise SplitError(f"split skill name must be one directory segment: {skill!r}")
source = registry / "skills" / relative / "SKILL.md"
if not source.is_file():
raise SplitError(f"missing split source: {source}")
skills_root = (registry / "skills").resolve(strict=True)
skill_root = source.parent.resolve(strict=True)
if source.parent.is_symlink() or skill_root.parent != skills_root:
raise SplitError(f"split source must be a physical registry Skill: {source}")
return skill_root / "SKILL.md"
def _reference_path(source: Path, reference_name: str) -> Path:
relative = Path(reference_name)
if not relative.parts or relative.is_absolute() or ".." in relative.parts:
raise SplitError(
"split reference must stay inside its Skill directory: "
f"{reference_name!r}"
)
skill_root = source.parent.resolve(strict=True)
reference = (skill_root / relative).resolve(strict=False)
if not reference.is_relative_to(skill_root):
raise SplitError(
"split reference must stay inside its Skill directory: "
f"{reference_name!r}"
)
return reference
def build_split_plan(
registry: Path,
policy: dict,
*,
max_lines: int = 800,
) -> tuple[SplitPlan, dict[Path, str]]:
raw_splits = policy.get("splits", {})
if not isinstance(raw_splits, dict):
raise SplitError("splits must be an object")
updates: dict[Path, str] = {}
changed_skills: list[str] = []
references: list[str] = []
final_lines: dict[str, int] = {}
for skill, moves in raw_splits.items():
if not isinstance(skill, str) or not isinstance(moves, list):
raise SplitError("splits must map skill names to move arrays")
source = _skill_source(registry, skill)
original = source.read_text(encoding="utf-8")
text = original
for move in moves:
if not isinstance(move, dict):
raise SplitError(f"invalid move for {skill}")
start_heading = move.get("start")
end_heading = move.get("end")
reference_name = move.get("reference")
title = move.get("title")
intro = move.get("intro")
replacement = move.get("replacement")
required = (start_heading, reference_name, title, intro, replacement)
if not all(isinstance(value, str) and value for value in required):
raise SplitError(f"incomplete split move for {skill}")
if end_heading is not None and not isinstance(end_heading, str):
raise SplitError(f"invalid end heading for {skill}: {start_heading}")
if start_heading in replacement.splitlines():
raise SplitError(
f"replacement repeats the start heading for {skill}: {start_heading}"
)
reference = _reference_path(source, reference_name)
lines = text.splitlines()
start_index = _line_index(lines, start_heading)
if start_index is None:
if reference.is_file() and replacement in text:
continue
raise SplitError(f"start heading not found in {source}: {start_heading}")
end_index = len(lines)
if end_heading is not None:
found = _line_index(lines, end_heading, start_index + 1)
if found is None:
raise SplitError(f"end heading not found in {source}: {end_heading}")
end_index = found
if reference.exists() or reference in updates:
raise SplitError(f"refusing to overwrite split reference: {reference}")
extracted = "\n".join(lines[start_index:end_index]).rstrip() + "\n"
reference_text = f"# {title}\n\n{intro}\n\n{extracted}"
lines[start_index:end_index] = replacement.splitlines()
text = "\n".join(lines).rstrip() + "\n"
updates[reference] = reference_text
references.append(str(reference))
count = len(text.splitlines())
final_lines[skill] = count
if count > max_lines:
raise SplitError(f"{source} would remain over {max_lines} lines ({count})")
if text != original:
updates[source] = text
changed_skills.append(skill)
return (
SplitPlan(
skills=tuple(changed_skills),
references=tuple(references),
final_lines=final_lines,
),
updates,
)
def _atomic_write(path: Path, text: str, mode: int) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_name(f".{path.name}.split-{os.getpid()}")
try:
temporary.write_text(text, encoding="utf-8")
os.chmod(temporary, mode)
os.replace(temporary, path)
except OSError:
temporary.unlink(missing_ok=True)
raise
def apply_split_plan(registry: Path, updates: dict[Path, str]) -> None:
skills_root = (registry / "skills").resolve(strict=True)
for path, text in sorted(
updates.items(), key=lambda item: len(item[0].parts), reverse=True
):
try:
relative = path.relative_to(skills_root)
except ValueError as exc:
raise SplitError(f"split target escaped the registry: {path}") from exc
if len(relative.parts) < 2:
raise SplitError(f"invalid split target: {path}")
skill_root_path = skills_root / relative.parts[0]
if skill_root_path.is_symlink():
raise SplitError(f"split target uses a symlinked Skill root: {path}")
skill_root = skill_root_path.resolve(strict=True)
resolved_path = path.resolve(strict=False)
if not resolved_path.is_relative_to(skill_root):
raise SplitError(f"split target escaped its Skill directory: {path}")
source_mode = (skill_root / "SKILL.md").stat().st_mode
_atomic_write(resolved_path, text, source_mode)
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--registry", type=Path, required=True)
parser.add_argument("--policy", type=Path, required=True)
parser.add_argument("--max-lines", type=int, default=800)
parser.add_argument("--apply", action="store_true")
args = parser.parse_args()
registry = args.registry.expanduser().resolve()
try:
policy = _load_policy(args.policy.expanduser().resolve())
plan, updates = build_split_plan(registry, policy, max_lines=args.max_lines)
if args.apply:
apply_split_plan(registry, updates)
except (OSError, SplitError) as exc:
print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
return 2
print(
json.dumps(
{"ok": True, "applied": args.apply, **plan.to_dict()},
ensure_ascii=False,
indent=2,
)
)
return 0
if __name__ == "__main__":
raise SystemExit(main())
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 |