An Agent Skills health check inventories every supported skill root, records package and path provenance, estimates name-and-description catalog context, matches local session evidence, flags overlapping installs, and confirms that archive operations remain recoverable. Run it before removing skills, after installing a plugin pack, and after moving your setup to another machine.
What the audit checks
A useful audit answers six questions for every skill: Where does it live? Which agent can load it? Where did it come from? How large are its instructions? Which local sessions reference it? Can an archive be restored to its original path?
| Signal | What it tells you | Decision use |
|---|---|---|
| Root and path | The skill scope and exact folder on disk | Find shadowed or misplaced copies |
| Source metadata | Package, repository, plugin, and install dates when available | Choose the copy you trust and can update |
| Usage evidence | Local Codex or Claude session references | Estimate current workflow relevance |
| Catalog context estimate | Approximate tokens in the skill name and description | Spot verbose discovery metadata worth inspecting |
| Archive ledger | Original path, archive path, time, and operation state | Preserve recovery information |
Run the local audit
Open a terminal and run the CLI from any directory. The audit reads supported global roots and reports what it can verify locally.
$ npx github:Ryan-yang125/skill-manager auditStart by checking coverage. A missing root can simply mean that the matching agent has no global skills on this machine. Session-log counts matter because they define how much history the usage matcher could inspect.
Interpret the signals together
Each signal has limits. A large skill can provide high value. A recently installed skill can have zero usage history. A frequently referenced name can appear in several packages. Good decisions come from the intersection of evidence, provenance, overlap, and personal workflow.
- Keep: trusted source, clear purpose, and current workflow value.
- Review: sparse evidence, uncertain provenance, large instructions, or unclear ownership.
- Archive: confirmed replacement, abandoned experiment, or duplicate with a chosen canonical copy.
Evidence rule: zero matches describes the scanned logs. Treat it as a prompt for review and preserve rare, seasonal, recovery, and security skills that still have a defined job.
Choose an audit cadence
Run a health check after installing a large skill pack, before changing agent setups, and at a regular interval that matches how often your tools change. Monthly works well for active experimenters. Quarterly is enough for a stable setup.
Save the JSON report when you want a machine-readable baseline. Comparing two reports reveals added paths, changed catalog metadata estimates, new evidence, and archive state over time.
Verify every change
- Preview the exact skills and original paths selected for archive.
- Keep the archive ledger in the app data directory.
- Run a fresh audit and confirm active and archived counts.
- Restore one low-risk item during initial setup to validate the recovery route.
Health check FAQ
What does an Agent Skills health check include?
It includes installed paths, source metadata, name-and-description catalog estimates, local usage evidence, duplicate locations, archive state, and evidence coverage.
Does zero usage evidence mean a skill is unused?
Zero matched evidence is a review signal. Session coverage may be incomplete, and rare workflow skills can remain valuable.
Can Skill Manager audit skills offline?
Yes. Inventory, usage analysis, archive, restore, and report export run locally. Release update checks and user-opened repository links use the network.
Run the audit
Start with a read-only report, then use the desktop app when you want file previews and reversible archive controls.
Get the command