Claude Agent Skills: The Hidden Token Tax Nobody Warns About

I installed 14 skills into a Claude Code project last month after reading one too many “best Claude Skills” roundups, and within a week my simplest one-line prompts were burning noticeably more input tokens than before I’d added any of them. Nobody had warned me that skill metadata isn’t free just because it’s small — it’s small per skill, but it’s paid on every single message, whether or not that skill ever fires. This post covers what a Skill actually is, the token math nobody publishes, why skills silently stop triggering once you cross a hard character budget, how Skills differ from MCP servers, and how I audited my own setup down to something that actually earns its keep.

What are Claude Agent Skills and how do they work?

A Skill is a folder — at minimum a SKILL.md file — that packages procedural knowledge Claude can load dynamically instead of you re-explaining a workflow every session. Anthropic’s engineering team describes it as “putting together an onboarding guide for a new hire,” and the mechanism is progressive disclosure across three levels: metadata, instructions, and bundled resources.

Here’s the minimal structure straight from the official spec:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# PDF Processing

Step-by-step instructions Claude follows once this skill activates.

When I built my first skill for a Drupal migration workflow, the frontmatter took ten minutes and the instructions body took an afternoon of trial and error watching Claude’s actual trajectory. The `name` field must match the parent directory, use only lowercase letters, numbers, and hyphens, and stay under 64 characters. The `description` field is capped at 1,024 characters in the spec, but in practice the skill listing UI in Claude Code truncates displayed descriptions at 250 characters — bury your key trigger phrase in sentence three and Claude may never see it.

How much does the metadata for every installed skill actually cost you?

Every installed skill’s name and description load into the system prompt at session start, for every skill, regardless of whether the task needs it. Anthropic’s own spec puts this at roughly 100 tokens per skill. That sounds trivial until you count what you’ve actually installed.

When I ran the math on my own 14-skill setup: 14 skills x ~100 tokens = about 1,400 tokens spent before I’d typed a single word of my prompt, on every message, in every session, for the entire conversation. That’s a fixed tax, not a one-time cost — it compounds across a long working session the same way an unused browser tab still uses RAM. Compare that to the “I Tried 100 Claude Skills” roundups now trending on Dev.to: 100 skills at the spec’s ~100-token estimate is roughly 10,000 tokens of pure overhead before Claude does anything, and that’s before you account for the fact that real-world descriptions frequently run longer than the spec’s minimal examples.

Academic work backs up that this overhead is worth engineering around. The SkillReducer paper (arXiv 2603.29919) reports a 48% mean compression rate for skill descriptions and a 39% mean reduction in body tokens, while holding an 86.0% pass rate on task-based evaluations and a 100% pass rate on SkillsBench — meaning you can compress descriptions hard without breaking triggering, if you do it carefully rather than just truncating.

Why do my Claude Skills stop triggering after I install more of them?

I hit this exact bug in a client’s monorepo: skills that had worked fine for weeks just stopped firing after we added a fifth and sixth skill to the same Claude Code project. The cause wasn’t a bug in my SKILL.md — it was a hard character budget. As of Claude Code 2.0.70, the combined character budget for skill and slash-command descriptions defaults to 15,000 characters, and there’s no warning when you cross it. Skills past that budget simply don’t make it into the system prompt, so Claude has no way to know they exist.

The workaround I use now is setting the environment variable SLASH_COMMAND_TOOL_CHAR_BUDGET=30000 to double the headroom, but that’s a band-aid, not a fix — it just moves the wall further out. The real fix is auditing description length per skill and trimming anything that reads like marketing copy instead of a trigger condition. A second, quieter failure mode: duplicate skills registered across different paths (project-level vs. user-level), where Claude loads conflicting instructions depending on which path a command happens to resolve to first.

Claude Skills vs MCP servers: which one should I use?

I see these two conflated constantly, and the distinction actually matters for token budgeting. An MCP server is a running process that exposes typed tools over the Model Context Protocol — it’s where side effects happen: querying a database, opening a pull request, posting to Slack. A Skill is a packet of natural-language instructions with no persistent process at all. MCP is connectivity; Skills are procedural knowledge.

The practical rule I follow on client projects: add an MCP server when Claude needs to reach a system it can’t reach today. Add a Skill when Claude already has the access but you keep re-explaining the same workflow. They compose well together — I commonly use an MCP server to fetch data and a Skill to define how that data should be transformed, formatted, or validated once it arrives.

Comparison: Claude Skills vs MCP Servers vs Plain Prompting

Option	Performance	Complexity	Best For
Agent Skill	~100 tokens/skill baseline, full body only on trigger	Low — just a folder + Markdown	Repeatable internal workflows, SOPs, formatting rules
MCP Server	Persistent process overhead, but scoped tool calls	Medium-High — separate running service	Reaching external systems: databases, APIs, SaaS tools
Plain re-prompting	Full instructions re-sent every session	Lowest setup, highest ongoing token cost	One-off tasks you’ll never repeat

How do you actually measure and cut a skill’s token cost?

Start by counting what’s currently loaded. I keep a plain checklist: list every installed skill, note its description character count, and flag anything over 250 characters (the practical truncation point) or contributing disproportionately to your 15,000-character budget. From there, three moves that worked for me:

