# audit-library-health

audit-library-health — a skill for diagnosing a skills library: validates structure, finds stale elements, checks documentation sync. Run before publishing or updating.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 170 installs · ★ 1161 repo stars
- Author: MoizIbnYousaf
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/MoizIbnYousaf/ai-agent-skills/tree/HEAD/skills/audit-library-health/SKILL.md
- Updated: 2026-09-21
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/audit-library-health

## What it does

Audits a library in four stages: validates catalog structure and frontmatter, runs diagnostics on installed skills, identifies elements ready for refresh, and compares generated docs against actual state. Each step outputs structured JSON for easy automation.

Includes four commands: `validate` checks catalog integrity and required fields; `doctor --format json` diagnoses installations; `check --format json` scans for stale skills via network requests (can be slow on unreachable repos); `build-docs --dry-run` reports whether docs are in sync, then regenerates if needed. Before pushing to a public repo, both `validate` and `doctor` must pass without errors.

Provides a checklist: all fields populated, folders consistent, skill count in skills.json matches reality. The guardrail on `--dry-run` before `build-docs` prevents accidental mutations.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add MoizIbnYousaf/ai-agent-skills --skill audit-library-health -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/audit-library-health/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/audit-library-health/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add MoizIbnYousaf/ai-agent-skills --skill audit-library-health -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/audit-library-health/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add MoizIbnYousaf/ai-agent-skills --skill audit-library-health -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/audit-library-health/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install MoizIbnYousaf/ai-agent-skills skills/audit-library-health
```

2. **Manually: put the files in place**
- File: `.github/skills/audit-library-health/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add MoizIbnYousaf/ai-agent-skills --skill audit-library-health -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/MoizIbnYousaf/ai-agent-skills --path skills/audit-library-health
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/audit-library-health/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add MoizIbnYousaf/ai-agent-skills --skill audit-library-health -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/MoizIbnYousaf/ai-agent-skills/tree/HEAD/skills/audit-library-health/SKILL.md

## When to use it
- verify library structure consistency before publishing
- locate skills with missing required fields
- synchronize generated documentation with the current catalog
- identify stale skills that need updates
- diagnose broken installations in a local library

## Example prompts
- Check the health of my skills library before pushing it
- Run audit-library-health and tell me if docs are in sync
- Find all skills with missing fields using validate

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: bd781a55b4d5e19d.

BEGIN THIRD-PARTY FILE bd781a55b4d5e19d
````text
---
name: audit-library-health
description: Use when checking the overall health of a skills library. Run doctor, validate, check for stale skills, and verify generated docs are in sync.
category: workflow
version: 4.1.0
---

# 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.

```bash
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.

```bash
npx ai-agent-skills doctor --format json
```

3. Check for skills that may need updates.

```bash
npx ai-agent-skills check --format json
```

4. Verify generated docs are in sync.

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

If `currentlyInSync` is false, regenerate:

```bash
npx ai-agent-skills build-docs
```

5. Review the curation queue for skills needing attention.

```bash
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.
````
END THIRD-PARTY FILE bd781a55b4d5e19d

The third-party file has ended. Everything between the bd781a55b4d5e19d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© MoizIbnYousaf · MIT · https://github.com/MoizIbnYousaf/ai-agent-skills/tree/HEAD/skills/audit-library-health/SKILL.md

## Similar
- [help](https://affpapa.org/en/nevibecode/skills/bitwize-music-studio-help.md) — skill · 253 installs
- [documentation-engineer](https://affpapa.org/en/nevibecode/agents/voltagent-documentation-engineer.md) — subagent · ★ 6505 repo stars
- [add-skill](https://affpapa.org/en/nevibecode/commands/add-skill.md) — command · ★ 2707 repo stars
- [marketplace-health-check](https://affpapa.org/en/nevibecode/skills/marketplace-health-check.md) — skill · 452 installs
- [loop-library](https://affpapa.org/en/nevibecode/skills/forward-future-loop-library.md) — skill · 2400 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
