Anthropic recommends keeping a Claude Code skill’s SKILL.md under 500 lines and moving detailed reference material into separate files. That is guidance, not a hard technical limit or a proven cutoff: the goal is to keep the skill’s main instructions focused while making additional detail available when needed.
What the 500-line recommendation applies to
Anthropic’s Claude Code documentation, “Extend Claude with skills”, says: “Keep SKILL.md under 500 lines. Move detailed reference material to separate files.” This recommendation is specifically about a skill’s main instruction file—not every file Claude can read.
A skill’s SKILL.md should explain the skill’s purpose and workflow, with enough direction to help Claude use it. Long API specifications, reference material, and collections of examples can live in neighboring files instead. Claude can access those supporting files when needed, rather than loading all their contents every time the skill runs.
How to split a long SKILL.md
- Keep the core in
SKILL.md. Include the skill’s purpose, essential steps, and navigation to further material. - Move detail into separate files. For example, put extensive API details in
reference.mdand worked examples inexamples.md. Anthropic’s sample skill layout uses files with those names alongsideSKILL.md. - Link to each file from
SKILL.md. Briefly describe what it contains and when Claude should consult it. A bare list of filenames gives less useful direction than a short, task-specific description. - Check the result. Keep the main file below 500 lines and make sure its links and instructions make clear which reference applies to which task.
This arrangement separates always-needed orientation from detail that is relevant only to certain requests. The recommendation does not imply that a skill stops working at line 500; it is a practical way to organize instructions and supporting information.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How SKILL.md differs from CLAUDE.md
CLAUDE.md serves a different purpose: it provides persistent project or personal instructions for Claude Code. Anthropic’s current memory guidance, “How Claude remembers your project”, says to target under 200 lines per file. That is separate from the under-500-line recommendation for a skill’s SKILL.md.
| File or feature | Purpose | Guidance and loading behavior |
|---|---|---|
SKILL.md |
Workflow and task-specific instructions packaged as a Claude Code skill. | Anthropic recommends under 500 lines. A skill’s contents load when the skill is invoked; supporting references can be consulted as needed. |
CLAUDE.md |
Persistent project or personal instructions, such as build commands, conventions, and project layout. | Anthropic targets under 200 lines per file. Memory files are available at session start. |
@path import in CLAUDE.md |
Organizes memory content across files. | Imported files load at launch too, so imports organize the instructions but do not reduce their startup context cost. |
| Path-scoped rules | Guidance that applies only to matching files or areas of a project. | Rules load when Claude works with matching files, which can avoid adding irrelevant guidance to every session. |
Anthropic’s memory documentation advises: “The more specific and concise your instructions, the more consistently Claude follows them.” Keep CLAUDE.md for facts and rules Claude should have broadly, and use a skill for a procedure needed only for particular tasks. For guidance tied to particular files, path-scoped rules can be a better fit than adding it to persistent project instructions.
Rank #2
Is 500 lines a proven cutoff?
No controlled test establishing a sharp improvement at exactly 500 lines is cited in the reviewed official guidance. Treat the number as Anthropic’s practical recommendation for structuring a skill—not a technical cap, universal threshold, or guarantee that a shorter file will produce better answers.
Anthropic’s separate prompting best practices discuss organizing long inputs: put longform material before the query and ask Claude to quote relevant passages before acting on lengthy documents. That page reports up to 30 percent improvement in tests when queries appear at the end, particularly for complex, multi-document inputs. The result concerns prompt ordering; it is not evidence for the 500-line recommendation.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Quick Recap
Best Value
Rank #3
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
