skill-stocktake
Audits Claude skills and commands for quality, freshness, and overlap. Use when running a skill audit, doing a stocktake of all skills, reviewing which skills to keep or retire, checking for stale or redundant skills, or evaluating skill quality across a project. Supports Quick Scan (changed skills only, 5–10 min) and Full Stocktake (complete review, 20–30 min).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- skill-stocktake
- description
- Audits Claude skills and commands for quality, freshness, and overlap. Use when running a skill audit, doing a stocktake of all skills, reviewing which skills to keep or retire, checking for stale or redundant skills, or evaluating skill quality across a project. Supports Quick Scan (changed skills only, 5–10 min) and Full Stocktake (complete review, 20–30 min).
- allowed-tools
- Read Agent WebSearch Skill Bash(*/quick-diff.sh:*) Bash(*/save-results.sh:*) Bash(*/scan.sh:*)
02 资源文件 5
- 参考文档references/evaluation-guide.md1.3 KB
- 参考文档references/results-schema.md1.3 KB
- 脚本scripts/quick-diff.sh3.3 KB
- 脚本scripts/save-results.sh2.0 KB
- 脚本scripts/scan.sh5.6 KB
03 SKILL.md 正文
skill-stocktake
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.
Core principle: Evaluation is blind — the same checklist applies to all skills regardless of origin. Archive/delete operations always require explicit user confirmation.
Quick Start
- First run (Full Stocktake): invoke
/skill-stocktakefrom your project root — noresults.jsonexists yet, so Full Stocktake runs automatically - Subsequent runs (Quick Scan): invoke
/skill-stocktake— detectsresults.jsonand scans only changed skills - Force full re-scan: invoke
/skill-stocktake full
When to Use
- Periodic quality reviews of your skill library (monthly or after major skill additions)
- Before publishing or sharing skills with a team
- When skills feel stale, overlapping, or confusing to use
- After a batch of new skills has been created
When NOT to Use
- For deep improvement of a single skill — use
/skill-refiner-interactiveinstead - For creating new skills to fill gaps identified by the stocktake — use
skill-developmentinstead - For individual skill editing or quick fixes
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 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 a general-purpose subagent. Substitute [INVENTORY] with the Phase 1 scan table, and [CHECKLIST] with the 4-item evaluation checklist below.
Agent(
subagent_type="general-purpose",
prompt="
Evaluate the following skill inventory against the checklist.
[INVENTORY — paste Phase 1 scan table here]
[CHECKLIST — paste the 4-item checklist below]
Return JSON for each skill:
{ \"verdict\": \"Keep\"|\"Improve\"|\"Update\"|\"Retire\"|\"Merge into [X]\", \"reason\": \"...\" }
"
)
Chunk guidance: Process ~20 skills per subagent invocation. Save intermediate results to results.json (status: "in_progress") after each chunk. After all skills: set status: "completed" and proceed to Phase 3.
Resume detection: If status: "in_progress" is found on startup, resume from the first unevaluated skill.
Evaluation 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
- [ ] Rule compliance verified — invoke `plugin-rulebook` skill for naming, tool-scoping, language, and formatting checks
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 dimensions (holistic AI judgment — not a numeric rubric):
- 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: The reason field must be self-contained and decision-enabling — never write "unchanged" or "superseded" alone. For bad/good examples by verdict type, see references/evaluation-guide.md.
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; to action improvements, invoke
/skill-refiner-interactiveon the target skill - For multiple Improve-verdict skills at once, ask with
AskUserQuestion: "Runenhancement-suggestoragainst the batch of Improve verdicts for one prioritized action plan?" — options "Yes" / "No". If yes, invoke theenhancement-suggestoragent (viaAgent) against the batch instead of a skill-by-skill pass
- Update: present updated content with sources checked
- Check MEMORY.md line count; propose compression if >100 lines
Results File
Results are saved to ~/.claude/skills/skill-stocktake/results.json. See references/results-schema.md for the full JSON schema and field reference.
Key requirement: evaluated_at must be the actual UTC completion time — obtain via date -u +%Y-%m-%dT%H:%M:%SZ. Never use a date-only approximation like T00:00:00Z.
Testing & Validation
After a stocktake run, verify:
- Consistency — re-run Quick Scan on an unchanged skill library; expect "No changes since last run."
- Reason quality — spot-check 3 reasons; confirm each names specific evidence, not vague labels
- Schema integrity — validate
results.jsonhasevaluated_at,mode,batch_progress, andskillskeys - Completeness — confirm
batch_progress.totalequalsbatch_progress.evaluatedwhenstatus: "completed" - Scope accuracy — confirm the Phase 1 summary correctly lists which paths were found and skipped
Quality gates:
- [ ] All Retire / Merge verdicts have explicit user confirmation before any deletion
- [ ]
results.jsonstatusis"completed"before presenting the Phase 3 summary - [ ] WebSearch was used for any skill referencing versioned CLI tools, APIs, or specific flags
Reference Guide
| Resource | Purpose |
|---|---|
references/evaluation-guide.md |
Reason quality examples per verdict type |
references/results-schema.md |
Full JSON schema and field reference for results.json |
plugin-rulebook skill |
Active rule configuration and compliance check (naming, tool-scoping, language, formatting) |
Notes
- Archive / delete operations always require explicit user confirmation
- No verdict branching by skill origin
04 同仓库更多 Skills
demo
Fixture skill used by scripts.marketplace_ci sync tests.
export-demo
Fixture skill used by scripts.marketplace_ci export tests.
work-to-development
Validate an accepted Linear Issue's readiness for implementation (criteria, dependencies, duplicate/existing artifacts) and request governed branch/worktree creation through git-kit:starting-work — recording work-started Git/GitHub evidence and a deliberate Linear Started transition only after Git identity is read back and verified. Use when asked to start work on a Linear issue, begin development for an accepted issue, or prepare an accepted issue for implementation. Never creates a branch directly — always delegates to git-kit.
work-linking
Create and maintain stable cross-system links and authority labels between Notion and Linear records, and detect/repair drift between them. Use when asked to link a Notion record to a Linear record, check for drift between Notion and Linear, or repair a broken/stale link. Repairs only the bounded non-authoritative copy or link — never chooses by newest timestamp, and never creates a reverse-write loop against either system's own authority.
status-and-learning
Produce a dated, explicitly non-live Linear-to-Notion progress summary, or capture an outcome/learning after work completes. Use when asked to summarize progress to Notion, report portfolio status, or capture what was learned from a completed piece of work — not to disposition open follow-up items (see open-item-management for that). Never runs automatically or continuously — every summary is a deliberate, approved snapshot, not a live sync.
repository-gates
Discover, delegate, record, and invalidate this repository's actual Git/GitHub lifecycle gates (pre-commit, pre-push, PR required checks, Codex delta review, review requirements, merge rights) and the repository-policy provider profile that maps governed operations to git-kit. Use when asked what gates apply to this repository, to discover repository policy before starting Wave 2 work, or to check whether prior gate evidence is still valid after new commits. Discovery and delegation only — never executes a gate's own internal logic, and never invents a gate the repository doesn't actually define (in particular, never assumes a "Review Changes" gate exists).