| 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):
- 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.
- 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):
- Size: SKILL.md body >500 lines OR >50 KB (Tier 2 budget exceeded)
- 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.
- 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:
- 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).
- When to invoke — 3-5 positive trigger phrases
- When NOT to invoke — explicit exclusions (in BODY, never in description frontmatter)
- Rules / decision-criteria — durable rules, kept tight
- Anti-patterns catalog — fingerprint + 1-line fix per pattern (load-bearing skim surface)
- 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)
- Best-practices from current-source research (if Step 2 ran AND findings ADD/CONTRADICT/SUPERSEDE)
@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:
- Rename
<path>/SKILL.md to <path>/SKILL.md.bak
- 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.
- 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).
- 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.
- 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.
- 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?
- 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
- Skip Step 2 current-source research. Exception only for project-internal-only domains.
- Skip Step 4 class-first audit. No exceptions. Sub-agents asked to summarize without audit instructions WILL drop content.
- Allow >85% size reduction without explicit justification. Big reductions ALWAYS drop load-bearing content.
- Delete the original SKILL.md. Always
.bak. Rollback mandatory.
- Silently pick one meaning when same-ID drift exists. Preserve both with disambiguation OR explicit deprecation.
- Drop silent-failure-class entries. High-severity precisely because no dramatic traceback.
- Write
e-v-a-l( (the 6-char Write-hook-blocked substring) literally. Use spaced/dashed/Unicode separator.
- Put negative-trigger keywords in the frontmatter description. Causes keyword-contamination on Claude Sonnet; move to "When NOT to invoke" body section.
- 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.
- 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.
