use-skill-review

name	use-skill-review
description	Use when auditing, refreshing, or summarizing an existing SKILL.md — it exceeds ~5000 tokens or 500 lines, hasn't been refreshed in >14 days despite high usage, carries stale model/tool/CLI references, or skill summarization is about to be delegated to a sub-agent. Also use when a skill refresh dropped content or a condensed skill stopped triggering. Sibling of superpowers:writing-skills (that one CREATES new skills; this one refreshes existing ones).
model	opus

use-skill-review — audit + current-source refresh + summarize an existing SKILL.md

Three load-bearing disciplines (in order): (1) fresh-literature research using available web tools and authoritative sources, (2) summarize with .bak preservation, (3) MANDATORY class-first audit-against-.bak step. Skipping any one ships gaps silently. Anchored by two prior large-skill condensations that each dropped real content on the first pass and only recovered it via the class-first audit, plus this skill's own v1 → v2 refresh (folded in 11 external best-practice patterns).

Three-tier progressive disclosure (multi-vendor consensus 2026)

This is the load-bearing structural constraint, validated across Anthropic / Google ADK / Microsoft Agent Framework / agentskills.io spec:

Tier	Budget	What lives here
Tier 1 (frontmatter)	~100 tokens, loaded at startup	name + description (spec caps description alone at 1,024 chars; Claude Code truncates description+when_to_use combined at 1,536 chars in the listing)
Tier 2 (SKILL.md body)	<5000 tokens recommended (≤500 lines per Anthropic)	Rules, anti-patterns, dispatch template — FRONT-LOAD the load-bearing content
Tier 3 (references/)	unbounded, on demand	references/full.md + helper scripts + assets (legacy skills use @SKILL.md.bak — same mechanics, worse discoverability; prefer references/ for new refreshes)

