Skill Health Monitor

Automated audits that score and report on skill health by checking structure, content, activity, compatibility, and discoverability to prevent failures.

Security Scan

An instruction-only audit/checklist for evaluating skill collections; content and requirements are consistent with its stated purpose, though it assumes local shell tooling and references CLI helpers that are not included.

Purpose & Capability

The skill's name and description match the SKILL.md contents: it's a health-audit checklist for agent skills. It does not request credentials or install anything, which is proportionate. Minor inconsistency: the SKILL.md shows example audit commands (check-skill-health, scan-skills, skill-health) that are not provided by the package, and the declared requirements list no binaries even though the instructions assume common shell tools (cat, grep, git). This is plausible but should be understood: the document is a guide, not an included implementation.

Instruction Scope

Instructions remain within the scope of auditing skills: reading SKILL.md, grepping for TODO/FIXME, checking git history, and producing a report. There is no instruction to transmit data to external endpoints. Caveat: the instructions require reading potentially sensitive files inside a skills collection (which is expected for a local audit), so run against only the intended directories and be aware of secrets present in skill files.

Install Mechanism

No install spec and no code files — lowest-risk delivery. Because this is instruction-only, nothing will be written or executed automatically by installing the skill.

Credentials

The skill declares no environment variables, credentials, or config path requirements, which is appropriate for a read-only health checklist. The SKILL.md does reference standard dev tools (git, grep, cat) but does not request special permissions or secrets.

Persistence & Privilege

always is false and the skill does not request persistent privileges or attempt to alter other skills or agent-wide settings. It's a manual guide for operators rather than an autonomously running component.

Assessment

This is a guidance-only skill (no code) intended as a checklist for auditing your skill collection. It's internally consistent and low-risk, but note the following before using it: (1) the examples reference helper CLI commands (check-skill-health, scan-skills, skill-health) that are not included — you'll need to implement or substitute your own tooling, (2) the checklist expects access to local tools (git, grep, cat); ensure those are available and run checks in the intended directories only, (3) audit operations read skill files and git history and could surface secrets if present — consider running on a copy or in a sandbox, and (4) because the skill contains no executable code, it won't perform automated scans by itself; you should implement or use safe, reviewed scripts to automate the recommended checks. If you want automated behavior, request an implementation (source code or verified CLI) and review that code before running it.

Automated health checks for your agent skill collection

Purpose

Audit, score, and maintain the health of your AI agent skills. Catch rotting skills, missing files, broken triggers, and outdated content before they cause silent failures.

When to Use

• "check skill health", "audit my skills", "skill inventory"
• Periodic maintenance (weekly/monthly)
• Before adding new skills to a collection
• When agents start behaving unexpectedly

Health Score Dimensions (0-100 each)

1. Structure (25%)

• Has SKILL.md or equivalent config file
• Has README.md with usage instructions
• File structure follows agent skill conventions
• No orphaned or dangling file references

2. Content (25%)

• Description is clear and specific (not vague)
• Trigger words/phrases are defined
• Examples are provided
• Edge cases and failure modes documented

3. Activity (20%)

• Updated within last 30 days
• Commit history shows maintenance
• Issues/PRs are addressed
• Dependencies are current

4. Compatibility (15%)

• Works with current agent framework version
• No deprecated API usage
• Cross-platform tested (if applicable)
• Dependencies listed and version-pinned

5. Discoverability (15%)

• Has relevant topics/tags
• Description contains searchable keywords
• Listed in skill directories
• README has quick-start section

Health Rating

Score	Rating	Action
90-100	🟢 Healthy	Maintain
70-89	🟡 Needs Attention	Minor fixes
50-69	🟠 Degrading	Schedule update
0-49	🔴 Critical	Rewrite or retire

Audit Commands

# Check single skill directory
check-skill-health ./path/to/skill

# Scan entire skill collection
scan-skills ./skills/ --report=health-report.md

# Compare health over time
skill-health diff --baseline=health-report-2026-03.md --current=health-report-2026-04.md

Quick Audit Checklist

Run this on each skill:

1. cat SKILL.md — Does it exist? Is the description clear?
2. grep -r "TODO\|FIXME\|HACK" — Any technical debt markers?
3. git log --since="30 days ago" --oneline — Any recent activity?
4. grep -i "trigger\|when to use\|example" SKILL.md — Are triggers and examples defined?
5. Check for hard-coded paths, URLs, or deprecated tool names

Report Format

## Skill Health Report — 2026-04-22

### Summary
- Total skills: 16
- 🟢 Healthy: 8 (50%)
- 🟡 Needs Attention: 5 (31%)
- 🟠 Degrading: 2 (13%)
- 🔴 Critical: 1 (6%)
- Average score: 74/100

### Issues Found
1. **prompt-guard** (🔴 35/100) — Missing README, no trigger words
2. **evr-framework** (🟠 55/100) — SKILL.md only, no examples
3. ...

Anti-Patterns to Watch

• ❌ "Good skill" with no evidence of testing
• ❌ Skills that duplicate existing functionality
• ❌ Over-engineered skills with 50+ rules nobody follows
• ❌ Skills referencing removed or renamed tools
• ❌ Copy-pasted descriptions that don't match content

License

MIT