bevy-plugin/skills/bevy-game-engine/SKILL.md is 10,189 chars, just over the 10,000-char WARN threshold. Advisory only — the ERROR ceiling is 26,000 — but it has no sidecar at all, so the cheap fix is available.
How it crossed
It sat at 9,929 chars — 71 chars of headroom — before #2205, which added a two-line cargo generate cross-reference to the project-setup block. That addition corrected genuinely stale guidance (the skill said cargo new my_game; Bevy's own quickstart is cargo generate --git .../bevy_new_2d), and the template URL alone is 47 chars.
I tried three progressively terser forms during that PR: the tightest one still carrying a runnable command lands at 10,062, and even a prose-only pointer with no command lands at 10,003. There is no version of that cross-reference that fits under the line. The file was one edit away from crossing regardless of which edit came first — the right fix is structural, not another round of word-shaving.
Suggested fix
Extract to a sidecar — and prefer the multi-file references/ shape over a single REFERENCE.md, per .claude/rules/skill-quality.md § references/ and .claude/rules/context-engineering.md C3 (the corpus has 129 single sidecars and, as of #2143, one references/ split).
Candidate splits by consumer path, not by size:
| Reference file |
Carries |
rendering.md |
2D/3D rendering, sprites, meshes, materials, lighting, cameras, shaders |
assets-and-states.md |
Asset loading/handles, game states, transitions, conditional systems |
Keep in the body: the ECS core, project setup, the essential-commands block, and the bevy-ecs-patterns disambiguation table (two sibling skills compete for the same intent, which is exactly the case context-engineering.md says the When-to-Use table earns its tokens).
bevy-ecs-patterns is 12,146 chars and also in the WARN band — same treatment, and the two are natural companions since the split has to decide which skill owns each ECS topic.
Not urgent
WARN, not ERROR; 47 other skills sit in the same band. Filed so the reason it crossed is on record rather than rediscovered, and so the fix is a deliberate split rather than a reflex trim of whatever line happens to be newest.
Related
bevy-plugin/skills/bevy-game-engine/SKILL.mdis 10,189 chars, just over the 10,000-char WARN threshold. Advisory only — the ERROR ceiling is 26,000 — but it has no sidecar at all, so the cheap fix is available.How it crossed
It sat at 9,929 chars — 71 chars of headroom — before #2205, which added a two-line
cargo generatecross-reference to the project-setup block. That addition corrected genuinely stale guidance (the skill saidcargo new my_game; Bevy's own quickstart iscargo generate --git .../bevy_new_2d), and the template URL alone is 47 chars.I tried three progressively terser forms during that PR: the tightest one still carrying a runnable command lands at 10,062, and even a prose-only pointer with no command lands at 10,003. There is no version of that cross-reference that fits under the line. The file was one edit away from crossing regardless of which edit came first — the right fix is structural, not another round of word-shaving.
Suggested fix
Extract to a sidecar — and prefer the multi-file
references/shape over a singleREFERENCE.md, per.claude/rules/skill-quality.md§references/and.claude/rules/context-engineering.mdC3 (the corpus has 129 single sidecars and, as of #2143, onereferences/split).Candidate splits by consumer path, not by size:
rendering.mdassets-and-states.mdKeep in the body: the ECS core, project setup, the essential-commands block, and the
bevy-ecs-patternsdisambiguation table (two sibling skills compete for the same intent, which is exactly the casecontext-engineering.mdsays the When-to-Use table earns its tokens).bevy-ecs-patternsis 12,146 chars and also in the WARN band — same treatment, and the two are natural companions since the split has to decide which skill owns each ECS topic.Not urgent
WARN, not ERROR; 47 other skills sit in the same band. Filed so the reason it crossed is on record rather than rediscovered, and so the fix is a deliberate split rather than a reflex trim of whatever line happens to be newest.
Related
parallel-agent-dispatch'sreferences/split, the pattern to copy.claude/rules/skill-quality.md— size bands and thereferences/conventions