Skill Overhead Alert (Skills Bloat checker)

What it is

Amber inbox card that fires when the Claude Code skills you have installed add up to too much always-on overhead. It is the skills analogue of the MCP Overhead Alert: same inbox-card + snooze + Settings-limit shape, but global (skills config is not per-project in Omniscio — every installed skill loads into every conversation, so there is exactly one rule) and with two independent trip legs instead of MCP's three (skills hold no RAM while idle, so the RAM leg is dropped).

Where to find it

An amber card in your inbox, alongside your other alerts, with the single global rule at Settings → Notifications → Skill Overhead. (It does not live under the Skills sidebar entry — that panel is for browsing and installing skills, not for this alert.)

How it behaves

What it watches

Every skill you install — a personal skill under ~/.claude/skills or one that arrived with a plugin (the plugin cache) — loads its YAML frontmatter into the skill-discovery index of every conversation. That is the always-on tax: even a skill you never invoke costs context on every single message, because its name + description have to be advertised so the agent knows the skill exists. A pile of unused or heavy skills is pure waste. The checker watches the global set of installed skills — user skills plus plugin skills — and fires when either of these crosses its limit:

1. Estimated frontmatter tokens — the summed always-on frontmatter tokens across ALL installed skills. Always labeled an estimate (a chars / 4 heuristic): Omniscio counts only the frontmatter, because only the frontmatter loads into every conversation — the skill body is read on demand when the skill actually runs, so it does not crowd the live context the same way. Default limit 20,000 tokens.
2. Unused skills — count of installed skills (user + plugin) with no invocation in the last 30 days (from the tool_invocations scanner). The most reliable "wasted weight" signal. Default limit 1 — the card keeps offering unused skills to review until none are left (a clean slate). Set it higher to stop sooner, or 0 to turn the review card off.

A limit of 0 disables that leg. The alert fires when either enabled leg trips (frontmatter OR unused).

New-user warm-up (the "unused skills" nudge waits 30 days)

The "unused skills" part of this alert stays silent until you've been using Omniscio for at least 30 days (measured from your first session). This is on purpose: that leg asks "which skills haven't you touched in the last 30 days?" — and on a brand-new install the honest answer is "all of them," because there simply isn't 30 days of history to look back on yet. Firing then would nag a new user that every skill is "unused" the day they installed it. So Omniscio holds the unused-skills nudge during that warm-up window and only starts watching once the 30-day question can be answered truthfully. A fresh install with no sessions yet is treated as brand-new. (Same warm-up idea as the record-breaking-session alerts.)

The "too many skills loaded" (token overhead) part is not held — a heavy pile of installed skills costs context on every message whether or not you've ever used them, so that leg is meaningful from day one and can fire immediately, even during the warm-up window.

The plugin-usage fix (why your plugin skills used to say "Never used")

This feature ships with a real bug fix. The tool-invocation scanner records a skill's usage under the exact name it was invoked with. A user skill is invoked by its bare folder slug (e.g. audit-aggregation), but a plugin skill is invoked namespaced by its plugin (e.g. superpowers:systematic-debugging). The Skills view used to look up usage by the bare folder name only — so every used plugin skill matched nothing and rendered "Never used", even one you run constantly (verified against real data: 14/14 plugin skills matched <plugin>:<skill>, 0/14 matched the bare name).

