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).

• Read ~/.claude/skills/skill-stocktake/results.json

• 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)

• If output is []: report "No changes since last run." and stop

• Re-evaluate only those changed files using the same Phase 2 criteria

• Carry forward unchanged skills from previous results

• Output only the diff

• 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

Skill

7d use

Verdict

Reason

Phase 4 — Consolidation

• Retire / Merge: present detailed justification per file before confirming with user:

• What specific problem was found (overlap, staleness, broken references, etc.)

• What alternative covers the same functionality (for Retire: which existing skill/rule; for Merge: the target file and what content to integrate)

• Impact of removal (any dependent skills, MEMORY.md references, or workflows affected)

• Improve: present specific improvement suggestions with rationale:

• What to change and why (e.g., "trim 430→200 lines because sections X/Y duplicate python-patterns")

• User decides whether to act

• Update: present updated content with sources checked

• Check MEMORY.md line count; propose compression if >100 lines

Results File Schema

~/.claude/skills/skill-stocktake/results.json:

**evaluated_at**: Must be set to the actual UTC time of evaluation completion.

Obtain via Bash: date -u +%Y-%m-%dT%H:%M:%SZ. Never use a date-only approximation like T00:00:00Z.

{

  "evaluated_at": "2026-02-21T10:00:00Z",

  "mode": "full",

  "batch_progress": {

    "total": 80,

    "evaluated": 80,

    "status": "completed"

  },

  "skills": {

    "skill-name": {

      "path": "~/.claude/skills/skill-name/SKILL.md",

      "verdict": "Keep",

      "reason": "Concrete, actionable, unique value for X workflow",

      "mtime": "2026-01-15T08:30:00Z"

    }

  }

}

Notes

• Evaluation is blind: the same checklist applies to all skills regardless of origin (ECC, self-authored, auto-extracted)

• Archive / delete operations always require explicit user confirmation

• No verdict branching by skill origin