SKILL.md Line Limit: 500 Lines, and How to Fix Skills Not Triggering
By Matt Cullerton, founder of Mavric and Apso
Anthropic's documented limit for a SKILL.md file is 500 lines, not the 200 lines a popular TikTok checklist claims. And if your Claude skills are not triggering consistently, trimming the body will not fix it. Claude decides whether to use a skill from its name and description alone, before it reads a line of the body.
A TikTok from @goldst.ai dictates a six-point audit prompt to Claude: keep skills under 200 lines, move overflow into references, add tables of contents, use code for consistency, add templates, and check a "three C's framework." Two of those checks conflict with Anthropic's guidance, and none addresses the video's opening problem: "my skills are not working consistently."
What is the SKILL.md line limit?
Anthropic's documentation says 500 lines in several places:
- The Skill authoring best practices page says "Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files." Its pre-ship checklist includes "SKILL.md body is under 500 lines."
- The Claude Code skills docs say "Keep
SKILL.mdunder 500 lines." - Anthropic's skill-creator skill says "Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy."
- The open Agent Skills specification says "Keep your main
SKILL.mdunder 500 lines."
A 200-line house rule is a reasonable preference, since a shorter body costs fewer tokens. It is not the documented threshold.
When should a reference file have a table of contents?
The video says any reference over 100 lines needs a table of contents. That matches the best practices page: "For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads."
Anthropic is not consistent on the number, though. The skill-creator skill in its own public repo says "For large reference files (>300 lines), include a table of contents." The video's 100 matches the docs site. Anyone using 300 is following Anthropic's tooling.
Is there a "three C's framework" for skills?
No Anthropic documentation uses the phrase "three C's" or defines that framework. The video describes it as skills being "clear, concise, and that there are no technical constraints."
The first two have support in the best practices page, which has a section titled "Concise is key."
The third runs the wrong way. Anthropic recommends constraints when an operation is fragile. The best practices page describes a "low freedom" mode for when "Operations are fragile and error-prone, Consistency is critical, A specific sequence must be followed." Its example is a database migration: "Run exactly this script: python scripts/migrate.py --verify --backup. Do not modify the command or add additional flags." Removing technical constraints from every skill would strip out the mechanism Anthropic recommends for inconsistent results.
Should skills use scripts instead of written instructions?
Yes, for deterministic tasks, and the video gets this one right. The best practices page says "Prefer scripts for deterministic operations: Write validate_form.py rather than asking Claude to generate validation code." It lists the benefits: scripts are "More reliable than generated code," "Save tokens," "Save time," and "Ensure consistency across uses."
The overview page explains the token saving. When Claude runs a script through bash, the script's code never enters the context window. "Only its output ... consumes tokens."
The video's template check also fits the published layout. The spec names assets/ as the folder for templates, images and data files.
Why is my Claude skill not triggering?
This is the problem the video starts with, and none of its six checks reaches it. Every check is about the body, the references, the scripts or the prose. Triggering happens before any of that is read.
The overview page describes the loading order. At startup Claude loads only each skill's name and description, roughly 100 tokens per skill. "The description is what Claude matches your request against when determining whether to trigger the Skill, so it must say both what the Skill does and when to use it." The SKILL.md body is Level 2 and is read only after that match. Cutting a 250-line body to 199 lines does not change whether the skill fires.
Anthropic's skill-creator names the problem and the fix: "currently Claude has a tendency to 'undertrigger' skills - to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit 'pushy'." Its example adds a line like "Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
Other rules from the docs that affect triggering:
- Write descriptions in third person. "The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems."
- The spec caps
descriptionat 1,024 characters andnameat 64. - Claude Code runs a skill with
disable-model-invocation: trueonly when you type/name. - A skill with
pathsglobs activates only when the files you are working on match. - Claude Code truncates
descriptionpluswhen_to_useat 1,536 characters in the skill listing.
How Anthropic says to test skills
The video asks Claude to run the audit "quickly." Anthropic's method is slower. The best practices page says "Create evaluations BEFORE writing extensive documentation." Its checklist asks for "At least three evaluations created" and "Tested with Haiku, Sonnet, and Opus."
It describes a loop of watching an agent use the skill, finding the specific failure and fixing that.
Bottom line
Keep SKILL.md under 500 lines, per Anthropic's docs, and add a table of contents to long reference files. Use scripts for deterministic work and keep exact commands for fragile steps. If a skill does not fire, rewrite its description with clear trigger phrases, then test it with real evaluations.
Sources
- Skill authoring best practices - 500-line limit, 100-line table of contents rule, degrees of freedom, scripts and testing
- Agent Skills overview - loading levels, how descriptions trigger skills, sync and plan limits
- Use Skills in Claude Code - frontmatter fields and the 1,536-character truncation
- Agent Skills specification - field limits and folder conventions
- anthropics/skills repository - the skill-creator skill and its undertriggering advice
- Equipping agents for the real world with Agent Skills - Anthropic's launch post
- Agent Skills launch announcement - product announcement and availability
- First impressions of Claude Cowork - background on Cowork, tagged in the video
- Anthropic makes agent Skills an open standard - reporting on the open-standard release
Published September 10, 2026. Based on a TikTok by @goldst.ai. Full video notes (markdown)