Files

Paul O'Reilly cbde292dd7 Add check-skills: verify skill symlinks match source repo

Compares installed skill symlinks against the source directory,
reporting missing, stale, and orphan entries.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-17 11:14:25 +13:00

2.5 KiB

Raw Permalink Blame History

check-skills

Purpose

Check which skills from the custom-claude-skills repository are missing from the active Claude Code profile's skills directory.

Usage

check-skills [OPTIONS] [SKILLS_REPO]

Arguments

Argument	Default	Description
`SKILLS_REPO`	`~/dev/claude/projects/custom-claude-skills/skills`	Path to the skills source directory

Options

Flag	Description
`--profile DIR`	Override the Claude profile directory (default: `$CLAUDE_CONFIG_DIR` or `~/.claude`)
`--dryrun`, `-n`	Same as normal mode (script is read-only by nature)
`--help`, `-h`	Show usage

Behaviour

Resolve the skills source directory (the repo's skills/ folder)
Resolve the active profile's skills directory ($CLAUDE_CONFIG_DIR/skills or ~/.claude/skills)
For each subdirectory in the source that contains a SKILL.md:
- Check if a symlink exists in the profile's skills directory pointing to that source
- Classify as: linked (symlink exists and points to correct source), stale (symlink exists but points elsewhere or is broken), or missing (no entry in profile skills dir)
Also check for entries in the profile's skills directory that don't correspond to any source skill — classify as orphan
Print a summary report

Output Format

Profile: ~/.claude-octopus
Source:  ~/dev/claude/projects/custom-claude-skills/skills

  LINKED   reflect
  LINKED   log
  LINKED   reflect-logs
  MISSING  housekeeping
  STALE    old-skill (points to /some/other/path)
  ORPHAN   manual-skill (not in source repo)

Summary: 3 linked, 1 missing, 1 stale, 1 orphan

LINKED — green, no action needed
MISSING — yellow, skill exists in repo but not linked in profile
STALE — yellow, symlink target doesn't match expected source
ORPHAN — cyan, exists in profile but not in source repo (informational, not an error)

Exit code:

0 if no missing or stale skills
1 if any missing or stale skills found

Dryrun Behaviour

Identical to normal mode — this script is read-only and never modifies anything. The --dryrun flag is accepted for convention compliance but has no effect.

Edge Cases

Skills source directory doesn't exist → error message, exit 1
Profile skills directory doesn't exist → treat all skills as missing
Broken symlink in profile → classify as stale
CLAUDE_CONFIG_DIR not set → fall back to ~/.claude
Subdirectory in source without SKILL.md → skip (not a valid skill)

2.5 KiB Raw Permalink Blame History