---
title: "SKILL.md Line Limit: 500 Lines, and How to Fix Skills Not Triggering"
date: "2026-09-10"
video_id: "7683973920021695774"
tiktok_url: "https://www.tiktok.com/@goldst.ai/video/7683973920021695774"
creator: "@goldst.ai"
category: "AI"
tags: ["claude skills", "skill.md", "agent skills", "claude code", "skill triggering"]
excerpt: "Anthropic says to keep SKILL.md under 500 lines, not 200. Here is what its docs say about references, scripts, and why a skill does not trigger."
---
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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/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](https://code.claude.com/docs/en/skills) say "Keep `SKILL.md` under 500 lines."
- Anthropic's [skill-creator skill](https://github.com/anthropics/skills/tree/main/skills/skill-creator) says "Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy."
- The open [Agent Skills specification](https://agentskills.io/specification) says "Keep your main `SKILL.md` under 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 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 `description` at 1,024 characters and `name` at 64.
- Claude Code runs a skill with `disable-model-invocation: true` only when you type `/name`.
- A skill with `paths` globs activates only when the files you are working on match.
- Claude Code truncates `description` plus `when_to_use` at 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - 500-line limit, 100-line table of contents rule, degrees of freedom, scripts and testing
- [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - loading levels, how descriptions trigger skills, sync and plan limits
- [Use Skills in Claude Code](https://code.claude.com/docs/en/skills) - frontmatter fields and the 1,536-character truncation
- [Agent Skills specification](https://agentskills.io/specification) - field limits and folder conventions
- [anthropics/skills repository](https://github.com/anthropics/skills) - the skill-creator skill and its undertriggering advice
- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - Anthropic's launch post
- [Agent Skills launch announcement](https://claude.com/blog/skills) - product announcement and availability
- [First impressions of Claude Cowork](https://simonwillison.net/2026/jan/12/claude-cowork/) - background on Cowork, tagged in the video
- [Anthropic makes agent Skills an open standard](https://siliconangle.com/2025/12/18/anthropic-makes-agent-skills-open-standard/) - reporting on the open-standard release


## Video description and verification notes

**This is a 41-second vertical clip at 720x1280 (h265 video, AAC audio, 532 kbps), posted 2026-09-10 by @goldst.ai, whose TikTok channel nickname is also goldst.ai. At capture it held 12,400 plays, 626 likes, 47 comments, 179 reposts, and 789 saves. The audio is credited in the metadata as the track "original sound" by the artist "silly guy," and the description carries three hashtags: #ai, #claude, #cowork. I read all 21 extracted frames at 2-second intervals and all 154 transcript words. There is no screen recording in this video. Every frame is the same selfie-framed shot: a woman in a white-and-black crochet lace sweater seated in a black mesh office chair, beige walls behind her, a white door on the left, a wood-framed door on the right, and a fluorescent drop-ceiling panel glowing above her head. The content is carried entirely by two layers of burned-in text. The first is a karaoke-style word-by-word caption at the top of the frame, which reads in sequence "my skills" (frame 1), "you check" (frame 2), "that all" (frame 3), "200 lines" (frame 4), "to go" (frame 5), "if there" (frame 6), "100 lines" (frame 7), "table of" (frame 8), "analyze the" (frame 9), "not missing" (frame 10), "code for" (frame 11), "of just" (frame 12), "tell me" (frame 13), "so that" (frame 14), "more consistent" (frame 15), "one last" (frame 16), "follows the" (frame 17), "clear concise" (frame 18), "constraints please" (frame 19), "needs these" (frame 20), and "we can" (frame 21). The second layer is a checklist of six green-checkmark labels that accumulates on screen as she speaks and then clears before the end. "✅ Skill <200 lines" appears at frame 4 (about 6 seconds), "✅ Use references" at frame 5 (about 8 seconds), "✅ Add ToC" at frame 8 (about 14 seconds), "✅ Code for consistency" at frame 11 (about 20 seconds), "✅ Assets for format" at frame 13 (about 24 seconds), and "✅Check 3C's" at frame 16 (about 30 seconds). All six are visible together from frame 16 through frame 19, then every overlay is gone by frame 20 (about 38 seconds), leaving only the caption. The spoken request is a single dictated prompt: check that all SKILL.md files are under 200 lines, push the overflow into references, add a table of contents to any reference over a hundred lines, find places that should use custom code instead of written instruction, ask for additional templates, and verify every skill follows "the three c's framework, that they are clear, concise, and that there are no technical constraints."**

## Correction: Anthropic's published ceiling for SKILL.md is 500 lines, and three separate Anthropic sources agree

The first and most prominent overlay in the video, on screen from frame 4 to frame 19, is "✅ Skill <200 lines." The spoken line is "check my existing skills to make sure that all the skill mds are under 200 lines."

Anthropic does not publish a 200-line limit anywhere I could find. The number in the official documentation is 500, and it appears three times in three different places. The [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) page states it twice, once under progressive disclosure patterns ("Keep SKILL.md body under 500 lines for optimal performance") and again under Token budgets ("Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files"). The pre-ship checklist on that same page lists "SKILL.md body is under 500 lines" as a verification item. The [Claude Code skills documentation](https://code.claude.com/docs/en/skills) repeats it as a bolded instruction: "Keep `SKILL.md` under 500 lines." Anthropic's own [skill-creator skill](https://github.com/anthropics/skills/tree/main/skills/skill-creator), published in the anthropics/skills repository, says "SKILL.md body - In context whenever skill triggers (<500 lines ideal)" and then "Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy." The [open Agent Skills specification](https://agentskills.io/specification) gives the same figure: "Keep your main `SKILL.md` under 500 lines."

A 200-line house rule is a defensible personal preference, since a shorter body does cost fewer tokens once the skill triggers. It is not the documented threshold, and a viewer who treats it as one will refactor skills that were already inside Anthropic's guidance.

## Verified: the 100-line table-of-contents rule is real, but Anthropic's own two sources disagree on the number

At frame 7 the caption reads "100 lines," and at frame 8 the overlay "✅ Add ToC" appears. The transcript is "if there are any references that are over a hundred lines make sure that there is a table of contents in there."

This one checks out against the primary source. The [best practices page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) has a section titled "Structure longer reference files with table of contents" that reads: "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." The stated reason is specific. Claude sometimes previews a referenced file with a partial read such as `head -100` rather than reading the whole thing, so a table of contents in the first screen tells it what else is in the file.

Anthropic is not internally consistent on the threshold. The [skill-creator SKILL.md](https://github.com/anthropics/skills/tree/main/skills/skill-creator) in the same company's public repository says "For large reference files (>300 lines), include a table of contents." The video's 100 matches the documentation site. Anyone auditing against 300 is following Anthropic's own tooling instead. Both are Anthropic, and they do not agree.

## Correction: there is no "three C's framework," and "no technical constraints" is the opposite of Anthropic's advice

The last overlay to appear, at frame 16, is "✅Check 3C's." The caption across frames 17 to 19 spells out the content: "follows the," "clear concise," "constraints please." The transcript is "make sure every skill follows the three c's framework that they are clear concise and that there are no technical constraints."

No Anthropic documentation I fetched uses the phrase "three C's" or defines any such framework. The [best practices page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) does open with "Good Skills are concise, well-structured, and tested with real usage" and devotes a section to "Concise is key," so the clarity and conciseness halves have real support. The third item does not.

Anthropic's guidance recommends constraints where the operation is fragile. The same page defines a "low freedom" mode for exactly this case: "Use when: Operations are fragile and error-prone, Consistency is critical, A specific sequence must be followed," and its worked example is a database migration with the literal instruction "Run exactly this script: `python scripts/migrate.py --verify --backup`. Do not modify the command or add additional flags." The analogy Anthropic uses is a narrow bridge with cliffs on both sides, where "There's only one safe way forward. Provide specific guardrails and exact instructions." A blanket audit that strips technical constraints out of skills would remove the mechanism the documentation recommends for the failures the video is complaining about.

There is a separate `compatibility` frontmatter field in the [spec](https://agentskills.io/specification) whose stated purpose is to declare environment requirements, capped at 500 characters. If "no technical constraints" means "do not declare dependencies," that conflicts with the spec's own anti-pattern guidance, which warns against assuming packages are installed.

## Verified: "custom code for consistency" and "assets for templates" both match the published conventions

Two of the six checklist items land cleanly.

"✅ Code for consistency" (frame 11) corresponds to "we should be using custom code for consistency instead of just written instruction." The [best practices page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) states "Prefer scripts for deterministic operations: Write `validate_form.py` rather than asking Claude to generate validation code," and lists the reasons: pre-made scripts are "More reliable than generated code," "Save tokens (no need to include code in context)," "Save time," and "Ensure consistency across uses." The [overview page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) adds the mechanism, which is that a script Claude runs through bash never enters the context window at all, so "Only its output ... consumes tokens."

"✅ Assets for format" (frame 13) corresponds to "tell me if you need any additional templates." The [specification](https://agentskills.io/specification) names `assets/` as the conventional directory for "Templates (document templates, configuration templates), Images (diagrams, examples), Data files (lookup tables, schemas)." Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) describes the same three-directory layout: `scripts/` for "Executable code for deterministic/repetitive tasks," `references/` for "Docs loaded into context as needed," and `assets/` for "Files used in output (templates, icons, fonts)." The overlay's wording maps onto the published convention.

## The stated problem is inconsistent triggering, and not one of the six checks touches the field that controls triggering

The opening line of the clip, visible as the caption "my skills" at frame 1, is "hey claude my skills are not working consistently." Every subsequent check is about the body of SKILL.md, the reference files, the scripts, the assets, or prose style. Triggering is decided before any of that is read.

The [overview page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) is explicit about the loading order. Level 1 is metadata, always loaded at startup, roughly 100 tokens per skill, and consists only of `name` and `description` from the YAML frontmatter. "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." Level 2, the SKILL.md body, is read only after that match happens. Shortening a 250-line body to 199 lines changes nothing about whether the skill fires, because Claude never saw those lines when it decided.

Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) names this failure mode directly and prescribes 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 rewrites "How to build a simple fast dashboard to display internal Anthropic data." into a version that appends "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.'"

The [best practices page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) adds three more triggering rules the clip does not mention. Descriptions must be written in third person, because "The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems." Each skill has exactly one description field, and "Claude uses it to choose the right Skill from potentially 100+ available Skills." The `description` field is capped at 1,024 characters by the [spec](https://agentskills.io/specification), and `name` at 64.

In Claude Code specifically, the [skills documentation](https://code.claude.com/docs/en/skills) lists three more reasons a skill silently fails to fire, none of which a line-count audit would catch. A skill with `disable-model-invocation: true` can only be run manually as `/name`. A skill with `paths` glob patterns activates only when the files being worked on match. And the combined `description` plus `when_to_use` text "is truncated at **1,536 characters** in the skill listing to reduce context usage," so a description padded past that limit loses its tail.

## Unstated cost: the audit is a six-pass sweep over a whole library, requested "quickly"

The closing transcript lines are "please do this quickly because my business needs the skills to automate our work so we can grow faster." The caption at frame 20 reads "needs these" and at frame 21 "we can," and by that point every checklist overlay has been cleared from the screen.

The request as dictated is six independent passes over every skill in a library: count lines in each SKILL.md, relocate overflow into references, count lines in each reference and insert a table of contents, identify instruction blocks that should become scripts, propose new template assets, and run a style review. Each pass requires reading the files, which is the opposite of the progressive disclosure the architecture is built around. The [overview page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) puts the Level 2 budget at "Under 5k tokens" per triggered skill, so a library of twenty skills read in full for an audit is a large read before any editing starts.

Anthropic's recommended method for the underlying problem is slower and evidence-based rather than rule-based. The [best practices page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) says "Create evaluations BEFORE writing extensive documentation," asks for "At least three evaluations created" and "Tested with Haiku, Sonnet, and Opus" in its checklist, and describes an observe-refine-test loop where you watch an actual agent use the skill and bring the specific failure back. Its example of that loop is a triggering-adjacent miss: "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions filtering."

## Context the clip leaves out: skills do not sync across surfaces, and plan access varies

The description tags #cowork. Cowork is Anthropic's agent product for non-developers, announced on 2026-01-12 per [Simon Willison's write-up of the launch](https://simonwillison.net/2026/jan/12/claude-cowork/), initially on macOS for Max subscribers and extended to Pro on 2026-01-16. The current [Cowork page on claude.com](https://claude.com/blog/cowork-research-preview) now says Cowork "is now just Claude" and lists web, desktop, and mobile beta availability across Pro, Max, Team, and Enterprise. Anthropic's [overview page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) mentions Cowork once, in the context of Enterprise skill content scanning.

For anyone running skills as business infrastructure, the overview page documents three limits the clip does not raise. Custom skills "do not sync across surfaces," so a skill uploaded to claude.ai is not available through the API, and Claude Code skills are filesystem-based and separate from both. Sharing scope differs by surface: claude.ai custom skills are "Individual user only. Each team member must upload separately," and "claude.ai does not support centralized admin management or org-wide distribution of custom Skills." On claude.ai, custom skills are "Available on Pro, Max, Team, and Enterprise plans with code execution enabled." On the Claude API, skills run with "No network access" and "No runtime package installation," which constrains the kind of scripts a skill can ship.

Agent Skills launched on 2025-10-16 alongside Anthropic's engineering post [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills). The documentation the clip's rules are being measured against therefore predates the clip by about eleven months. The spec was later moved out of Anthropic's own repository: the `spec/agent-skills-spec.md` file in [anthropics/skills](https://github.com/anthropics/skills) now contains only a pointer reading "The spec is now located at https://agentskills.io/specification." [SiliconANGLE reported](https://siliconangle.com/2025/12/18/anthropic-makes-agent-skills-open-standard/) that the open-standard release happened on 2025-12-18. I did not locate a primary Anthropic announcement page for that date, so treat the exact day as reporting rather than confirmed.

## Key Takeaways

- Correction: the on-screen rule "✅ Skill <200 lines" does not match Anthropic's published figure. The best practices page, the Claude Code skills docs, the skill-creator skill, and the open spec all say to keep SKILL.md under 500 lines.
- Verified: "if there are any references that are over a hundred lines make sure that there is a table of contents" matches the best practices page verbatim, which gives 100 lines as the threshold and partial reads as the reason.
- Partial correction: Anthropic contradicts itself on that threshold. Its own skill-creator skill sets the table-of-contents trigger at more than 300 lines, not 100.
- Correction: there is no Anthropic "three C's framework." Clear and concise are supported by the docs. "No technical constraints" is the reverse of Anthropic's low-freedom guidance, which tells you to write exact commands and guardrails for fragile operations.
- Verified: "use custom code for consistency instead of just written instruction" matches "Prefer scripts for deterministic operations," and "templates" belongs in the `assets/` directory named by the spec.
- Correction of the premise: none of the six checks addresses triggering. Claude decides whether to fire a skill from `name` and `description` alone, loaded at startup at roughly 100 tokens per skill, before it reads a single line of the body.
- Unstated cost: the fix for undertriggering is a rewritten description. Anthropic's skill-creator says Claude undertriggers and tells authors to make descriptions "pushy" with explicit trigger phrases. In Claude Code, `disable-model-invocation`, `paths` globs, and the 1,536-character truncation of `description` plus `when_to_use` are three more silent causes.
- Unstated cost: Anthropic's prescribed method is evaluation-driven, with at least three evals, testing across Haiku, Sonnet, and Opus, and an observe-refine-test loop. That is not compatible with the clip's closing instruction to "do this quickly."
- Unstated cost: custom skills do not sync across claude.ai, the API, and Claude Code. On claude.ai they are per-user with no admin distribution, and they need Pro, Max, Team, or Enterprise with code execution enabled.

## Resources

- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic's primary authoring guide. Source for the 500-line body limit, the 100-line table-of-contents rule, the degrees-of-freedom model, "Prefer scripts for deterministic operations," and the pre-ship checklist.
- [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) — the three progressive disclosure levels with token costs, confirmation that `description` is what Claude matches against, the frontmatter field limits, and the cross-surface sync and plan availability limits.
- [Use Skills in Claude Code](https://code.claude.com/docs/en/skills) — the full frontmatter field table including `when_to_use`, `disable-model-invocation`, `paths`, and `allowed-tools`, the skill location paths, the 1,536-character listing truncation, and a repeat of the 500-line rule.
- [Agent Skills specification](https://agentskills.io/specification) — the open standard. `name` max 64 characters, `description` max 1024, `compatibility` max 500, and the `scripts/`, `references/`, `assets/` directory conventions.
- [anthropics/skills repository](https://github.com/anthropics/skills) — Anthropic's open-source skills. The `skill-creator` skill is the source for the "pushy descriptions" advice, the undertriggering admission, the assets/references/scripts descriptions, and the conflicting 300-line table-of-contents threshold.
- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic's engineering post from the 2025-10-16 launch, with the progressive disclosure framing and the instruction to pay special attention to `name` and `description`.
- [Agent Skills launch announcement](https://claude.com/blog/skills) — product announcement dated 2025-10-16, listing availability across the Claude apps, the developer platform, and Claude Code on Pro, Max, Team, and Enterprise.
- [First impressions of Claude Cowork](https://simonwillison.net/2026/jan/12/claude-cowork/) — contemporaneous account of the 2026-01-12 Cowork research preview, Max-only at launch and extended to Pro on 2026-01-16.
- [Anthropic makes agent Skills an open standard](https://siliconangle.com/2025/12/18/anthropic-makes-agent-skills-open-standard/) — trade reporting on the open-standard release. Cited as reporting because I found no matching primary Anthropic announcement page.
