SKM-B01 · Warning
Body is longer than 500 lines
The specification recommends keeping SKILL.md under 500 lines and moving detail into `references/`.
What the rule is
The specification recommends keeping SKILL.md under 500 lines, with additional detail moved into `references/` files instead. This is a recommendation, not a hard constraint like the `name` and `description` rules — no documented behaviour treats it as a hard failure.
The reason it matters anyway: the full body loads into context the moment the skill activates, on every runtime. A long body isn't just harder to maintain — it's a real, recurring context cost every time the skill fires.
Where it comes from
- Agent Skills — SpecificationSpecification
- SKILL.md, the format hubSpecification
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Degrades | The full body loads the moment the skill activates, on every runtime — a long body is a real context cost, not just untidy, even though no runtime hard-rejects it. |
| Codex | Degrades | The full body loads the moment the skill activates, on every runtime — a long body is a real context cost, not just untidy, even though no runtime hard-rejects it. |
| Cursor | Degrades | The full body loads the moment the skill activates, on every runtime — a long body is a real context cost, not just untidy, even though no runtime hard-rejects it. |
| OpenClaw | Degrades | The full body loads the moment the skill activates, on every runtime — a long body is a real context cost, not just untidy, even though no runtime hard-rejects it. |
| Hermes Agent | Degrades | The full body loads the moment the skill activates, on every runtime — a long body is a real context cost, not just untidy, even though no runtime hard-rejects it. |
How to fix it
- Move detailed reference material, examples, or edge-case handling out of SKILL.md and into a `references/` file, leaving the main body as the core procedure.
- Keep only what the agent needs on every activation in the body itself.
Elsewhere
- SKILL.md, the formatThe full frontmatter field table this rule is drawn from.
- Agent Skills Not WorkingThe diagnostic reference this rule’s portability and failure evidence comes from.
- All rulesEvery check the validator runs, grouped by class.