git:20260624.7f1ddab to git:20260702.de3e382

2 added, 0 removed. Audit A to A.

# skill-stocktake

> A Claude Code skill (MIT) that audits all installed Claude skills for quality. It reads every skill in one context and applies AI holistic judgment to produce Keep / Improve / Update / Retire / Merge verdicts. Two modes: full (evaluate everything) and changed (re-evaluate only changed skills, carry the rest forward). No scan scripts, no subagent batching — it relies on a large context window.

## Core documentation

- [llms-full.txt](llms-full.txt): self-contained Q&A reference for AI agents (Project Facts, Prior Research, question-form H2 sections)

- [README.md](README.md): human-facing narrative (install, modes, verdict criteria, requirements)

- [SKILL.md](skills/skill-stocktake/SKILL.md): full slash-command specification — modes, four-phase flow, evaluation checklist, reason-quality rules

+ - [hooks/log-skill-usage.sh](hooks/log-skill-usage.sh): bundled usage-measurement hook (Claude Code–specific; adaptable to other harnesses) with bats tests under tests/

## Architecture

- 5 verdicts: **Keep** (useful and current), **Improve** (worth keeping, specific fixes), **Update** (outdated tech reference), **Retire** (low quality / stale / cost-asymmetric), **Merge into X** (substantial overlap with another skill)

- Inventory via Glob (`~/.claude/skills/*/SKILL.md` + `learned/*.md`); dependency markdown under `.venv` / `.pytest_cache` is excluded structurally because Glob targets only skill definition files

- Fully inline holistic evaluation — every skill read into one context so cross-skill overlap detection is accurate; no scan scripts and no subagent batching

- Lean verdict ledger: `~/.claude/skills/skill-stocktake/results.json` (`{evaluated_at, skills:{name:{path,verdict,reason,mtime}}}`), updated inline

+ - Usage measurement: bundled `hooks/log-skill-usage.sh` logs `invoke` / `read` / `slash` events to `~/.claude/metrics/skill-usage.jsonl`; `slash` (user-typed /skill, added 2026-07-03) closes the blind spot where command-message injection bypasses the Skill tool and Read

- 4 phases: Inventory → Evaluation → Summary → Consolidation; Improve/Update verdicts hand off to Anthropic's official `skill-creator` skill

## Standard reference

- [Agent Skill specification](https://agentskills.io/specification): the Claude Code skill format used by this repo

- [SkillsMP marketplace](https://agentskills.io/specification): one-step install via `/skills add`

## Improvement hand-off

- Anthropic's official `skill-creator` skill (from [anthropics/skills](https://github.com/anthropics/skills)) is the improvement engine; skill-stocktake hands off Improve/Update verdicts to it. It is not authored by shimo4228.

## Sibling skills

- [llms-txt-writer](https://github.com/shimo4228/llms-txt-writer): writes AI-facing docs optimized for ChatGPT / Perplexity / Gemini citation

- [skill-comply](https://github.com/shimo4228/skill-comply): measures whether agents actually follow skill / rule definitions

- [context-sync](https://github.com/shimo4228/context-sync): audits and fixes project documentation roles

- [search-first](https://github.com/shimo4228/search-first): research-before-coding workflow

- [rules-distill](https://github.com/shimo4228/rules-distill): scan installed skills, extract cross-cutting principles, and distill them into rules

- [learn-eval](https://github.com/shimo4228/learn-eval): extract reusable patterns from sessions, self-evaluate quality, and save to the right location