skill-context-cost

How much of your AI agent's context window do your skills eat before you type anything?

Every agent app that supports Agent Skills advertises each installed skill to the model at session start — roughly name (path): description per skill. That cost is paid in every single session, whether you use the skill or not. Install enough skills and you're burning thousands of tokens of context (and attention) before the conversation begins.

skill-context-cost scans your machine, measures it, and tells you how to slim it down:

npx skill-context-cost          # the numbers
npx skill-context-cost doctor   # the advice

Example

◆ Claude Code (CLI)  ·  window 200,000 tok
  startup cost 3,421 tok (1.7% of window) · 44 skills advertised
  if all invoked at once: 144,714 tok · dirs: ~/.claude/skills

  GLOBAL — every session on this machine  3,421 tok · 44 skills
         share         startup   invoked   skill
     1. ████████████     153 t    7,582 t  turnstile-spin (user)
     2. ███████████·     141 t    2,132 t  cloudflare-email-service (user)
     3. ██████████··     129 t      420 t  browser-mcp-selector (plugin:browser-mcp-selector)
     … 41 more — rerun with --all

  LOCAL — this project only  0 tok · 0 skills
    (none)

  ► always loaded too: global CLAUDE.md 292 t (~/.claude/CLAUDE.md)

Σ total startup cost across apps: 6,597 tokens across 71 advertised skills

And doctor opens with a grade dashboard, then groups findings by rule with magnitude bars:

  Claude Code (CLI) C ▕████░░░░░░▏   Claude Desktop B ▕██░░░░░░░░▏   Codex CLI A ▕█░░░░░░░░░▏
  0 ✖ errors · 30 ⚠ warnings · 1 ℹ info · 0 ✓ good

◆ Claude Code (CLI) — grade C · 3,421 tok startup (1.7% of window) · 44 skills
  ⚠ Startup entry over ~100-tok budget — paid EVERY session (4)
     turnstile-spin             ██████████    133 t (user)
     cloudflare-email-service   █████████·    123 t (user)
     browser-mcp-selector       ████████··    112 t (plugin:browser-mcp-selector)
     web-perf                   ████████··    106 t (user)
     fix: make the description dense (what + when-to-use in 1–2 sentences); detail belongs in the body

Biggest wins (heaviest startup entries):
  1. pitch-review (Claude Desktop) — 244 tok every session; tighten its description or make it manual-only

Supported apps

App	What is scanned	macOS / Linux	Windows
Claude Code (CLI)	user skills, project skills, installed plugins (respecting enabledPlugins), CLAUDE.md	~/.claude/skills, <project>/.claude/skills, ~/.claude/plugins	%USERPROFILE%\.claude\...
Claude Desktop	newest agent-session skill bundle (synced by the app)	~/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin	%APPDATA%\Claude\local-agent-mode-sessions\skills-plugin
Codex CLI	user skills, project skills, AGENTS.md	~/.codex/skills, <project>/.codex/skills	%USERPROFILE%\.codex\...
ChatGPT (desktop/web)	nothing — customizations are server-side; reported for clarity	—	—

Note: Claude Desktop does not read ~/.claude/skills — verified against cowork session logs (~/Library/Logs/Claude/coworkd.log): sessions mount only the app's synced skills-plugin bundle; the real ~/.claude is never mounted. That directory belongs to Claude Code and is counted in its section. Desktop's Skills panel not listing local skills is tracked in anthropics/claude-code#43095.

Commands & flags

npx skill-context-cost [scan]     scan and show per-skill startup cost (default)
npx skill-context-cost doctor     scan + actionable suggestions

--app <ids>       claude-code, claude-desktop, codex, chatgpt (comma-separated)
--all             list every skill, not just the top 8
--json            machine-readable output (both tokenizers included)
--window <n>      override the assumed context window (tokens)
--project <path>  project root for project-level skills (default: cwd)
--no-color        disable colors

What doctor checks

• error — skill has no description (the model can never choose it)
• warn — description over 1,024 chars (Claude Code truncates it)
• warn — startup entry over the ~100-token budget (paid every session)
• warn — SKILL.md over 5,000 tokens when invoked → split into references/*.md (progressive disclosure)
• warn — Codex skill list over its 8,000-char cap → skills silently dropped from the model's view
• warn — duplicate skill names across sources (shadowing)
• info — same skill drifted apart between ~/.claude/skills and ~/.codex/skills
• info — oversized always-loaded files (CLAUDE.md, AGENTS.md)
• ok — skills using disable-model-invocation: true (zero startup cost 👍)

Grades: A < 0.5% of window · B < 1% · C < 2% · D < 4% · F ≥ 4%.

Methodology (honest numbers)

• Startup cost = tokens of the listing line the app injects per skill (- name (path): description) plus a small fixed overhead, matching the progressive-disclosure design: only name/description are loaded at startup; the body loads on invocation. Skills with disable-model-invocation: true are not advertised at all → counted as 0.
• Invoked cost = tokens of the full SKILL.md. Extra files (references/, scripts) load on demand and are not counted.
• Tokenizers: o200k_base (exact for Codex CLI models) via gpt-tokenizer. Claude's tokenizer is not public, so Claude numbers are estimated as o200k × 1.15 and labeled as estimates. Cross-check inside Claude Code with /context.
• Windows assumed: 200k (Claude), 400k (Codex) — override with --window.

These are estimates of a moving target — apps change their prompt formats. Treat the numbers as accurate to ~±10%, and the relative ranking as solid.

Sources

• Codex CLI: Build skills — startup listing = name + description + path, capped at 2% of window / 8,000 chars
• Claude Code docs: skills & plugins
• Claude Desktop skill storage locations

Development

git clone https://gitlab.com/andrew54068/skill-context-cost.git
cd skill-context-cost
yarn install
yarn test          # build + 46 node:test cases (no test framework deps)
node dist/cli.js doctor

Requires Node ≥ 18. Architecture: each app is a Provider reading the environment only through an injected ProviderContext (src/provider.ts), registered in src/registry.ts — adding an app is one module + one registry line. Thresholds live in src/limits.ts. Contributions welcome — especially verified paths/formats for new apps and platforms.

License

MIT