Documentation
README
Audit Skill Libraries
Find evidence-backed defects without changing the library.
Scope
| Target | Checks |
|---|---|
| One Skill | Frontmatter, description, links, resources, scripts, secrets, local paths, size |
| Skill Library | Every single-Skill check plus duplicate names, ownership, scope, and static trigger overlap |
Ownership
- Audit owns static structure, safety, references, metadata, and trigger overlap.
- Test owns live activation and outcome behavior.
- Visualize owns inventory/usage/test evidence and conservative lifecycle review candidates.
- Create owns applying approved structural changes.
Method
- Run
uv run --script <skill-dir>/scripts/run -- lint <target> --jsonfirst for a single Skill or a library. Save and use its static findings as evidence. - Manually review what CLI cannot prove: description semantics, ownership, scope, and trigger overlap.
- If CLI is unavailable or fails: state limitation /
inconclusive. Never claim clean. - Do not execute scripts. Do not auto-fix.
Checks
- Missing or invalid
SKILL.mdand frontmatter - Directory/name mismatch
- Workflow summaries or ambiguous triggers in
description - Broken relative links and unused resources
- Non-executable or risky scripts
- Secrets and accidental machine-local paths
- Oversized bodies that should use progressive disclosure
- Static trigger overlap across sibling skills
- Project-only instructions inside a global package
Severity
| Level | Meaning |
|---|---|
| P0 | Install or execution breaks |
| P1 | Triggering or ownership is wrong |
| P2 | Safety or maintenance risk |
| P3 | Cleanup or style debt |
Output
Return severity, file, evidence, impact, and smallest suggested change. Do not apply fixes unless requested.
uv run --script <skill-dir>/scripts/run -- lint skills/<name> --json
uv run --script <skill-dir>/scripts/run -- lint skills --json
uv run --script <skill-dir>/scripts/run -- scan skills/<name> --json
uv run --script <skill-dir>/scripts/run -- scan skills --json