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>

specs/check-skills.spec.md

@@ -0,0 +1,72 @@
+# 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
+
+1. Resolve the skills source directory (the repo's `skills/` folder)
+2. Resolve the active profile's skills directory (`$CLAUDE_CONFIG_DIR/skills` or `~/.claude/skills`)
+3. 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)
+4. Also check for entries in the profile's skills directory that don't correspond to any source skill — classify as **orphan**
+5. 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)