skill-checkup

name	skill-checkup
description	Use when you need to validate the health of your Claude Code skills library — checks for broken file references, missing dependencies, frontmatter issues, duplicate triggers, and dependency drift. Runs structural and semantic audits across all installed skills. Invoke via '/checkup', '/review-skills', or 'check my skills'.
argument-hint	[--quick | --full | skill-name]

/checkup — Skills Library Health Check

Validates the structural health of your Claude Code skills. Reports problems, does not auto-fix.

Triggers

• /checkup — standard check (Level 0 + Level 1)
• /checkup --quick — binary checks only (Level 0)
• /checkup --full — all levels including semantic analysis (Level 2)
• /checkup <skill-name> — check a single skill
• /review-skills — alias for /checkup

When NOT to Use

• Checking a single skill file you just wrote — use manual review instead
• Investigating runtime behavior — this is structural, not functional
• Fewer than 5 skills installed — overhead exceeds value

Workflow

Phase 0: Canary + Discovery

Canary test — verify a known truth before proceeding:

Determine the skills directory. Use $HOME to expand the path:

Bash: ls "$HOME/.claude/skills/"

If the directory does not exist or is empty — STOP. Report: "Skills directory not found at ~/.claude/skills/. Cannot proceed." The rest of the report is unreliable.

Discovery — build the full catalog:

1. Find all skill files:

Bash: find "$HOME/.claude/skills" -maxdepth 2 -name "SKILL.md" | sort

Also check for lowercase variants (skill.md) which indicate a naming issue.

2. For each skill, collect metadata:

   • File path
   • Last modified date: Bash: stat -f %m "{path}" 2>/dev/null || stat -c %Y "{path}" 2>/dev/null
   • File size
   • name from frontmatter
   • description from frontmatter

3. Store the catalog in memory for subsequent phases.

Phase 1: Validation (Level 0 + Level 1)

All results are marked as FACT.

Level 0 — Binary Checks

For each skill:

1. File dependencies exist. Extract all file paths from the skill text (patterns: lines starting with / or ~/ that look like file paths, paths inside backticks). For each path, expand ~ to $HOME and check:

Bash: test -e "$HOME/path/to/file" && echo "exists" || echo "MISSING"

If missing — [x].

2. Cross-references to other skills are valid. Extract all skill mentions (patterns: /skill-name triggers, skills/X/SKILL.md paths). Verify each referenced skill exists in the catalog from Discovery. If not — [x].

3. Absolute paths are valid. Find all absolute paths (/Users/..., /home/..., /opt/...). Verify existence. If missing — [x].

4. File naming is correct. Verify the main file is named exactly SKILL.md (not skill.md, SKILL.MD, or other variants). If wrong — [!].

Level 1 — Structural Checks

5. Frontmatter is valid. Verify required elements:

• YAML frontmatter block (between --- markers)
• name field present and non-empty
• description field present and non-empty
• At least one ## section heading in the body If anything is missing — [!].

6. Trigger uniqueness. Collect all triggers (slash commands like /...) from all skills. If two skills share the same trigger — [!] for both, listing the conflict.

7. Drift detection. For each skill: extract file dependencies. Compare the skill's last-modified date with each dependency's last-modified date:

Bash: stat -f %m "{path}" 2>/dev/null || stat -c %Y "{path}" 2>/dev/null

If a dependency was modified AFTER the skill — [!] with drift in days.

Phase 2: Semantic Analysis (Level 2, only with --full)

Results are marked as SUGGESTION.

IMPORTANT: The auditor SKIPS ITSELF (skill-checkup) in semantic checks.

8. Duplicate detection. Compare skills pairwise: do two skills do the same thing? Check by descriptions and triggers. If overlap >70% — [~].

9. Description clarity. For each skill: can a user unambiguously tell when to invoke it from the description alone? If the description is vague or ambiguous — [~].

10. Description format. Check if the description follows the "Use when..." pattern recommended by Anthropic best practices. If not — [~].

---

Output Format

Last checkup: {date}. Since then: {+N skills, -N issues resolved, +N new issues}.

{N} skills. Library is healthy.
{healthy} healthy. {attention} need attention. {broken} broken.

[x] /{skill}: {what is wrong — plain language}
    -> {what to do} (line {N} in {file path})

[!] /{skill}: drift — dependency {file} modified {N} days after skill
    -> Review whether the change affects skill logic

---
Suggestions (--full only):

[~] /{skill-a} and /{skill-b}: possible functional overlap
    -> Consider merging or clarifying boundaries

Checked in {N} seconds.

Format rules:

• Healthy skills are NOT listed
• [x] — broken (FACT, action required)
• [!] — needs attention (FACT, drift or potential issue)
• [~] — suggestion (SUGGESTION, from Level 2)
• Verdict first, then numbers, then issues
• Each issue: what is wrong + what to do + where (file:line)
• SUGGESTIONS block is visually separated from FACTS
• If everything is healthy — say so, do not list N lines of "OK"
• No emoji

If the library is fully healthy:

{N} skills. Library is healthy.

Checked in {N} seconds. No issues found.

---

History

After each run, persist the result to ~/.claude/checkup-history.json:

Read $HOME/.claude/checkup-history.json (if it exists)

Append an entry:

{
  "date": "YYYY-MM-DD",
  "mode": "default|quick|full",
  "summary": {
    "total": 48,
    "healthy": 46,
    "attention": 2,
    "broken": 0
  },
  "issues": [
    {
      "skill": "my-skill",
      "level": "x",
      "message": "dependency ~/templates/report.html not found"
    }
  ],
  "duration_seconds": 8
}

Keep the last 20 runs. Drop older entries when writing a new one.

When a previous run exists — show the trend in the first line of the report.

---

Self-audit

1. Canary test at startup — verify ~/.claude/skills/ exists before anything else
2. Check self with binary tests only (Level 0). Skip semantic checks for skill-checkup
3. At the end of the report — recommend a manual audit once a month

---

Proactive Reminders

On session start, if >14 days since the last checkup:

It's been {N} days since the last /checkup. Consider running a skills health check.

After creating a new skill:

New skill created. Run /checkup {skill-name} for a quick validation.

---

Principles

1. Navigator, not autopilot. Reports problems, does not fix them.
2. FACT vs SUGGESTION. The user always knows what is deterministic and what is a recommendation.
3. Healthy skills are silence. Only problems appear in the report.
4. Tone is care, not control. No shouting, no aggression. A calm doctor.
5. Specificity. Not "problem in skill X". Rather "file Y not found, line Z, action — restore or update path".