Audit library health

Audit Library Health

Goal

Verify that a skills library is consistent, up-to-date, and ready to share or install from.

Guardrails

• Always use --format json for structured output when automating health checks.
• Always use --dry-run before running build-docs to check if docs are already in sync.
• Never push a library to a shared repo without passing validate and doctor first.
• Use --fields to limit output when inspecting large catalogs.

Workflow

1. Run the validation script to check catalog integrity.

npx ai-agent-skills validate

This checks: required fields, folder consistency, frontmatter validity, collection integrity, and generated doc sync.

2. Run doctor to check installed skills health.

npx ai-agent-skills doctor --format json

3. Check for skills that may need updates.

npx ai-agent-skills check --format json

4. Verify generated docs are in sync.

npx ai-agent-skills build-docs --dry-run --format json

If currentlyInSync is false, regenerate:

npx ai-agent-skills build-docs

5. Review the curation queue for skills needing attention.

npx ai-agent-skills curate review --format json

Health Checklist

• validate passes with no errors
• doctor reports no broken installs
• build-docs --dry-run shows docs are in sync
• No skills with empty whyHere fields
• All house skills have matching folders in skills/
• skills.json total matches actual skill count

Gotchas

• validate and doctor are read-only — they never mutate the library.
• check makes network requests to verify upstream sources. It may be slow or timeout on unreachable repos.
• The curate review queue is derived from missing fields and stale verification dates — it is a heuristic, not a mandate.