Open every SKILL.md in .claude/skills/, count the characters in each description field, and add them up. The total must stay under 15,000 characters. Any individual description over 1,024 characters gets truncated by Claude, silently, with no warning. In AEM's production skill libraries, we measured this constraint becoming active at around 12 skills: at that point, three descriptions were silently truncated and two skills had stopped activating with no error signal. Once a project grows past 10 skills, the description character count becomes the first constraint you need to manage.

TL;DR: For a project with under 15 skills, manually count characters in each description field. For 15 or more skills, use a one-line grep command. Watch two limits: a 1,024-character cap per individual description, and a 15,000-character total for all descriptions combined. Exceeding either limit causes silent, partial failures in skill activation.

Why Does the Character Count Matter?

Skills over the character budget are silently truncated or dropped: no error, no warning, no log entry. The skill sits in the folder but stops activating, with no signal to tell you why. Claude Code loads every skill description into the system prompt at session start and works through a fixed character budget.

The default budget scales at 1% of the active context window, with a fallback of 8,000 characters when the window cannot be determined (Anthropic, Claude Code Skills Documentation, 2026). You can raise it by setting the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable, but the truncation behavior when you exceed it is the same either way.

"When you give a model an explicit output format with examples, consistency goes from ~60% to over 95% in our benchmarks." — Addy Osmani, Engineering Director, Google Chrome (2024)

Knowing your character counts is the prerequisite for consistent activation. You can't optimize what you haven't measured. A community study testing 200+ prompts across Claude Code skill configurations found activation rates as low as 20% with unoptimized descriptions and up to 90% with carefully structured ones (mellanon, "Claude Code Skills Structure and Usage Guide," GitHub Gist, 2025). The character budget is not an edge case. It is the primary lever.

How Do I Count Descriptions Manually (Under 15 Skills)?

Open each SKILL.md file in your skills folder. Find the description field in the YAML frontmatter. Count its characters, including spaces and punctuation, but not the surrounding quote marks. Sum the counts across all skills and compare the total against the 15,000-character budget to see where you stand.

This description:

description: "Runs the weekly brand review: checks pipeline metrics, formats the summary, and flags blocked items."

Is 101 characters. Count from the first letter to the final period, including all spaces. The quotes are delimiters, not part of the count.

Do this for every skill. Write down each count. Sum them. If the total is under 15,000, you're inside the budget.

The official Claude Code docs note that each skill's combined description and when_to_use text is capped at 1,536 characters in the skill listing regardless of total budget (Anthropic, Claude Code Skills Documentation, 2026). Front-load the most important trigger keywords so they survive even if the tail is cut.

This takes about 2 minutes for 10 skills. For 20 or more, use the shell command below.

How Do I Use a Shell Command to Count All Descriptions (15+ Skills)?

Run this grep command to list every skill description with its character count, sorted from longest to shortest. It works on any Unix shell, including macOS Terminal, WSL, and Linux, and completes in under a second regardless of how many skills you have installed.

grep -r "^description:" .claude/skills/ | \
  awk -F'"' '{print length($2), FILENAME}' | \
  sort -rn

Sample output:

923  .claude/skills/code-review/SKILL.md
412  .claude/skills/content-writer/SKILL.md
88   .claude/skills/summarizer/SKILL.md

To get the total in one command:

grep -r "^description:" .claude/skills/ | \
  awk -F'"' '{sum += length($2)} END {print "Total:", sum, "/ 15000"}'

Output: Total: 1423 / 15000

This runs in under a second. Add it to your development workflow before adding new skills to a project with a large existing library.

How Do I Count Descriptions on Windows Without a Unix Shell?

Run this Python script on any platform, Windows, macOS, or Linux, to list every skill description's character count and flag any individual description over 1,024 characters. Python ships with Windows 10 and later, so no extra installs are needed on most developer machines.

import os, re

skills_dir = ".claude/skills"
total = 0
results = []

