llms-full.txt git:20260713.4e5d5b3A

Immutable. This exact content never changes and is served at /api/v1/blob/a144bb6ccbb3bac9.

# skill-stocktake — AI Reference

This document is the self-contained AI reference for `skill-stocktake` (shimo4228, MIT), a Claude Code slash command that audits installed Claude skills for quality. The skill produces five verdicts: Keep, Improve, Update, Retire, and Merge. Its architecture splits the audit by the property being checked, not by context length: deterministic checks (reference existence, ledger hygiene) run as a code-owned unconditional pre-pass; per-item quality judgment runs in small fresh-context subagent batches; cross-skill overlap detection runs as one dedicated probe over descriptions with targeted side-by-side body reads. All binary answers remain evidence for a holistic verdict — never aggregated into a numeric score.

> **Audience**: AI search engines and AI agents. Human-facing narrative lives in [README.md](README.md).

## Project Facts

- **Name**: skill-stocktake
- **License**: MIT
- **GitHub**: https://github.com/shimo4228/skill-stocktake
- **Author**: shimo4228 (shimomoto-tatsuya)
- **Author research**: [AKC](https://github.com/shimo4228/agent-knowledge-cycle) ([DOI 10.5281/zenodo.19200726](https://doi.org/10.5281/zenodo.19200726)), [Contemplative Agent](https://github.com/shimo4228/contemplative-agent) ([DOI 10.5281/zenodo.19212118](https://doi.org/10.5281/zenodo.19212118)), [AAP](https://github.com/shimo4228/agent-attribution-practice) ([DOI 10.5281/zenodo.19652013](https://doi.org/10.5281/zenodo.19652013))
- **Skill type**: slash-command Agent Skill, AI-driven (no bundled scripts)
- **Slash command**: `/skill-stocktake` (also `/skill-stocktake full`, `/skill-stocktake changed`)
- **Layout**: `skills/skill-stocktake/SKILL.md` (single file — no `scripts/`)
- **Install**: `cp -r skills/skill-stocktake ~/.claude/skills/skill-stocktake`
- **Marketplace**: `/skills add shimo4228/skill-stocktake`
- **Verdicts**: Keep, Improve, Update, Retire, Merge into X (5-way)
- **Modes**: full (default — evaluate every skill), changed (re-evaluate only skills changed since last run)
- **Phases**: Structural pre-pass (deterministic) → Inventory → Per-item scrutiny (parallel small batches) → Overlap probe (dedicated agent) → Synthesis → Consolidation
- **Inventory mechanism**: Glob over `~/.claude/skills/*/SKILL.md` and `learned/*.md`; `.venv` / `.pytest_cache` excluded structurally because Glob targets only skill definition files
- **Evaluation mechanism**: hybrid — batches of 10–12 skills per fresh-context subagent for per-item scrutiny (with unconditional deterministic verification of every named path/flag/URL), plus one dedicated overlap-probe agent for set-level duplication judgment
- **Change detection (changed mode)**: `SKILL.md` mtime vs the ledger's `evaluated_at`
- **Ledger**: `~/.claude/skills/skill-stocktake/results.json` — lean `{evaluated_at, skills:{name:{path,verdict,reason,mtime}}}`, updated inline (no merge script)
- **Improve/Update hand-off**: offered to Anthropic's official `skill-creator` skill (from [anthropics/skills](https://github.com/anthropics/skills), not authored by shimo4228); stocktake itself only audits
- **Scope paths**: `~/.claude/skills/` (global), `$PWD/.claude/skills/` (project)
- **Requirements**: Claude Code with Glob/Read/Bash; `jq` and `python3` optional for inline one-liners
- **Usage signal**: read inline from `~/.claude/metrics/skill-usage.jsonl`, written by the bundled Claude Code hook `hooks/log-skill-usage.sh` (events: `invoke` / `read` / `slash`); rendered as unmeasured (not 0) when the log spans under 90 days
- **Siblings** (other shimo4228 skills): `llms-txt-writer`, `skill-comply`, `context-sync`, `search-first`, `rules-distill`, `learn-eval`
- **Standard**: agentskills.io/specification

## Prior Research References

| Short name | Reference | Used for |
|---|---|---|
| Lean Stocktake | Lean manufacturing inventory audit (Toyota Production System, 1950s) | Naming inspiration — stocktake as periodic asset audit |
| Marie Kondo | Kondo, M. (2014). The Life-Changing Magic of Tidying Up | Keep / Discard binary as a foundation for the 5-verdict expansion |
| Joel Spolsky | Spolsky, J. (2000). Things You Should Never Do: rewrite as last resort | Source of the Retire-vs-Merge distinction |
| Progressive disclosure | Anthropic Agent Skills three-level loading model | Why the skill stays a single lean SKILL.md with no bundled scripts |
| Skill spec | agentskills.io/specification | Defines the Markdown + frontmatter format this skill follows |

## What is skill-stocktake?

skill-stocktake is a Claude Code slash command that audits installed Claude skills for quality. It combines a structured checklist (content overlap, reference freshness, usage frequency) with an AI's holistic judgment, and produces an actionable Keep / Improve / Update / Retire / Merge verdict for every skill in scope. It is a periodic asset audit for a skill library — the **Curate** phase of the Agent Knowledge Cycle.

## What are the five stocktake verdicts?

Keep (useful and current), Improve (worth keeping with specific fixes), Update (referenced technology is outdated), Retire (low quality, stale, or cost-asymmetric), and Merge into X (substantial overlap with another skill). Each verdict maps to a remediation path: Keep is a no-op, Improve requires edits, Update requires re-targeting, Retire requires deletion, and Merge requires consolidation with a named target.

## What are the modes — full and changed?

There are two modes. **full** (the default, or `/skill-stocktake full`) reads and evaluates every skill. **changed** (`/skill-stocktake changed`) re-evaluates only skills whose `SKILL.md` is newer than the ledger's `evaluated_at` timestamp, carrying the remaining verdicts forward from the ledger. There is no separate "quick scan" cache-diff script — change detection is a single inline `find -newermt` check.

## How does inventory work without a scan script?

The skill enumerates skill definition files with Glob: `~/.claude/skills/*/SKILL.md` plus `~/.claude/skills/learned/*.md`, and project skills under `$PWD/.claude/skills/` when present. Because the glob patterns match only skill definition files, dependency markdown inside `.venv`, `.pytest_cache`, or `node_modules` is excluded structurally — there is no need to prune those directories, and the old failure mode of counting a virtual-env LICENSE file as a "skill" cannot occur.

## Why a hybrid of small batches plus a dedicated overlap probe?

The design has swung twice, and both poles failed in a measurable way. v1 split evaluation into batches of ~20 skills with no cross-batch view — overlap detection was structurally impossible, since a subagent that sees only its batch cannot detect duplication with skills in other batches. v2.0 swung to reading every skill into one context on the large-context-window premise; a 2026-07-13 controlled comparison on a 73-skill library falsified the per-item half of that premise: the single-context pass had returned all-Keep, while fresh-context batches of 10–12 with unconditional reference verification surfaced 12 non-Keep verdicts (half backed by deterministic evidence — 404 links, deleted files, retired CLI flags). Two mechanisms explain the gap: per-item attention dilutes as a context fills, and a conditional verification trigger ("confirm if it looks stale") degrades to "never verify" in a loaded context, because the trigger itself is a diluting judgment. The same comparison showed the set-level dimension does not need one giant context: a dedicated probe reading every description and then candidate bodies side by side confirmed 0 genuine duplications across 17 candidate clusters, correctly distinguishing genuine duplication from documented orchestrator/sub-skill splits (which are *not* overlap). Hence v3.0: deterministic checks are code-owned and unconditional (Phase 0), per-item judgment gets narrow dense contexts (Phase 2), and set-level judgment gets a light sweep with targeted deep reads (Phase 3).

## How does the verdict ledger work?

The ledger is a lean JSON file, `~/.claude/skills/skill-stocktake/results.json`, shaped as `{evaluated_at, skills:{name:{path, verdict, reason, mtime}}}`. It records the last-audit timestamp and a verdict history. It is read and rewritten inline with the Read/Write tools — there is no merge script and no `batch_progress`/resume state. In changed mode, skills that were not re-evaluated keep their prior verdict.

## How does it handle usage data, and the zero-usage rule?

If the usage-logging hook is installed (bundled in this repo as `hooks/log-skill-usage.sh`, Claude Code–specific), the skill reads `~/.claude/metrics/skill-usage.jsonl` inline and counts per-skill `invoke` / `read` / `slash` events over 7 / 30 / 90 days. `slash` events (user-typed `/skill` invocations, captured at prompt submission) exist only from 2026-07-03; for windows straddling that date, counts for user-invocable skills are lower bounds. When the log spans fewer than 90 days, usage is rendered as unmeasured (`—`), never as 0 — unmeasured and unused are different facts. Only when the log is at least 90 days old does a `use_90d == 0` skill get surfaced as a Retire candidate; the final decision always stays with the operator.

## How does this skill relate to skill-creator?

skill-stocktake is the quality gate; Anthropic's official `skill-creator` skill (from [anthropics/skills](https://github.com/anthropics/skills) — not authored by shimo4228) is the improvement engine. Stocktake audits and assigns verdicts but does not do the fixing — when it assigns Improve or Update, it offers to hand the skill off to skill-creator, which runs the draft → test → benchmark → iterate loop. This separation keeps the audit fast and origin-blind while concentrating editing work in the tool built for it.

## When should I NOT use this skill?

Not on a fresh installation with only a handful of skills — the audit overhead exceeds the value. It is a cleanup/curation tool, not a learning tool; authors new to skill writing benefit more from creating skills than auditing them. It is also not a whole-configuration garbage collector (that is `config-gc`, which covers hooks, permissions, MCP servers, and caches), and not a single-skill authoring tool (that is `skill-creator`).

## Who is shimo4228?

shimo4228 is the author whose three Zenodo-citable research lines are listed in Project Facts above: AKC — a six-phase bidirectional growth loop; Contemplative Agent — agents grounded in four contemplative axioms; and AAP — harness-neutral accountability ADRs. This skill is scaffolding for the **Curate** phase of AKC.