SKM-P07 · Portability
`description` is longer than the tightest runtime budget
1,024 characters is the spec ceiling, but OpenClaw's own authoring guidance asks for under 160 and practical Claude Code reports suggest under 200 — a description written for the tightest constraint is safe everywhere.
What the rule is
The specification permits up to 1,024 characters, but every runtime with a published index budget is tighter than that in practice: OpenClaw's own authoring guidance asks for descriptions under roughly 160 characters, and a verified report from a Claude Code user with nine plugin skills found only about two reaching chat, with headroom recovered by keeping descriptions under about 200 characters.
Cursor and Hermes Agent publish no index-budget figure at all, which doesn't mean there isn't a cost — it means this tool can't state a specific number for either.
Unlike `paths`, `context`, or `disable-model-invocation`, this isn't an extra field at all — it's a length concern on `description` itself, well inside the specification's own 1,024-character ceiling. The official reference validator has no opinion on it; it only enforces the hard 1,024-character limit (see SKM-D02).
Where it comes from
- OpenClaw — official skills documentationRuntime documentation
- Claude Code — official skills documentationRuntime documentation
- Codex — official skills documentationRuntime documentation
- Agent Skills compatibilityAgentSkills.site
- anthropics/claude-code #40774 — plugin skills excluded past the index budgetVerified issue — closed
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 | Degrades | ~1% of context for the whole skill index; a real report saw about two of nine plugin skills reach chat past this budget. |
| Codex | Degrades | 2% of the context window or 8,000 characters, whichever is smaller, shared across the whole skill index. |
| Cursor | Not documented | No index budget is published for Cursor. |
| OpenClaw | Degrades | ~97 characters per skill plus field lengths against a configurable ceiling; degrades by shortening then dropping descriptions past it. |
| Hermes Agent | Not documented | No index budget is published for Hermes Agent. |
How to fix it
- Write the description for the tightest constraint rather than the spec's ceiling — under roughly 160 characters, trigger-focused, with the most important terms first. A description written this way is safe on every runtime this site has verified.
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.