If my Skill's content is genuinely complex, won't forcing it under 500 lines sacrifice completeness?
There's a misunderstanding behind this concern: the 500-line limit applies to the body, not to the total information a Skill can convey. You don't need to sacrifice completeness — you need to redistribute it. Keep the core logic that Claude will need on every single trigger in the body, and move detail that's only needed in specific situations into extension files.
In practice, a genuinely complex Skill usually signals that it's covering multiple distinct use cases — and the better question to ask is whether those cases are being described too broadly, when they could instead be split into several focused Skills that each trigger on their own. A Skill that does one thing well typically triggers more accurately, and is easier to maintain, than one giant Skill trying to cover everything.
How should the folder structure be organized for a Skill with multiple files?
The common convention is one dedicated folder per Skill, with SKILL.md as the main entry point, alongside subdirectories like scripts/ (executable code, typically designed as small CLI tools), references/ (supplementary background material like schemas or cheat sheets), and assets/ (templates or static files used in output), organized by content type.
The logic behind this structure aligns with the three-layer disclosure mechanism: SKILL.md handles navigation and high-level process description, while the subdirectories hold content that's "read only when needed" or "executed only when needed." Link depth is best kept to a single level — SKILL.md links directly to files under references/, without those files linking further to yet another layer. Otherwise Claude ends up chaining through multiple jumps just to look up one detail, defeating the cost savings Progressive Disclosure was meant to provide in the first place.
Beyond clearly stating functionality, what practical details in the description field get overlooked?
The most commonly overlooked point is that description should cover both "what this Skill does" and "when it should be used," not just a functional description. For example, writing just "handles Git commit messages" is vague, whereas "use when writing a commit message for staged changes" covers both function and trigger context, letting Claude match user requests more accurately.
Another easily overlooked point is concrete keywords. Users rarely type in formal documentation-style language when making requests — they tend to use more conversational phrasing. When description covers the actual words and situational phrasing users are likely to say, trigger accuracy improves noticeably compared to a description that just stacks technical terminology. This is also why a Skill that does one thing tends to trigger better — a single, focused function makes it possible to write a description that's genuinely specific.
I already have several Skill.md files in use that exceed 500 lines — do I need to rewrite them immediately?
There's no need to panic and rewrite everything at once, but it's worth prioritizing a review. The signal for whether a given Skill deserves priority is how often it triggers and whether triggering it tends to coincide with other tasks running at the same time. An oversized Skill that triggers frequently is diluting other context content every single time, which makes it the highest priority; a Skill that rarely triggers carries less urgency even if it's well over 500 lines.
A sensible rewrite order: first review description to confirm trigger accuracy isn't already an issue; then sort the body content into "core logic" versus "situational detail," moving situational detail into a temporary reference.md first; finally circle back to confirm the body has naturally slimmed down to a reasonable range. This gradual splitting approach carries less risk than a full rewrite all at once, and makes it easier to confirm the Skill still works correctly at every step.
The most common mistake when writing your first Skill isn't writing too little — it's writing too much. Every possible detail, every edge case, every piece of reference material gets crammed into a single Skill.md, on the assumption that including everything can't hurt. This instinct runs directly against how Skills are actually designed to work.
Anthropic's official documentation gives a specific threshold: keep the SKILL.md body under 500 lines, and split anything beyond that into separate files. This isn't an arbitrary number — it maps directly onto the three-layer progressive disclosure mechanism built into the Skill architecture. Understanding how those three layers work reveals that "how long should it be" is actually the wrong first question to ask.
Loading a Skill happens in three distinct stages, and the amount of content read at each stage differs dramatically. The first layer happens at startup: Claude only loads each Skill's YAML frontmatter — the name and description fields — which costs only a few dozen tokens per Skill, so even a system with dozens of Skills installed carries a light startup load.
The second layer happens on trigger: only when a user's request matches the situation described in a Skill's description does Claude load that Skill's full SKILL.md body into context. This is exactly the layer the 500-line guideline is managing — the longer the body, the more content floods in at once when triggered, diluting whatever else in context is actually relevant to the task.
The third layer is extended reading: if the SKILL.md links to other files (like forms.md or reference.md), Claude only reads those when the specific detail is actually needed — triggering the Skill doesn't cause all linked files to load at once.
This is the point most likely to be misunderstood: the 500-line limit applies to the SKILL.md body, not to the total amount of knowledge a Skill can contain. In the official documentation's PDF-processing Skill example, the SKILL.md body keeps only the core logic and the most commonly used operations, while form-filling — a feature used less often but carrying a lot of detail — gets moved into a separate forms.md, which Claude only reads when a user actually asks to fill out a form.
In other words, there's effectively no cap on the total knowledge a Skill can carry — what's limited is only "how much floods into context on the first wave when triggered." Think of the mechanism like a well-organized manual: a table of contents first, then the relevant chapter, and only then the detailed specs buried in an appendix — readers shouldn't have to read the entire book cover to cover just to look up one small detail.
The first layer of disclosure runs entirely on the description field — Claude decides whether to trigger a given Skill by matching this description text against the semantics of the user's request. If description is written vaguely (say, just "handles PDF-related work"), Claude may fail to trigger the Skill even in situations where it's exactly what's needed. Conversely, a description specific enough to include the actual keywords and situational language a user might use noticeably improves trigger accuracy.
This is also why "how long should SKILL.md be" isn't the first question worth asking — no matter how lean the body is, it doesn't matter if description isn't precise enough, because Claude never gets to the step of reading the body in the first place.
The practical rule of thumb is straightforward: the SKILL.md body should hold only high-level logic and the most frequently used steps. Any section that runs to several hundred words, or covers content that's "rarely needed but requires full detail in the few cases it is" (specific error-code handling, advanced parameter configuration), is a signal to split it into a separate file. Split files are best kept to a single level of link depth, so Claude doesn't have to chain through several layers of documents just to look up one detail.
Before writing your next SKILL.md, get the description right first — specific enough that Claude can tell at a glance whether a given request should trigger it. Then keep the body scoped to core logic and high-frequency operations, and move anything detailed, low-frequency, but bulky into a separate file without hesitation. 500 lines isn't a hard ceiling — it's a reminder that if you've hit that volume without splitting anything out, the body has likely started carrying a role it was never meant to carry.