login
krispuckett

skill-issue

by @krispuckett in AI & LLM
19
0
# Install this skill:
npx skills add krispuckett/skill-issue

Or install specific skill: npx add-skill https://github.com/krispuckett/skill-issue

# Description

Audit and review all installed agent skills. Run on-demand or via cron to get a health report: skill inventory, usage tracking, version checks, dependency health, and actionable recommendations (keep, update, review, remove). Use when asked to review skills, check for skill updates, find unused skills, or audit the skill ecosystem.

# SKILL.md

name: skill-issue
description: "Audit and review all installed agent skills. Run on-demand or via cron to get a health report: skill inventory, usage tracking, version checks, dependency health, and actionable recommendations (keep, update, review, remove). Use when asked to review skills, check for skill updates, find unused skills, or audit the skill ecosystem."

Skill Issue β€” Skill Auditor

Audit all installed skills and produce a markdown report with recommendations.

Quick Start

# Basic β€” scans ./skills and ./memory
node scripts/audit.mjs

# Custom directories
SKILL_DIRS="./skills,/path/to/more/skills" MEMORY_DIR="./memory" node scripts/audit.mjs

# Save report
node scripts/audit.mjs > /tmp/skill-audit-report.md

Environment Variables

Variable Default Description
SKILL_DIRS ./skills Comma-separated skill directories to scan
MEMORY_DIR ./memory Dated markdown logs for usage tracking
AUDIT_DAYS 7 Days back to scan for usage

What It Checks

  1. Inventory β€” Finds every subdirectory containing a SKILL.md with YAML frontmatter
  2. Usage β€” Scans recent memory/log files for skill name mentions
  3. Health β€” Verifies required binaries (requires.bins) and env vars (requires.env)
  4. Versions β€” Checks ClawdHub registry if clawdhub CLI is available
  5. Recommendations β€” keep (active+healthy), update (outdated), review (unused), remove (broken deps)

Safety

  • Read-only β€” Never modifies, installs, or removes anything
  • Advisory only β€” Recommendations require manual action

# README.md

πŸ” skill-issue

An agent skill that audits all your other agent skills. HR department for AI agents.

Find the skill issues before they find you.

Name: Josh Puckett β€” who immediately knew it had to be called /skill-issue

Concept: Benji Taylor β€” "I need a skill that reviews all the other skills, figures out which ones are performing, and fires the rest."

What It Does

  • Inventories every installed skill across your project
  • Tracks usage by scanning recent logs for skill mentions
  • Checks health β€” verifies required binaries and environment variables
  • Recommends action β€” keep, update, review, or remove

Quick Start

git clone https://github.com/krispuckett/skill-issue.git
cd skill-issue

# Point it at your skills directory
SKILL_DIRS="../my-project/skills" node scripts/audit.mjs

That's it. Any directory containing subdirectories with SKILL.md files will be scanned.

Usage

Ask Your Agent

"Run a skill audit"
"Check my skills for issues"
"Do I have a skill issue?"

CLI

# Scan default ./skills directory
node scripts/audit.mjs

# Scan multiple directories
SKILL_DIRS="./skills,./other-skills" node scripts/audit.mjs

# Scan with usage tracking from your logs
SKILL_DIRS="./skills" MEMORY_DIR="./logs" node scripts/audit.mjs

Configuration

Variable Default Description
SKILL_DIRS ./skills Comma-separated directories to scan
MEMORY_DIR ./memory Directory with dated markdown logs (YYYY-MM-DD.md) for usage tracking
AUDIT_DAYS 7 How far back to scan for usage
SKIP_HUB false Set to 1 to skip ClawdHub version checks

What It Scans

The auditor looks for subdirectories containing a SKILL.md with YAML frontmatter:

skills/
β”œβ”€β”€ my-skill/
β”‚   └── SKILL.md
β”œβ”€β”€ another-skill/
β”‚   └── SKILL.md

SKILL.md Format

---
name: my-skill
description: "What this skill does"
metadata: {"requires":{"bins":["curl","jq"],"env":["API_KEY"]}}
---

If requires.bins lists CLI tools, the audit checks they're installed. If requires.env lists env vars, it checks they're set.

Sample Output

# πŸ” Skill Audit Report

## Summary
- Total skills: 12
- βœ… Keep: 5       (active + healthy)
- πŸ”Ž Review: 4    (unused β€” maybe remove?)
- πŸ—‘οΈ Remove: 3    (broken dependencies)

## Detailed Report
| # | Skill       | Bins     | Usage (7d) | Health | Rec       |
|---|-------------|----------|------------|--------|-----------|
| 1 | 🌀️ weather  | curl     | πŸ“Š 5       | βœ…     | βœ… keep   |
| 2 | πŸ—£οΈ voice    | sag      | β€”          | ❌ sag | πŸ—‘οΈ remove |
| 3 | πŸ“§ email    | himalaya | πŸ“Š 8       | βœ…     | βœ… keep   |

## ⚠️ Skills Needing Attention
- **voice** β€” πŸ—‘οΈ Missing: `sag` not found. Install or remove.

How It Works

  1. Scans SKILL_DIRS for subdirectories with SKILL.md
  2. Parses YAML frontmatter for metadata
  3. Runs which on each required binary
  4. Checks process.env for required variables
  5. Scans dated .md files in MEMORY_DIR for skill name mentions
  6. Outputs a markdown report with per-skill recommendations

Read-only. Never modifies, installs, or removes anything.

Requirements

  • Node.js 18+

License

MIT β€” see LICENSE

# Related Skills

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚑ Amp πŸš€ Antigravity πŸ€– Claude Code πŸ¦€ Clawdbot πŸ“ Codex ▢️ Cursor πŸ€– Droid πŸ’Ž Gemini CLI πŸ™ GitHub Copilot πŸͺΏ Goose πŸ“Š Kilo Code πŸ”§ Kiro CLI πŸ’» OpenCode 🦘 Roo Code 🌲 Trae πŸ„ Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.