# Use Skill Review

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

- Skill: `oimiragieo/use-skill-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/use-skill-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/use-skill-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/use-skill-review

---


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

```powershell
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?"

```bash
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/` |
| **Bloated description starving the fleet** 🚨 | One skill's description is 1KB+ while other skills stop auto-triggering | Listing-budget class: all descriptions share ~1% of the context window; oversize descriptions push least-used skills to names-only silently. `/doctor` shows which. Trim to <600 chars; `disable-model-invocation: true` for manual-only skills |
| **Same-ID drift silently picking one meaning** | .bak has F4 defined twice; new SKILL.md only has one | Preserve BOTH with `-orig` / `-actual` / `-shell` suffix |
| **Silent-failure-class entries dropped** | Entries with "silently" / "no traceback" / "appears to work" not in new | Run extra grep; surface each with 🚨 marker |
| **Literal substring blocked by Write hook** | Documenting the 6-char `e-v-a-l` + open-paren substring triggers the hook itself | Use spaced/dashed/Unicode separator anywhere this pattern is documented |
| **Premature sub-agent kill** | Sub-agent silent >30 min — assumed stuck — `TaskStop` fired | Check `Get-Process` for CLI binary (codex/cursor/gemini) FIRST; CLI dispatch typically takes 5-15 min |
| **Replacing original instead of .bak'ing** | Used `Write` to overwrite SKILL.md directly | Always `Move-Item SKILL.md SKILL.md.bak -Force` FIRST |
| **Deferred-to-.bak without explicit pointer** | New SKILL.md just shorter, no mention of .bak | Last section MUST be "Full per-entry rationale → `@SKILL.md.bak`" with metrics |
| **Research findings buried without "ADD/CONTRADICT/SUPERSEDE" filter** | Section includes findings that merely CONFIRM the .bak (dead context) | Include ONLY findings in those three classes; one-line confirmations |
| **No regression check on adjacent skills** (NEW v2) | After refresh, didn't test that other skills still route correctly | Test 2-3 trigger prompts on adjacent skills; description-keyword collision can silently degrade them |
| **Versioning in SKILL.md body** | `## v1.0 → v1.1 changelog` style entries | Move to marketplace.json; SKILL.md is timeless content. Exception: load-bearing methodology receipts that explain WHY a rule exists |

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