KhurrumMahmood /check-ecosystem-consistency
Audit whether the skill ecosystem still agrees with itself after a material change.
This skill exists because new skills create coordination obligations:
the skill may need catalogue coverage, count updates, tests, and
possibly a /which-shape registry update. Not every new skill belongs
in a shape, but every new skill should be consciously reviewed against
the shape registry.
How success is judged
- The script exit code is honored. If
.claude/skills/check-ecosystem-consistency/scripts/check.pyexits nonzero, report the failure and do not call the ecosystem consistent. report.md,state.json,findings.json, andevidence.jsonare written underreports/check-ecosystem-consistency/scan-<UTC>/(previous-state.jsonis included when a baseline exists).- Every
findings.jsonrow is relayed complete in the user-facing findings table:pattern,severity,file,summary, andrecommendation. --update-stateis run only after the findings have been reviewed and any needed catalogue or/which-shapeupdates have landed.
Forms
/check-ecosystem-consistency
/check-ecosystem-consistency --changed-from main
/check-ecosystem-consistency --staged
/check-ecosystem-consistency --update-state
Script form:
.venv/bin/python .claude/skills/check-ecosystem-consistency/scripts/check.py
Execution contract:
| Form | Script command | Contract |
|---|---|---|
/check-ecosystem-consistency |
.venv/bin/python .claude/skills/check-ecosystem-consistency/scripts/check.py |
Snapshot the full ecosystem, compare to .claude/ecosystem/last-state.json, and write a timestamped report |
/check-ecosystem-consistency --changed-from REF |
.venv/bin/python .claude/skills/check-ecosystem-consistency/scripts/check.py --changed-from REF |
Include git diff --name-only REF paths in report.md; the ecosystem snapshot is still full, not limited to those paths |
/check-ecosystem-consistency --staged |
.venv/bin/python .claude/skills/check-ecosystem-consistency/scripts/check.py --staged |
Include staged git diff --name-only --cached paths in report.md; the ecosystem snapshot is still full |
/check-ecosystem-consistency --update-state |
.venv/bin/python .claude/skills/check-ecosystem-consistency/scripts/check.py --update-state |
Write .claude/ecosystem/last-state.json only after the preceding report's findings were reviewed and required follow-up landed |
What It Checks
- skill inventory and frontmatter snapshot;
- added, removed, or changed skills since the last reviewed state;
/which-shape/shapes.jsonschema and referenced skill slugs;- new skills that should be reviewed for shape-router impact;
- README/ONBOARDING skill-count claims;
- new skills missing obvious
.claude/docs/skill-catalog.mdcoverage.
State And Reports
Reports are written under:
reports/check-ecosystem-consistency/scan-<UTC>/
The scan contains report.md, state.json, previous-state.json when
available, findings.json, and evidence.json.
The durable baseline lives at:
.claude/ecosystem/last-state.json
The script reads that state by default, but it only writes it when
--update-state is passed. Use --update-state after the consistency
findings have been reviewed and any needed catalogue or /which-shape
updates have landed.
When things go sideways
| Symptom | Action |
|---|---|
--changed-from REF names a bad git ref and Changed Paths is empty unexpectedly |
Re-run git diff --name-only REF to verify the ref, then rerun with a valid REF; do not treat an empty changed-path list as proof nothing changed |
Shape registry schema error appears in findings.json as shape_registry_schema_error |
Honor the script's nonzero exit, fix .claude/skills/which-shape/shapes.json, and rerun before updating state |
| Report or state write fails | State which artifact failed to write; do not claim report.md, state.json, findings.json, evidence.json, or .claude/ecosystem/last-state.json landed |
Baseline is missing and baseline_missing appears in findings.json |
Review the first report as the baseline, then rerun with --update-state only after accepting that snapshot |
Relationship To /which-shape
When a skill is added or materially repurposed, review
.claude/skills/which-shape/shapes.json. Add the skill to a shape only
when it changes a durable problem-solving loop. If the skill is purely
tactical, leaving it out is fine; updating the ecosystem state records
that the omission was reviewed.