git:20260713.4e5d5b3 to git:20261008.b91a06a

2 added, 2 removed. Audit A to A.

# skill-stocktake

> A Claude Code skill (MIT) that audits all installed Claude skills for quality. It combines a deterministic structural pre-pass, per-skill scrutiny in small fresh-context subagent batches (with unconditional reference verification), and a dedicated cross-skill overlap probe, and applies AI holistic judgment to produce Keep / Improve / Update / Retire / Merge verdicts — never a numeric score. Two modes: full (evaluate everything) and changed (re-evaluate only changed skills, carry the rest forward).

## 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

- Hybrid evaluation split by property, not context length: deterministic checks are code-owned and unconditional (Phase 0 structural pre-pass via skill-health); per-item judgment runs in small fresh-context batches of 10–12 (attention dilutes in a loaded context — a single-context pass returned all-Keep where batches surfaced 12/73 non-Keep); set-level overlap detection is a dedicated probe (description sweep → side-by-side body reads)

- 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

- - 6 phases: Structural pre-pass → Inventory → Per-item scrutiny (parallel batches) → Overlap probe → Synthesis → Consolidation; Improve/Update verdicts hand off to Anthropic's official `skill-creator` skill

+ - 6 phases: Structural pre-pass → Inventory → Per-item scrutiny (parallel batches) → Overlap probe → Synthesis → Consolidation; Improve/Update verdicts hand off to a skill named `skill-creator`

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

+ - A skill named `skill-creator` is the improvement engine; skill-stocktake hands off Improve/Update verdicts to it with the failed screening questions. The author's [skill-creator](https://github.com/shimo4228/akc-cycle/tree/main/skills/skill-creator) ships in the akc-cycle plugin, and the SKILL.md cites its §3 (writing guidance) and §4 (the shared screening questions).

## 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