/skill-stocktake

description: "Use when auditing Claude skills and commands for quality. Supports Quick Scan (changed skills only) and Full Stocktake modes with sequential subagent batch evaluation."
origin: ECC

skill-stocktake

Slash command (`/skill-stocktake`) that audits all Claude skills and commands using a quality checklist + AI holistic judgment. Supports two modes: Quick Scan for recently changed skills, and Full Stocktake for a complete review.

Scope

The command targets the following paths **relative to the directory where it is invoked**:

| Path | Description | |------|-------------| | `~/.claude/skills/` | Global skills (all projects) | | `{cwd}/.claude/skills/` | Project-level skills (if the directory exists) |

**At the start of Phase 1, the command explicitly lists which paths were found and scanned.**

Targeting a specific project

To include project-level skills, run from that project's root directory:

cd ~/path/to/my-project
/skill-stocktake

If the project has no `.claude/skills/` directory, only global skills and commands are evaluated.

Modes

| Mode | Trigger | Duration | |------|---------|---------| | Quick Scan | `results.json` exists (default) | 5–10 min | | Full Stocktake | `results.json` absent, or `/skill-stocktake full` | 20–30 min |

**Results cache:** `~/.claude/skills/skill-stocktake/results.json`

Quick Scan Flow

Re-evaluate only skills that have changed since the last run (5–10 min).

1. Read `~/.claude/skills/skill-stocktake/results.json` 2. Run: `bash ~/.claude/skills/skill-stocktake/scripts/quick-diff.sh \ ~/.claude/skills/skill-stocktake/results.json` (Project dir is auto-detected from `$PWD/.claude/skills`; pass it explicitly only if needed) 3. If output is `[]`: report "No changes since last run." and stop 4. Re-evaluate only those changed files using the same Phase 2 criteria 5. Carry forward unchanged skills from previous results 6. Output only the diff 7. Run: `bash ~/.claude/skills/skill-stocktake/scripts/save-results.sh \ ~/.claude/skills/skill-stocktake/results.json <<< "$EVAL_RESULTS"`

Full Stocktake Flow

Phase 1 — Inventory

Run: `bash ~/.claude/skills/skill-stocktake/scripts/scan.sh`

The script enumerates skill files, extracts frontmatter, and collects UTC mtimes. Project dir is auto-detected from `$PWD/.claude/skills`; pass it explicitly only if needed. Present the scan summary and inventory table from the script output:

Scanning:
  ✓ ~/.claude/skills/         (17 files)
  ✗ {cwd}/.claude/skills/    (not found — global skills only)

| Skill | 7d use | 30d use | Description | |-------|--------|---------|-------------|

Phase 2 — Quality Evaluation

Launch an Agent tool subagent (**general-purpose agent**) with the full inventory and checklist:

Agent(
  subagent_type="general-purpose",
  prompt="
Evaluate the following skill inventory against the checklist.

[INVENTORY]

[CHECKLIST]

Return JSON for each skill:
{ \"verdict\": \"Keep\"|\"Improve\"|\"Update\"|\"Retire\"|\"Merge into [X]\", \"reason\": \"...\" }
"
)

The subagent reads each skill, applies the checklist, and returns per-skill JSON:

`{ "verdict": "Keep"|"Improve"|"Update"|"Retire"|"Merge into [X]", "reason": "..." }`

**Chunk guidance:** Process ~20 skills per subagent invocation to keep context manageable. Save intermediate results to `results.json` (`status: "in_progress"`) after each chunk.

After all skills are evaluated: set `status: "completed"`, proceed to Phase 3.

**Resume detection:** If `status: "in_progress"` is found on startup, resume from the first unevaluated skill.

Each skill is evaluated against this checklist:

- [ ] Content overlap with other skills checked
- [ ] Overlap with MEMORY.md / CLAUDE.md checked
- [ ] Freshness of technical references verified (use WebSearch if tool names / CLI flags / APIs are present)
- [ ] Usage frequency considered

Verdict criteria:

| Verdict | Meaning | |---------|---------| | Keep | Useful and current | | Improve | Worth keeping, but specific improvements needed | | Update | Referenced technology is outdated (verify with WebSearch) | | Retire | Low quality, stale, or cost-asymmetric | | Merge into [X] | Substantial overlap with another skill; name the merge target |

Evaluation is **holistic AI judgment** — not a numeric rubric. Guiding dimensions:

• **Actionability**: code examples, commands, or steps that let you act immediately
• **Scope fit**: name, trigger, and content are aligned; not too broad or narrow
• **Uniqueness**: value not replaceable by MEMORY.md / CLAUDE.md / another skill
• **Currency**: technical references work in the current environment

**Reason quality requirements** — the `reason` field must be self-contained and decision-enabling:

• Do NOT write "unchanged" alone — always restate the core evidence
• For **Retire**: state (1) what specific defect was found, (2) what covers the same need instead
• Bad: `"Superseded"`
• Good: `"disable-model-invocation: true already set; superseded by continuous-learning-v2 which covers all the same patterns plus confidence scoring. No unique content remains."`
• For **Merge**: name the target and describe what content to integrate
• Bad: `"Overlaps with X"`
• Good: `"42-line thin content; Step 4 of chatlog-to-article already covers the same workflow. Integrate the 'article angle' tip as a note in that skill."`
• For **Improve**: describe the specific change needed (what section, what action, target size if relevant)
• Bad: `"Too long"`
• Good: `"276 lines; Section 'Framework Comparison' (L80–140) duplicates ai-era-architecture-principles; delete it to reach ~150 lines."`
• For **Keep** (mtime-only change in Quick Scan): restate the original verdict rationale, do not write "unchanged"
• Bad: `"Unchanged"`
• Good: `"mtime updated but content unchanged. Unique Python reference explicitly imported by rules/python/; no overlap found."`

Phase 3 — Summary Table

| S