for f in .claude/skills/*/SKILL.md; do
  chars=$(awk '/^description:/{print length($0)}' "$f")
  echo "$f: $chars chars"
done | sort -t: -k2 -n -r

First, move anything that isn’t needed on every task out of SKILL.md and into a `references/` file — the spec’s third level of disclosure — so it’s only loaded when Claude actually reads it, not baked into the always-loaded metadata. Second, rewrite descriptions as trigger conditions, not summaries: “Use this skill when the user asks to reconcile PHP composer.lock conflicts” beats “Helps with Composer.” Third, prune. I removed 4 of my original 14 skills after finding they’d triggered zero times across two weeks of real work — they were pure overhead with no offsetting benefit, exactly the failure mode the Local-Splitter study (arXiv 2604.12301) targets, reporting 45-79% cloud token savings from combining local routing with prompt compression on edit-heavy and explanation-heavy coding workloads.

What are the biggest mistakes when building a SKILL.md file?

The most common mistake I see in code review is writing the description like ad copy instead of a classifier prompt. The description’s only job is deciding whether to load the skill at all — “use this skill when you need to X,” not “this skill does X.” The second mistake is bloating the body past the spec’s own recommendation of under 5,000 tokens and 500 lines; once a SKILL.md gets unwieldy, split it into referenced files instead of scrolling past the point where Claude reliably uses it.

The third mistake, and the one that bit me hardest, is skipping the security review step. Anthropic’s own guidance is blunt: install skills only from trusted sources, and audit anything less-trusted by reading every bundled file, script, and network call before use, because a malicious or careless skill can direct Claude to exfiltrate data or take unintended actions. I now treat every third-party skill from a “100 skills” roundup the same way I’d treat an unreviewed npm package — read it before it runs.

Is a skill marketplace like “100 best Claude Skills” a good idea?

Not the way most people use them. These roundups treat skill installation like installing browser extensions — more is better, curiosity is free. It isn’t. Every skill you install is a permanent line item in your per-message token bill until you remove it, and the roundup format actively discourages the pruning step because nobody writes “47 skills you tried and should delete.” My working rule after auditing three separate projects: install to test, measure trigger rate over a real work week, then keep only what earned its 100-token tax. That single discipline change cut my own baseline overhead by close to a third without losing any capability I was actually using.

• Every installed skill’s name and description loads into every request at roughly 100 tokens each, whether or not the skill ever triggers, so unused skills are a recurring cost, not a one-time install.
• Claude Code 2.0.70 enforces a default 15,000-character budget across skill and slash-command descriptions, and skills that push past it silently stop appearing to Claude with no warning.
• SkillReducer-style description compression can cut skill tokens roughly 48% for descriptions and 39% for bodies while holding a 100% pass rate on SkillsBench, if compression targets redundancy rather than truncating key trigger phrases.
• Skills and MCP servers solve different problems — MCP is connectivity to external systems, Skills are reusable procedural knowledge — and combining them beats forcing one to do both jobs.
• Description fields should read as trigger conditions (“use this skill when…”) rather than marketing summaries, since that’s literally the only text Claude sees before deciding to load the rest.
• Audit installed skills against real trigger rate over a work week and prune anything that never fires; a “100 skills installed” setup is a liability, not a flex, until you’ve measured it.

Frequently Asked Questions

What is the difference between Claude Skills and MCP servers?

MCP servers are running processes that give Claude access to external systems like databases or APIs; Skills are folders of instructions with no persistent process that teach Claude how to complete a repeatable workflow. Use MCP for connectivity Claude doesn’t have yet, and Skills for workflows you keep re-explaining.

Why did my Claude Code skill stop triggering?

The most common cause is exceeding the default 15,000-character budget for combined skill and slash-command descriptions in Claude Code 2.0.70 and later — skills past that limit are silently dropped from the system prompt. Check total description length across all installed skills and trim, or raise the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

How many tokens does a Claude Skill use?

Roughly 100 tokens per skill for the always-loaded name and description, per the official Agent Skills specification. The full SKILL.md body, recommended under 5,000 tokens, only loads when Claude decides the skill is relevant to the current task.

How do I write a good SKILL.md description?

Write it as a trigger condition, not a summary — “use this skill when the user asks to X” rather than “this skill does X.” Keep it under 250 characters where possible since some UIs truncate the displayed description at that length, and lead with your primary keyword or use case.

Are Claude Agent Skills an open standard?

Yes. Anthropic published Agent Skills as an open standard at agentskills.io on December 18, 2025, for cross-platform portability, meaning a SKILL.md built for Claude can work with other compatible agent implementations that follow the same specification.

The unique thing I keep coming back to is that Skills were designed to solve a context-window problem, and most public advice about them recreates a smaller version of the same problem — just at the description layer instead of the body layer. A 15,000-character wall you don’t know exists, and a 100-token tax per skill you never audit, are exactly the kind of invisible costs progressive disclosure was supposed to eliminate. Treat your skill folder the way you’d treat production dependencies: version it, measure it, and delete what doesn’t earn its keep. Drop a comment below or subscribe to NexGismo for posts like this delivered weekly.