The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →For a Claude Code skill, keep SKILL.md under 500 lines and move detailed references, API specifications, and examples into separate files beside it. Anthropic recommends linking those files from SKILL.md and explaining what each contains and when Claude should consult it. This is practical guidance, not a hard technical limit or a proven performance threshold.
Why split a long SKILL.md?
A skill’s SKILL.md should focus on its purpose and the instructions Claude needs when the skill is used. Extensive reference material can live in separate files instead of making the main instruction file carry every detail. Anthropic’s Claude Code skills documentation says: “Keep SKILL.md under 500 lines. Move detailed reference material to separate files.”
![Claude AI for Beginners Bible: [5 in 1] The Ultimate Guide to Automate Your Work, Save Hours Every Week, and Use AI for Real-World Results](https://m.media-amazon.com/images/I/415+fSJacsL._SL160_.jpg)
The distinction matters for context: supporting files can be made available when needed without loading all their contents every time the skill runs. That lets the main file stay focused while preserving access to detail for tasks that require it.
How to organize a skill around the recommendation
- Keep the main file focused. Use
SKILL.mdfor the skill’s purpose, workflow, and navigation to supporting material. - Move detail into adjacent files. Put lengthy API references, example collections, or other material that is not needed for every invocation in separate files. Anthropic’s sample layout includes
reference.mdandexamples.mdbesideSKILL.md. - Link and label each reference. In
SKILL.md, link to each supporting file and briefly state what it contains and when Claude should consult it. A link without that context gives less guidance about when the detail is relevant.
The goal is not to split content arbitrarily at line 500. Keep frequently needed instructions in the main file; move detailed material that only some tasks need into references. The recommendation gives a useful size target, while the organization should still reflect how the skill is used.
Recommended Free Tools
#1 Best Overall
Do not confuse SKILL.md with CLAUDE.md
These files serve different purposes and have different size guidance. A skill provides procedures or information for particular tasks; CLAUDE.md provides persistent project or personal instructions. Anthropic’s current guidance targets CLAUDE.md files under 200 lines, rather than applying the 500-line recommendation to them.
| File or feature | Purpose | Current guidance and context behavior |
|---|---|---|
SKILL.md |
Instructions for a skill’s task-specific workflow | Keep under 500 lines; the skill’s contents load when invoked, and supporting references can be consulted as needed. Source: Anthropic’s skills documentation. |
CLAUDE.md |
Persistent project or personal instructions, such as build commands, conventions, and project layout | Target under 200 lines per file; memory loads at session start. Source: Anthropic’s memory documentation. |
@path import in CLAUDE.md |
Organize instructions across files | Imported files also load at launch, so imports organize content but do not reduce that context cost. Source: Anthropic’s memory documentation. |
| Path-scoped rules | Guidance that applies only when Claude works with matching files | Load selectively for matching files, which can reduce irrelevant instruction noise and save context. Source: Anthropic’s memory documentation. |
What belongs in project memory instead?
Keep CLAUDE.md for facts and rules Claude should have in every session: for example, build commands, coding conventions, project layout, or a durable “always do this” instruction. Put multi-step procedures or guidance relevant only to a particular code area in a skill or path-scoped rule. Anthropic’s memory documentation advises: “The more specific and concise your instructions, the more consistently Claude follows them.”
An @path import can help organize a longer memory file, but it does not make imported content cheaper in context when those files load at launch. If guidance should apply only to work on certain files, path-scoped rules are a better fit than loading that guidance for every session.
Is 500 lines a hard limit or a proven cutoff?
No. Anthropic presents under 500 lines as a recommendation for a skill’s SKILL.md, not as a technical boundary after which a skill stops working. The reviewed official guidance does not establish a controlled experiment showing a sharp drop in results at exactly 500 lines.
Anthropic’s separate prompting best practices report tests in which putting a query after longform data improved quality by up to 30 percent, especially for complex, multi-document inputs. That finding concerns the ordering of information in prompts; it does not test skill-file length and should not be used as evidence for a 500-line threshold.
Quick Recap
Rank #4
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.
