Claude Code skill description limits: 1,536 vs 1,024 characters

If you have searched for the character limit of a skill description, you have probably seen two different numbers. Both are correct. They belong to two different products that share the name "Skills".

The short answer

Where the skill runs	Field	Limit
Claude Code (local files in ~/.claude/skills/ or .claude/skills/)	description and when_to_use combined	1,536 characters
Agent Skills API and claude.ai (uploaded skills)	description	1,024 characters

If you write skills for Claude Code, the number to remember is 1,536, and it is a shared budget for two fields.

What "truncated" means

The Claude Code docs put it this way: the combined description and when_to_use text is truncated at 1,536 characters in the skill listing, to reduce context usage.

The skill listing is the part Claude sees at the start of every session: the name and description of every installed skill. The body of SKILL.md is not in it. The body loads only when the skill is actually used.

So anything past character 1,536 is cut from the listing. Claude never sees it when it decides which skill fits your request. The body is unaffected, but by then the decision has already been made.

The docs give the practical rule in one line: put the key use case first.

The when_to_use field shares the budget

when_to_use is a separate frontmatter field for trigger context. Its text is appended to description in the listing and counts toward the same 1,536 characters. A long description therefore leaves less room for when_to_use, and the other way around.

---
name: release-notes
description: Generates release notes and changelogs from git history.
when_to_use: Use when the user asks for release notes, a changelog, or what shipped since the last version.
---

Here the two fields together are well under the limit. In your own skills, measure the sum, not each field on its own.

How to check your own skills

For skills whose description sits on a single line, this prints the length of each description that is longer than 300 characters:

grep -h '^description:' ~/.claude/skills/*/SKILL.md \
  | awk '{ n = length($0) - 13; if (n > 300) print n }' \
  | sort -rn

The 13 is the length of description: . Depending on your awk, non-ASCII characters may be counted as bytes, so the number can read slightly high.

Descriptions written as multi-line YAML (>- or |) need a YAML parser to measure. Remember to add the length of when_to_use if you use it.

How to write within the limit

Most descriptions that hit the cap are padded, not rich. A few habits keep them short and effective:

• Lead with what the skill does and when to use it. Put the sentence you would least like Claude to miss at the very start.
• Use the words people actually say. "Use when the user asks for release notes, a changelog, or what shipped" matches real requests better than "release management helpers".
• One skill, one job. If a description needs 1,400 characters to cover everything, it is usually two skills. Split it and each description gets sharper.
• Cut what the body already says. The listing only needs enough to decide whether to load the skill. Details belong in SKILL.md itself.

If a skill still does not fire after you tighten its description, see why a Claude Code skill never triggers.

Editing descriptions without opening files

SkillKeeper lets you rewrite a skill's description and its trigger phrases directly in the menu bar popup and shows the 1,536-character limit as you type. The counter turns orange when you go over, and it does not block you. Edits are written to the skill's SKILL.md on your Mac.

Sources

• Claude Code skills documentation, for the 1,536-character limit and the when_to_use field
• Agent Skills overview, for the 1,024-character limit of the Agent Skills API