The matching now goes through one shared helper, src/shared/skill-usage-match.ts, used by both the Skills view and the new Skill Overhead scan — so a heavily-used plugin skill is counted correctly in both places and is never false-flagged as unused. (It also folds in throwaway .worktrees/<path>:<slug> usage keys that past worktree sessions left behind, so a skill only ever run inside a worktree isn't wrongly counted as unused either.)

The card

The card is titled "Skill overhead — N unused · ~N always-on tokens" and lives in your inbox alongside your other alerts (not grouped under the Skills sidebar entry — see above). The count in the title is taken when the card appears; the live count sits above the deck. Opening it shows a review deck — your unused skills, one card at a time:

• Each card names the skill and shows its whole description (never cut short), then shows three small tags: how long it has gone unused, what it costs in every chat (always labelled an estimate), and where it came from (your skill, or the plugin that shipped it). No recorded use means no matching invocation was found, not proof the skill has never been used.
• Swipe (on a touch screen), the ‹ › buttons, or the ← → arrow keys move between skills. Moving never changes anything — it is how you skip a skill you want to think about.
• Keep it opens Keep for 60 days or Keep permanently. It suppresses the unused-skill reminder, not the skill's token cost.
• Archive moves a skill of your own (or one Omniscio ships) to the skills trash at once — no confirmation, because it is reversible. A plugin skill shows Remove instead and asks first, because removing it deletes it from the plugin cache (reinstall the plugin to get it back).
• Whichever you choose, that skill leaves the deck and the next one slides into its place, so you can work through as many as you like. A small line under the deck says what archiving does for the skill in front of you.
• When none are left the card shows No unused skills left. Show more skills opens the Skills manager for broader cleanup.

More about the controls:

• Keep and Archive work on desktop and on a paired phone — Archive is the same operation the Skills manager's own Remove performs there.
• Skills bundled with Omniscio also move to trash, and stay archived across launches. Restore them from Archived in the Skills manager; the review card does not contain an Archived list.
• omniscio-control is never offered. The seven other Omniscio skills route into its pages, so archiving it would break all of them. The card skips it and it does not count toward the unused total, though its token cost still counts in the frontmatter total.
• Keep and Archive are disabled while a save or the plugin confirmation is in progress, then become available again on failure.

Putting the whole card away is a separate action from archiving a skill: the card's own Archive button (top of the card; also the keyboard E shortcut, middle-click, bulk archive, or an inbox rule) just acknowledges the overhead — it never touches a skill file. The card also supports the universal inbox Snooze, and the Start session button every alert card carries. You can mute Skill Overhead alerts entirely from the card, or from Settings → Notifications → Alert types.

When it comes back. Keeping or archiving skills never hides the card — it stays up while any unused skill remains. Once you put it away, it returns only when more unused skills pile up or after the reminder cadence (30 days by default). Snooze is your "not now" control. Clearing a Keep (Start flagging) re-flags that skill.

For agents

Honesty contract

• Estimate: the frontmatter-token figure (shown with the tokens unit, and flagged as an estimate in the card's fine print) — a chars / 4 heuristic, never an exact tokenizer count.
• Measured: the installed-skill count and per-skill usage (call counts, "never used").

A non-technical user never sees a guess dressed up as a fact.

Settings

Settings → Notifications → Skill Overhead holds the single global rule: a master enable toggle plus tunable limits (estimated-frontmatter-token limit, unused-skill limit) and the two re-alert knobs (growth %, cadence days). The master switch is the enabled flag on the seeded 'global' rule — there is no AppSettings field.

The whole feature also respects enableSkillsIntegration: when the Skills feature is turned off, Omniscio neither scans nor alerts — no point nagging about a disabled surface, and a stale scan can never fire once skills are off.

Implementation notes

• Decision logic is one pure module: src/shared/alert-features/skills-bloat-alert.ts — shouldFireSkillsBloatAlert(scan, rule, now) plus the per-leg frontmatterLegTrips / unusedLegTrips helpers, and isOverAnyLimit. There is no per-day gate: answering a skill never quiets the alert, and a dismissed card re-alerts only on growth or cadence. The clock is injected, so it is testable without faking time.
• Scan engine (src/main/services/skills/skills-bloat-scan.ts) resolves the global installed set (user + plugin), sums the frontmatter estimates, and joins the 30-day usage aggregate through the shared skill-usage-match helper for unused detection. It reuses existing data — no skill is ever executed to measure it.
• Storage is a single global rule + a single global scan row (no per-project rows) plus a per-skill kept table (skills_bloat_kept — one row per kept skill, kept_until NULL = forever), all via forward-only migrations on the frozen baseline. A kept skill is excluded from the unused count only — never from the token total.
• The inbox card is a central alert, not its own inbox source: src/main/services/skills/skills-bloat-alert-card.ts turns the due item into one global card (dedup key skills-bloat-alert:global) via the shared reconcileAlertFamily / registerAlertArchiveListener building blocks every alert family uses — it follows the feature's own push AND SETTINGS_CHANGED (the scan stops pushing once Skills integration is off). Its custom body is src/renderer/src/features/skills-bloat-alert/SkillsBloatAlertCardBody.tsx — the review deck, on the shared useScrollSnapTrack paging, one SkillReviewTile per skill — mounted inside the shared AlertInboxViewer. Triggers and IPC handlers otherwise mirror the MCP Overhead Alert feature, minus the RAM leg.

Related

• mcp-bloat-alert.md — the sibling checker for MCP servers; same inbox-card + snooze shape, one extra leg (measured active-session RAM)
• doc-token-alert.md — the same alert pattern for a project's always-loaded agent docs (CLAUDE.md / AGENTS.md / MEMORY.md); the tiered-re-alert design originates here
• use-skills.md — the Skills view this alert links to: browse, install, edit, and update your Claude Code skills (and where the same plugin-usage fix now shows correct "used"/"never used" flags)
• inbox-overview.md — how unified-inbox rows surface across all integrations; the skill-overhead row lives in this list

See the contract for the full invariant list: .claude/memory/contracts/skills-bloat-alert-contract.md.