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 / reference validator
- SKILL.md, the format hubSpecification / reference validator
- skills-ref validate (official reference validator, v0.1.5)Specification / reference validator
Strict spec conformance
Conformant. The official reference validator (skills-ref) accepts this.
This is a separate question from the severity above and from which runtimes enforce it below — a rule can be a real, working extension in its home runtime while the reference validator still rejects the file outright, or vice versa. Both facts are reported, never one inferred from the other.
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Not documented | The spec's progressive-disclosure model means the full body loads at activation on every compliant runtime, but no runtime publishes a specific cost or consequence figure for a long body the way index budgets are published for discovery (see SKM-P07) — so no runtime claims a specific effect here. |
| Codex | Not documented | The spec's progressive-disclosure model means the full body loads at activation on every compliant runtime, but no runtime publishes a specific cost or consequence figure for a long body the way index budgets are published for discovery (see SKM-P07) — so no runtime claims a specific effect here. |
| Cursor | Not documented | The spec's progressive-disclosure model means the full body loads at activation on every compliant runtime, but no runtime publishes a specific cost or consequence figure for a long body the way index budgets are published for discovery (see SKM-P07) — so no runtime claims a specific effect here. |
| OpenClaw | Not documented | The spec's progressive-disclosure model means the full body loads at activation on every compliant runtime, but no runtime publishes a specific cost or consequence figure for a long body the way index budgets are published for discovery (see SKM-P07) — so no runtime claims a specific effect here. |
| Hermes Agent | Not documented | The spec's progressive-disclosure model means the full body loads at activation on every compliant runtime, but no runtime publishes a specific cost or consequence figure for a long body the way index budgets are published for discovery (see SKM-P07) — so no runtime claims a specific effect here. |
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.