optimize-skill-activation
/optimize-skill-activation
Audit installed skills and right-size each one's activation mode — slash-only, model-invocable (name+description in context), or eager-loaded (full body up front). Preview changes, then rewrite each SKILL.md frontmatter. Use when the user says "optimize skills", "right-size skills", "reduce skill tokens", "audit skill activation", or "/optimize-skill-activation".
- Author
- zcaceres ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 01.09.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 01.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/scan-invocations.sh
What it does and when to use it
Audit installed skills and right-size each one's activation mode — slash-only, model-invocable (name+description in context), or eager-loaded (full body up front). Preview changes, then rewrite each SKILL.md frontmatter. Use when the user says "optimize skills", "right-size skills", "reduce skill tokens", "audit skill activation", or "/optimize-skill-activation".
Triggers from the description
Original author description
Audit installed skills and right-size each one's activation mode — slash-only, model-invocable (name+description in context), or eager-loaded (full body up front). Preview changes, then rewrite each SKILL.md frontmatter. Use when the user says "optimize skills", "right-size skills", "reduce skill tokens", "audit skill activation", or "/optimize-skill-activation".
How it works
- Mental model
- When to run
- Step 1 — detect skill installation roots
- Step 2 — parse each SKILL.md
- Step 3 — measure how each skill is actually invoked
- Step 4 — classify each skill
- Step 5 — preview and confirm
- Step 6 — write the changes
- Step 7 — report
- Safety rails
SKILL.md preview
---
name: optimize-skill-activation
disable-model-invocation: true
description: Audit installed skills and right-size each one's activation mode — slash-only, model-invocable (name+description in context), or eager-loaded (full body up front). Preview changes, then rewrite each SKILL.md frontmatter. Use when the user says "optimize skills", "right-size skills", "reduce skill tokens", "audit skill activation", or "/optimize-skill-activation".
---
# optimize-skill-activation
Most of the context budget skills cost is paid up front — every installed skill's
`name` + `description` lives in the system prompt of every session. Skills that
should only fire on explicit user intent shouldn't burn that budget; skills the
agent must honor on every turn shouldn't be hidden behind a `/slash` no one
remembers to type. This skill audits what's installed, classifies each skill by
how it's actually used, and rewrites the frontmatter to match.
Inspired by `optimize-permissions` — same UX, same preview-then-confirm shape.
## Mental model
Claude Code skills load in three tiers (progressive disclosure):
1. **Metadata** — `name` + `description` always pinned in the system prompt
(~100 words per skill). The cheap tier.
2. **SKILL.md body** — loaded only when the skill activates (~thousands of
words). The expensive tier — paid per activation.
3. **Bundled resources** — `references/`, `scripts/` loaded on demand inside
the activated skill's flow. Effectively free until used.
There are three knobs that change *when* tier 2 fires:
| Mode | Frontmatter / hook | Tier-1 cost | Tier-2 trigger |
|--------------------|--------------------------------------------------|-------------|-----------------------------|
| Slash-only | `disable-model-invocation: true` | name+desc | user types `/skill-name` |
| Model-invocable | *(default)* | name+desc | model decides from context |
| Eager-loaded | `SessionStart` hook injecting SKILL.md body | full body | always; no trigger needed |
Mapping skills to the right mode is a judgment call about three things:
*intent strength* (is the user's request always unambiguous?), *blast radius*
(what happens if the model invokes it wrongly?), and *always-relevant*
(should it shape every turn, or only when invoked?).
## When to run
Trigger phrases: *optimize skills*, *right-size skills*, *reduce skill tokens*,
*audit skill activation*, *which skills should be slash-only*,
*which skills should always load*, or `/optimize-skill-activation`.
If the user has fewer than ~3 skills installed, say so and stop — there's
nothing meaningful to optimize.
## Step 1 — detect skill installation roots
Probe in order; record every root that contains skills:
| Scope | Path | Notes |
|-----------|-----------------------------------------------|------------------------------------------------------|
| User | `~/.claude/skills/*/SKILL.md` | applies to every project |
| Project | `<repo>/.claude/skills/*/SKILL.md` | project-local; usually checked into git |
| Plugin | `~/.claude/plugins/*/skills/*/SKILL.md` | shipped via plugins; do NOT rewrite — read-only |
```bash
find ~/.claude/skills -maxdepth 2 -name SKILL.md 2>/dev/null
find .claude/skills -maxdepth 2 -name SKILL.md 2>/dev/null
```
Skip plugin-managed skills — they're owned by their plugin and will be
overwritten on update. Surface them in the report as "managed by `<plugin>`,
not editable here" so the user knows why they're excluded.
If both user and project scopes have skills, ask which to audit (multiSelect is
fine). If only one has skills, target it silently.
## Step 2 — parse each SKILL.md
For each `SKILL.md`, extract:
- `name` (frontmatter)
- `description` (frontmatter)
- `disable-model-invocation` (frontmatter; default `false`)
- `hooks:` (frontmatter — note `SessionStart`, `PreToolUse`, etc.)
- Body word count (proxy for tier-2 cost)
- Whether the body references `/$name` as a usage example (signal of slash-intent)
A thin parser is fine — frontmatter is YAML between `---` fences.
## Step 3 — measure how each skill is actually invoked
Read the most recent ~20 Claude Code transcripts from
`~/.claude/projects/<encoded-cwd>/*.jsonl` (and widen to all projects if the
user says "across everything"). For each skill, count:
- `slash` — user explicitly typed `/skill-name`
- `auto` — model invoked via the Skill tool without an explicit slash
- `never` — installed but never used in the sample
A skill that's *only ever* invoked via slash is a strong candidate for
slash-only mode. A skill that's *only ever* invoked by the model is a candidate
for model-invocable. A skill that fires on nearly every session is a candidate
for eager loading. A skill that's never used is a candidate for removal — flag
it, don't auto-uninstall.
`scripts/scan-invocations.sh` is a thin grep helper; parsing inline is usually
fast enough.
## Step 4 — classify each skill
Combine signals from Steps 2–3 with the heuristics below.
### Recommend slash-only (`disable-model-invocation: true`)
- **Destructive or expensive workflows** — anything that pushes, deletes,
publishes, sends, charges, or kicks off long-running compute. The user
should always be the one to start it.
- **Strongly user-intent gated** — `/pr`, `/decompose`, `/acid-trip`,
`/zoom`, `/roast`. The whole point is the user explicitly asking for it.
- **Workflows whose description would over-trigger** — if the description
contains broad nouns like "code", "files", "review" the model will pull it
in too often.
- **Niche / rarely used** — installed but invoked <=1x in the transcript
sample, *and* always via slash.
### Recommend model-invocable (default — no special frontmatter)
- **Clear, specific trigger phrases in the description** — "use when the user
says X, Y, or Z" with phrases no other skill would match.
- **Idempotent, read-only, or contained** — running it accidentally costs at
most a few tool calls; doesn't mutate shared state.
- **Mixed invocation pattern** — sometimes the user remembers the slash,
sometimes the model picks it up. Default mode supports both.
### Recommend eager-loaded (`SessionStart` hook -> inject SKILL.md body)
- **Always-relevant constraints** — coding standards, repo conventions, a
custom commit-message format, an opinionated PR template.
- **Tiny body** — a few hundred words at most. Eager-loading a 5k-word skill
wastes the budget you're trying to save.
- **Frequent re-activation** — if the model invokes it on most turns anyway,
paying once at session start beats paying per activation.
See `references/activation-modes.md` for the exact frontmatter / hook shapes
and the failure modes of each.
### Recommend removal / archive (flag only — don't auto-delete)
- **Never invoked across all sampled transcripts** *and* installed >30 days.
- **Deprecated** — body opens with "Deprecated — use X instead."
- **Duplicate** — name + description nearly identical to another installed
skill (common after migrating skills between repos).
Removal is destructive and irreversible. Always require explicit user
confirmation per-skill; never bundle removals into the auto-apply pass.
## Step 5 — preview and confirm
Render a clean preview before writing. Group by recommended action, show the
current -> proposed mode, and a one-line "seen N times via X" rationale:
```
Proposed skill activation changes (~/.claude/skills/)
-> Make slash-only:
~ checkpoint default -> disable-model-invocation: true
seen 12x — always via slash, never auto
~ acid-trip default -> disable-model-invocation: true
destructive: writes files; intent-gated
-> Make eager-loaded (SessionStart hook):
~ commit-style default -> +SessionStart hook
seen 18x across 14 sessions; body is 240 words
-> Leave as-is (model-invocable, well-tuned):
= optimize-permissions
= review-code
? Flag for removal (you'll confirm each):
? old-prototype-skill never invoked in 20 sessions; installed 90 days ago
```
Use **AskUserQuestion** with `multiSelect: true` for the final cut. Default
the "leave as-is" group already-applied (no checkbox needed); default the
"slash-only" and "eager-loaded" tiers checked; default "flag for removal"
unchecked. Always offer "edit list manually" as an escape hatch.
If a skill currently has `disable-model-invocation: true` and the
recommendation is "leave as-is", silently skip it from the preview to keep
the noise down.
## Step 6 — write the changes
For each accepted recommendation:
1. **Back up the SKILL.md** before editing:
```bash
cp <path>/SKILL.md <path>/SKILL.md.bak.$(date +%s)
```
2. **Slash-only**: add `disable-model-invocation: true` to the frontmatter
YAML block. If a hook is set up that depends on auto-invocation, warn —
don't silently break it.
3. **Eager-loaded**: append (don't replace) a `hooks:` block to the
frontmatter with a `SessionStart` entry, *and* drop a
`scripts/inject-context.sh` that `cat`s `SKILL.md` (minus frontmatter)
to stdout — that's what Claude Code reads. For project-scoped skills use
`${CLAUDE_PROJECT_DIR}/.claude/skills/<name>/scripts/inject-context.sh`;
for user-scoped skills resolve and write the absolute path (e.g.
`$HOME/.claude/skills/<name>/scripts/inject-context.sh`) — there is no
`CLAUDE_SKILL_DIR` env var. See `references/activation-modes.md` for the
exact shapes.
4. **Removal**: only after a second confirmation; `rm -rf` the skill
directory, and remove the workspace entry if the user's setup uses
bun/npm workspaces.
5. **Preserve every other frontmatter key untouched.** YAML indent: 2 spaces.
Never edit plugin-managed skills (Step 1 already excluded them, but
double-check before writing).
## Step 7 — report
Print the final diff (per-skill: current mode -> new mode, backup path). Tell
the user how to revert (restore the `.bak.<ts>` file). Don't re-summarize the
preview — keep it terse.
If the user has multiple Claude Code projects, mention that user-scoped
changes apply everywhere; project-scoped changes apply only here.
## Safety rails
- **Never** rewrite a SKILL.md the user didn't confirm — per-skill consent,
not blanket.
- **Never** edit plugin-managed skills under `~/.claude/plugins/`.
- **Never** delete a skill without a second explicit confirmation for that
exact skill name.
- **Always** back up before writing. The backup is the rollback path.
- **Never** widen a skill's activation past what the data supports. If a
skill was invoked via slash 3x and auto 0x, recommend slash-only — don't
recommend eager-loading just because the body is small.
- If the transcript sample is sparse (<3 sessions) or the candidate list is
empty, say so and stop. Don't manufacture proposals.
## See also
- `references/activation-modes.md` — the exact frontmatter / hook shapes for
each mode, plus failure modes and gotchas
- `optimize-permissions` — same UX shape, applied to tool allowlists
- Anthropic's progressive-disclosure guidance for skills — the design
principle this skill helps you apply
Files in this package (6)
- CHANGELOG.md 1 KB
- README.md 1 KB
- SKILL.md 11 KB
- package.json 1 KB
- references/activation-modes.md 6 KB
- scripts/scan-invocations.sh 4 KB
Versions
The database has no other skills named optimize-skill-activation.
Database snapshot: 13.11.2026 · package version 92dbd2c9d007 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100skill-testing
Test skills for correct activation, content quality, and regression — both automated checks (frontmatter validity, lint) and manual verification (query-suite activation testing). Covers CI integration and how to catch skill regressions before users do. Use this skill when adding… - 100writing-skills
Use when creating, editing, or testing a Claude Code skill — writing SKILL.md and its frontmatter/description, choosing skill vs command vs subagent vs CLAUDE.md, fixing a skill that won't trigger, or deciding how strictly to test one. Covers activation (getting a skill to fire)… - 100skill-frontmatter
Write the YAML frontmatter for a SKILL.md file so it activates reliably — name, description, and activation keywords that the model matches against. Covers length, tone, and the most common frontmatter mistakes. Use this skill when authoring a new skill, fixing a skill that… - 100test-skill-activation
Measure whether agent skills (SKILL.md) actually activate in Claude Code, Codex and OpenCode with doesitfire, then improve the descriptions of skills that do not fire or fire when they should not. Use when the user asks if a skill triggers, why a skill is ignored, to test or… - 100skill-doctor
Audit, map, and improve your Claude Code skills, agents, and slash commands — and mine the current session for new ones worth creating. Use this whenever the user says "review my skills", "optimize my skills", "update my skills", "update all my skills", "maintain my skills",… - 100skill-architect
Design, create, audit, and improve Claude Agent Skills with expert-level progressive disclosure. Use when building new skills, reviewing existing skills, debugging activation failures, encoding domain expertise, or designing skills for subagent consumption. Activate on "create…