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.