Two silent failure classes (corrected 2026-07-03 per Claude Code docs + issues #64606/#59921):

1. Listing-budget drop (Tier 1): the skill LISTING has a budget of ~1% of the context window (~8,000 chars at 200k; skillListingBudgetFraction). When the fleet's combined descriptions overflow it, least-invoked skills are silently reduced to names-only and stop auto-triggering. /doctor reports which. Mitigations: trim bloated descriptions fleet-wide (one 10KB description eats the whole shared budget), set disable-model-invocation: true on manual-only workflow skills (removes their description from the listing entirely), raise skillListingBudgetFraction.
2. Compaction truncation (Tier 2): the body is NOT pruned at load time — the full file loads on activation. But after auto-compaction, Claude Code re-attaches only the FIRST 5,000 tokens of each invoked skill (25,000-token combined cap, most-recent first). A >5k-token body silently loses its tail in long sessions. Keep bodies under ~5k tokens AND put the most load-bearing rules first; re-invoke the skill after compaction to restore it.

Empirics (SkillsBench, arXiv 2602.12670): compact skills (+18.9pp) beat comprehensive documentation (+5.7pp) ~4×; curated skills average +16.2pp but 16/84 tasks went NEGATIVE — a skill is not free; each one added can degrade routing for the others.

When to invoke

Three independent triggers (any one fires):

1. Size: SKILL.md body >500 lines OR >50 KB (Tier 2 budget exceeded)
2. Age + usage: last refresh >30 days AND skill is high-usage-rank (top 20% of invocations in ~/.claude/projects/.../session-logs). High-usage skills accumulate gotcha debt faster — Hermes-pattern.
3. Delegation: about to dispatch summarization to sub-agent (codex/cursor/gemini/droid); this skill ensures current-source research + class-first audit are in the spec.

When NOT to invoke

• SKILL.md already <200 lines AND <20 KB (already within Tier 2 budget)
• Rapid-evolution skill (weekly+ changes) — defer summarization until stable
• Skill is non-trivial code templates that must execute verbatim
• Goal is CREATE not REFRESH — use superpowers:writing-skills instead

The 7-step ritual (in order, ALL mandatory)

Step 1 — Rename original to .bak (never delete)

Move-Item ~/.claude/skills/<name>/SKILL.md ~/.claude/skills/<name>/SKILL.md.bak -Force

Preserves full rationale. Rollback: Move-Item SKILL.md.bak SKILL.md -Force.

Step 2 — Research the skill's topic for current best practices

Use the available web-research tools and prefer authoritative current sources. Compose a 3-4 stream search:

• Skill's domain best practices (last 90-180 days)
• Known competitors / published frameworks in the same surface
• Counter-evidence (where the .bak's rules contradict newer literature)
• Cross-vendor patterns (Anthropic / Hermes / Google ADK / Microsoft / agentskills.io)

Cover general fresh literature, multi-source synthesis, primary research papers, and original implementation repositories. Use whichever web tools are available in the current harness; do not assume a vendor-specific search surface.

Report sourced findings as a structured artifact. Critical (added v2 per Perplexity): include in the new SKILL.md ONLY findings that ADD a new rule, CONTRADICT an existing rule, or SUPERSEDE an existing rule. Findings that merely CONFIRM the .bak's content are dead context — omit or one-line them.

When to skip Step 2 (rare): project-internal-only domains with no external best-practices analog (e.g. a catalog of project-specific known failure modes with no public literature to research). Note "Step 2 skipped: project-internal-only" in the new SKILL.md.

Step 3 — Write NEW concise SKILL.md (combine .bak audit + current-source findings)

Required sections, in order:

1. YAML frontmatter — name (must exactly match parent directory name for portability; Claude Code tolerates mismatch and the directory wins), description (≤1,024 chars per spec; description+when_to_use combined truncated at 1,536 in the Claude Code listing; positive "Use when" triggers only, unique discriminator in the first ~20 words, NEVER a workflow summary and NEVER negative DO NOT USE FOR: keywords — they inject the very keywords that misroute Sonnet-class routing; if disambiguating from a sibling skill, NAME the other skill instead of repeating its keywords). Optional Claude Code fields (verified 2026-07-03; single-vendor, all optional): when_to_use, model:, effort:, context: fork + agent:, disable-model-invocation: true (also removes the description from the listing = zero budget cost — use for manual-only workflows), user-invocable: false, allowed-tools/disallowed-tools, paths: (glob-scoped auto-activation), argument-hint, hooks, shell. depends: does NOT exist in any spec — never emit it (corrected 2026-07-03; v2 wrongly listed it).
2. When to invoke — 3-5 positive trigger phrases
3. When NOT to invoke — explicit exclusions (in BODY, never in description frontmatter)
4. Rules / decision-criteria — durable rules, kept tight
5. Anti-patterns catalog — fingerprint + 1-line fix per pattern (load-bearing skim surface)
6. Load-bearing methodology receipts (renamed from "Recent updates" per v2 — Anthropic canonical guidance says SKILL.md is timeless content; receipts pass IF they document WHY a rule exists, not WHAT changed)
7. Best-practices from current-source research (if Step 2 ran AND findings ADD/CONTRADICT/SUPERSEDE)
8. @SKILL.md.bak lazy-load reference with line/KB metrics

Target: 30-50% reduction vs original. Going >85% reduction almost always drops load-bearing content (anchor: a first-pass 88% reduction on a prior large skill silently dropped 15 entries, caught only by the audit step below).

Step 4 — MANDATORY class-first audit rubric (the load-bearing discipline)

Hermes-pattern: rubric-based grading per entry, NOT free-form "did I cover this?"

grep -n '^## \|^### \|^| [A-Z][0-9]\|^\* \*\*[A-Z]\d' SKILL.md.bak

For EACH heading / entry / row found in .bak, classify into ONE of four classes:

Class	What it means	Action
LOAD-BEARING	Operating-surface rule, active anti-pattern, current receipt	Verify covered in new SKILL.md; patch back if missed
STALE	Date-stamp >90 days, may no longer be true	Verify against authoritative current sources or an empirical check; if stale, mark [DEPRECATED <date>: <reason>]
DUPLICATE-ID	.bak has same ID with two meanings (F4 + F4-orig, J1-J6 has two sets)	Preserve BOTH in new SKILL.md with disambiguation suffix (-orig, -actual, -shell)
SILENT-FAILURE 🚨	Entry contains "silently", "no traceback", "appears to work", "degrades to baseline"	MUST surface in new SKILL.md with 🚨 marker; higher severity than crashes

Skipping this step IS the failure mode. Sub-agents asked to summarize default to aggressive cuts; the rubric is the gate.

Step 5 — Same-ID drift detection (subset of Step 4 DUPLICATE-ID class)

Already encoded in Step 4 rubric. Quick reference: when .bak has duplicate IDs, the disambiguation suffix is mandatory and a "Known duplicate-ID drift in @SKILL.md.bak" note explains the disambiguation.

Step 6 — Silent-failure-class flag (subset of Step 4 SILENT-FAILURE class)

Already encoded in Step 4 rubric. Plus one external silent-failure now banked: skill body >5000 tokens may be silently pruned by harness compaction mid-conversation (agentskills.io spec). Keep body under 5000 tokens.

Step 7 — Cross-link audit + regression check

After the new SKILL.md is finalized:

• Update docs/skill_index.md (or equivalent project index) — link to NEW SKILL.md, note .bak preservation, update last-refresh date
• Check files that reference this skill (grep -r "skill-name" .claude/agents/ docs/ CLAUDE.md) — verify references still resolve
• If skill is meta-skill-bundled, verify the bundle still composes correctly
• NEW v2 (Perplexity pattern): regression-check — does the new condensed SKILL.md trigger correctly on the same prompts the old .bak was designed for? Adding/refreshing a skill can silently degrade adjacent skill routing via description-keyword collision. Test 2-3 historical trigger prompts.

Anti-patterns this skill catches

Anti-pattern	Fingerprint	Fix
First-pass over-aggression	Summarized file <15% of original size	Audit step ALWAYS — first pass typically drops 10-15 load-bearing entries
Skipping current-source research	New SKILL.md identical structure to .bak, just shorter	Step 2 mandatory unless project-internal-only domain
Sub-agent default summarization	Dispatch prompt lacks current-source research + class-first audit requirements	Spec MUST include all 7 steps verbatim
Description >1,536 chars	combined description + when_to_use exceeds hard cap	Truncate; positive WHEN: phrases only; offload extended content to body
Negative-trigger keywords in description	DO NOT USE FOR: X, Y, Z in frontmatter	Causes keyword-contamination on Claude Sonnet (spboyer Feb 2026); move negative triggers to "When NOT to invoke" body section
Name vs directory mismatch	name: foo in frontmatter but parent dir is bar/	Directory wins on disk; either rename dir or sync name: field — universal portability gotcha
YAML block-scalar description 🚨	description: > or description: | with indented continuation lines	Claude Code's frontmatter parser doesn't support block scalars — the description renders EMPTY and the skill silently never auto-triggers (2026-07-03: 17 skills found dead this way). Always a single-line double-quoted value
UTF-8 BOM before frontmatter 🚨	File starts with \xEF\xBB\xBF---	Frontmatter fails to parse; skill shows bare --- as its description and never triggers. Strip the BOM (seen on a skill refreshed via a Windows editor)
Skill body >5000 tokens 🚨	SKILL.md body exceeds Tier 2 recommendation	Compaction-truncation class: full body loads on activation, but after auto-compaction only the FIRST 5k tokens per skill (25k combined) are re-attached — the tail silently vanishes in long sessions. Front-load load-bearing rules; move overflow to references/

Sub-agent dispatch template (copy verbatim into spec)

When delegating to codex/cursor/gemini/droid, the spec MUST include:

1. Rename <path>/SKILL.md to <path>/SKILL.md.bak
2. Use available web-research tools to research the skill's topic from authoritative current sources. Report 4-6 most-relevant sources + 2-3 best-practices to incorporate + any rules .bak contradicts. SKIP only if domain is project-internal-only.
3. Write a NEW <path>/SKILL.md (target 30-50% of original) with sections: frontmatter (name matches directory; description+when_to_use ≤1,536 chars; positive WHEN: phrases only; optional model: / effort: / context: fork / disable-model-invocation: true / paths: — NEVER depends:, it doesn't exist), when-to-invoke, when-NOT (body only, never description), rules, anti-patterns catalog, load-bearing methodology receipts, best-practices from current-source research (only ADD/CONTRADICT/SUPERSEDE findings), @SKILL.md.bak lazy-load reference. Body MUST be <5000 tokens (Tier 2 cap, silent-prune class above this).
4. MANDATORY CLASS-FIRST AUDIT (Hermes-pattern): grep .bak for ALL headings + entry IDs. For EACH item, classify into LOAD-BEARING / STALE / DUPLICATE-ID / SILENT-FAILURE 🚨. Verify LOAD-BEARING entries covered; preserve DUPLICATE-ID with suffix; surface SILENT-FAILURE with 🚨. Report any missing entries with .bak line numbers.
5. Avoid Write-hook-blocked substrings: if .bak documents a literal pattern the Write tool blocks (e.g. the 6-char "e-v-a-l" + open-paren), use spaced/dashed/Unicode separator in the new SKILL.md.
6. Regression check (Perplexity-pattern): test 2-3 historical trigger prompts against the new SKILL.md description — does it still activate? Does adjacent skill routing degrade?
7. Report back: (a) old size → new size + Tier 2 token check, (b) current-source findings summary (ADD/CONTRADICT/SUPERSEDE only), (c) per-class audit table (LOAD-BEARING covered / STALE deprecated / DUPLICATE-ID disambiguated / SILENT-FAILURE 🚨 surfaced), (d) regression check result.

Without explicit Steps 2 + 4 + 6 in the spec, sub-agents default to Step 1+3 only and ship gaps + stale content + adjacent-skill regression.

Load-bearing methodology receipts

These document WHY each step is mandatory, not WHAT changed in versions:

Anchor #1 — a large project-specific known-failures catalog: 125 KB → 14 KB first-pass (88% reduction, TOO AGGRESSIVE) → 20 KB post-audit (84%, correct). Audit caught 15 missed entries across several distinct failure classes. Without Step 4 class-first audit, all 15 would have shipped lost.

Anchor #2 — a large driver-authoring runbook: 108 KB → ~15 KB first-pass → 22 KB post-audit (80%, correct). Audit caught 8 missed sections (an env-export step, a platform-specific stub workaround, a path-mapping gotcha between two dev environments, template-loading discipline, a pre-flight data check, a cross-link audit checklist, a deprecation note, and a prior incident writeup).

Anchor #3 — use-skill-review v1 → v2 (2026-05-24, this skill on itself): v1 was 16 KB / 151 lines. Step 2 research surfaced 11 external best-practice patterns: 3 Hermes patterns (Autonomous Curator usage-rank trigger, class-first audit rubric, per-skill model frontmatter), 5 Anthropic spec patterns (3-tier progressive disclosure, 1,536-char description cap, name-vs-directory rule, context: fork field, disable-model-invocation: true field), 3 cross-vendor patterns (skill-body silent-prune class, regression-check on adjacent skills, "write evals before the skill"). All folded into v2 here.

Sibling skills

• superpowers:writing-skills — CREATES new skills from scratch; this skill AUDITS/REFRESHES/SUMMARIZES existing ones
• Available web-research tools — Step 2 current-source research surface
• When dispatching this skill to a sub-agent, verify the spec is complete and an audit trail is preserved before trusting the result
• chat-archeologist — useful before Step 2: search prior sessions for "did we already research this skill's domain?"

What this skill REFUSES to do

1. Skip Step 2 current-source research. Exception only for project-internal-only domains.
2. Skip Step 4 class-first audit. No exceptions. Sub-agents asked to summarize without audit instructions WILL drop content.
3. Allow >85% size reduction without explicit justification. Big reductions ALWAYS drop load-bearing content.
4. Delete the original SKILL.md. Always .bak. Rollback mandatory.
5. Silently pick one meaning when same-ID drift exists. Preserve both with disambiguation OR explicit deprecation.
6. Drop silent-failure-class entries. High-severity precisely because no dramatic traceback.
7. Write e-v-a-l( (the 6-char Write-hook-blocked substring) literally. Use spaced/dashed/Unicode separator.
8. Put negative-trigger keywords in the frontmatter description. Causes keyword-contamination on Claude Sonnet; move to "When NOT to invoke" body section.
9. Allow new SKILL.md body to exceed 5000 tokens. Compaction-truncation class; front-load the load-bearing rules and move overflow to references/full.md (preferred — documented pattern, linter-friendly, one level deep, with a TOC + grep patterns for >10k-word references) or legacy @SKILL.md.bak.
10. Skip the regression check. Adjacent skills can silently lose routing after a refresh; 2-3 trigger-prompt test is the cheap gate.

Quick reference (the 7-line checklist)

□ 1. Move-Item SKILL.md SKILL.md.bak -Force
□ 2. Research the skill's topic using authoritative current sources
□ 3. Write NEW concise SKILL.md (≤5000 tokens body, ≤1,536 chars description, positive WHEN: only, name matches directory)
□ 4. AUDIT (Hermes class-first rubric): classify each .bak entry as LOAD-BEARING / STALE / DUPLICATE-ID / SILENT-FAILURE 🚨; verify coverage
□ 5. Detect same-ID drift, preserve both meanings with suffix
□ 6. Surface silent-failure-class entries with 🚨 marker (including >5000-token body class)
□ 7. Update cross-references + regression-check adjacent skills via trigger prompts

Full per-step rationale + first-version receipts → @SKILL.md.bak

v1 of this skill (16 KB / 151 lines, 2026-05-24 ~12:36 EDT) lives at SKILL.md.bak. v2 (this file, 2026-05-24 ~13:20 EDT, post-self-review) folds in 11 external patterns surfaced by Step 2 research + the 3 self-contradictions the audit caught (deprecated vendor-specific tool names, "Recent updates" renamed to "Load-bearing methodology receipts", research-findings ADD/CONTRADICT/SUPERSEDE filter). Lazy-load @SKILL.md.bak only for first-version-format archeology.