for root, dirs, files in os.walk(skills_dir):
    for fname in files:
        if fname == "SKILL.md":
            path = os.path.join(root, fname)
            content = open(path, encoding="utf-8").read()
            match = re.search(r'^description:\s*"([^"]*)"', content, re.MULTILINE)
            if match:
                count = len(match.group(1))
                results.append((count, path))
                total += count

results.sort(reverse=True)
for count, path in results:
    flag = " <-- OVER LIMIT" if count > 1024 else ""
    print(f"{count:4d}  {path}{flag}")

print(f"\nTotal: {total} / 15000")

This script also flags any individual description over the 1,024-character limit.

What Should I Do If My Total Exceeds the Budget?

Compare your total against two thresholds: 15,000 characters for the combined budget and 1,024 characters per individual description. Below 12,000, no action is needed. Between 12,000 and 15,000, keep new descriptions under 100 characters. Above 15,000, shorten the longest descriptions first, starting with any skill that activates inconsistently.

  • If total is under 12,000 characters: You have room. No action needed.
  • If total is 12,000 to 15,000 characters: You're in the warning zone. The next skill you add to this project needs a short description (under 100 characters) to stay safe.
  • If total exceeds 15,000 characters: Skills installed last are being truncated or dropped. Find the longest descriptions and shorten them. Skills that activate inconsistently should be checked first, as their descriptions are the most likely casualties.
  • If any individual description exceeds 1,024 characters: That description is being cut mid-sentence in the system prompt. Claude sees only the first 1,024 characters. Shorten that description immediately. The truncation point is arbitrary and almost always falls in the middle of a trigger condition.

Skills installed last in the list are also at the greatest risk from a context position standpoint. Research from Stanford NLP found that model accuracy on content placed in the middle of long contexts dropped by more than 30% compared to content at the start, across multi-document tasks (Liu et al., "Lost in the Middle," Stanford NLP Group, 2023, ArXiv 2307.03172). A 2025 study by Chroma testing 18 frontier models found this degradation is universal: every model showed 30%+ accuracy drops at mid-window positions, regardless of advertised context window size (Chroma, "Context Rot," research.trychroma.com, 2025). Skills that load later into the system prompt face a similar disadvantage: they are both more likely to be truncated and less reliably attended to.

For guidance on which parts of a description to shorten without breaking activation, see How Do I Check If My Skill Descriptions Fit Within the System Prompt Character Budget? and How Do I Write Trigger Phrases That Make My Skill Activate Reliably?.

FAQ

For projects under 10 skills, the character budget is not an active constraint. Past that threshold, each new skill competes for limited space in the system prompt listing. Count only the value inside the description quotes, not the field name. User-level and project-level skills draw from the same pool and count toward the same total.

Does character count include the frontmatter field name itself? No. Count only the value inside the quotes. description: "My skill does X" has 12 characters (M-y through X). The description: prefix and quotes are not part of what Claude loads into the system prompt.

Does Claude count characters or tokens for the budget? The budget is defined in characters via the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable (Anthropic, Claude Code Skills Documentation, 2026). At roughly 4 characters per token, a 15,000-character budget is approximately 3,750 tokens. Track characters, not tokens, for precision.

My total is 9,200 characters across 18 skills. Am I safe? Yes. You're at 61% of the budget with room for 12 more 500-character descriptions before reaching the limit. The practical ceiling where activation problems start is around 13,000 to 14,000 characters, before the hard cut at 15,000.

Do user-level skills count against the same budget as project skills? Yes. Both load in the same session and both count toward the same 15,000-character ceiling. If you have 8,000 characters of user-level skills and 8,000 of project skills, you're over budget.

How often should I audit my character counts? Check when you add a new skill to a project that already has 10 or more skills. Check immediately if you notice a previously reliable skill is now activating inconsistently. Otherwise, a quarterly audit of large skill libraries is sufficient.

Is there a tool in Claude Code itself that shows description character counts? Not directly. The /skills command lists skills but doesn't show character counts. Use the grep or Python methods above to get precise numbers.

Last updated: 2026-04-22