reliquary/docs/workpad/research/bevy-skill-research/08-landscape-and-design-sketch.md

Bevy Skill Research: Landscape Survey & Design Sketch

Date: 2026-07-07
Purpose: Capture the initial motivation, survey of existing skills, and design approaches before committing to a specific skill architecture.

Why This Research Exists

The #1 problem with LLM-assisted Bevy development — confirmed by blog posts, community discussions, and this project's own errata — is that Claude confidently uses outdated Bevy APIs. Bevy's rapid release cycle (0.16→0.17→0.18→0.19 in ~18 months) introduces fundamental renames and semantic shifts that make pre-training knowledge actively harmful. A dedicated skill would serve as grounded API truth, loaded into context whenever Bevy code is being written.

The Problem in Practice

From Toby Hede's blog post (building a Bevy 0.17 space sim): Claude was "nearly always wrong" on unstable APIs without grounding. From Chier Hu's blog post: Bevy is a "good conceptual fit" for LLMs due to ECS patterns, but "punished by API instability."

This project's own errata file (1500+ lines) documents dozens of cases where incorrect Bevy/Lightyear patterns were confidently generated, costing hours of debugging per incident.

Landscape Survey: Existing Bevy Skills

bfollington/terma — Best Candidate, Outdated

• Repo: https://github.com/bfollington/terma
• Marketplace: https://crossaitools.com/skills/bfollington/terma/bevy
• Install: npx skills add https://github.com/bfollington/terma --skill bevy
• Stats: 154 installs, 46 stars
• Coverage: ECS patterns, component design, system ordering, plugin structure, query optimization
• Version: Only covers up to Bevy 0.17
• Verdict: Would actively mislead on 0.18+ APIs (EventWriter vs MessageWriter, Parent vs ChildOf, WinitPlugin generics, etc.)

laurigates/claude-plugins — Generic, Outdated

• Repo: https://github.com/laurigates/claude-plugins/tree/main/bevy-plugin
• Marketplace: https://smithery.ai/skills/laurigates/bevy-game-engine
• Coverage: References outdated dependencies (bevy_rapier2d/3d instead of Avian), no version pinning
• Verdict: Too generic and outdated to be useful

Official Bevy — No Claude Integration

• https://github.com/bevyengine/bevy has no .claude directory, no CLAUDE.md, no AGENTS.md
• Bevy has a no-LLM-contributions policy for upstream PRs
• Bevy's own docs are authoritative but not formatted for skill consumption

Curated Lists — No Bevy Skills

• awesome-claude-skills (https://github.com/travisvn/awesome-claude-skills) — no Bevy entry
• awesome-claude-code-and-skills (https://github.com/GetBindu/awesome-claude-code-and-skills) — no Bevy (lists htdt/godogen for Godot/Bevy/Babylon.js, but that's an autonomous agent, not a skill)
• claude-skill-registry (https://github.com/majiayu000/claude-skill-registry) — no Bevy skill

Related Tools (Not Coding Skills)

• bevy_brp_mcp (https://github.com/natepiano/bevy_brp) — MCP server for controlling running Bevy apps via Bevy Remote Protocol; runtime tooling, not a coding skill
• bevy_debugger_mcp (https://github.com/Ladvien/bevy_debugger_mcp) — natural-language game-state debugging via BRP

Bottom Line

Nothing publicly available is adequate for Bevy 0.18+. This project's own CLAUDE.md / errata is already significantly more detailed and version-accurate than anything published. A new skill would need to be built from scratch.

---

Design Sketch: What a Proper Bevy Skill Could Look Like

A skill worth building would serve as grounded API truth that prevents the #1 problem: Claude confidently using outdated Bevy APIs.

Core Content Layers

1. Current API reference (0.18/0.19) — the breaking changes, correct patterns, what moved where
2. Migration chain (0.16 → 0.17 → 0.18 → 0.19) — so it can reason about upgrade context
3. Pattern library — ECS idioms, plugin composition, system ordering, queries, relationships
4. Common traps — the things Claude gets wrong most (ChildOf vs Parent, WinitPlugin generics, bind groups, Message vs Event, etc.)
5. Production lessons — real gotchas from shipping code that go beyond API docs (asset cache poisoning, schedule timing, silent failures)

Key Design Decisions

Scope: Generic Bevy vs Bevy+Ecosystem?

Approach	Pros	Cons
Generic Bevy only	Broadly useful, smaller context cost, easier to maintain	Misses ecosystem gotchas (physics, particles, networking)
Bevy + ecosystem (Avian, Hanabi, egui)	More complete, catches cross-plugin traps	Larger, harder to maintain, ecosystem versions diverge
Bevy core + separate ecosystem skills	Modular, each triggers independently	More skill files, more trigger logic to maintain

Recommendation: Start with generic Bevy core. Ecosystem skills (Avian, Lightyear, etc.) can be separate and project-specific.

Update Strategy

Approach	Pros	Cons
Hand-curated from migration guides	Precise, tested, trustworthy	Manual effort each release
Scrape/embed migration guides	Automated, always current	Raw guides are verbose, may include irrelevant detail
Hybrid: hand-curated core + reference docs folder	Best of both — compact skill, deep docs on demand	Two things to maintain

Recommendation: Hybrid. The skill itself is a compact cheat sheet (~500 lines). Deeper reference docs live in a folder the skill can point to.

Size and Context Budget

A skill is loaded into context every time it triggers. The research produced ~800-1000 lines of reference across 7 reports. This needs compression.

Approach	Context cost	Coverage
Single file, everything	~2-3k tokens	Complete but heavy per-trigger
Compact skill + reference folder	~500-800 tokens always, more on demand	Tiered — critical stuff always, detail when needed
Multiple skills (bevy-ecs, bevy-events, bevy-rendering)	~300-500 tokens each, only relevant one loads	Granular but fragmented knowledge

Recommendation: Single skill with compact always-loaded content (gotchas, renames, decision guides) plus references/bevy/ folder for deeper dives. The skill triggers broadly on any Bevy code work, but only the critical "don't get this wrong" content eats context every time.

Content Priority: What LLMs Get Wrong Most

Ranked by frequency of incorrect generation (from this project's errata and community reports):

1. Event → Message rename and the Event/Message split (0.18) — highest confusion rate
2. ChildOf replacing Parent (0.16+), children iteration patterns
3. -> Result fallible systems (0.18) — LLMs still generate infallible signatures
4. Coordinate system (+Y up, -Z forward) vs GLTF (+Z forward) — directional code wrong ~50% of the time
5. Transform propagation timing (PostUpdate, not Update) — stale reads
6. Resources-as-Components in 0.19 — broad query contamination
7. Material bind groups — group 3, not group 2
8. State::set() behavior change — same-state transitions now fire
9. Asset cache dedup — load_with_settings poisoning
10. Schedule-dependent spawning — entities invisible to certain plugins

Trigger Design

The skill should trigger when:

• Any .rs file is being edited that imports from bevy::*
• User mentions Bevy, ECS, components, systems, plugins, queries
• Code involves entity spawning, hierarchy, events/messages, input handling
• Camera, rendering, material, or shader code is being written

It should NOT trigger for:

• Pure Rust code with no Bevy involvement
• Other game engines (Godot, Unity)
• Non-game Rust projects