reliquary/docs/workpad/research/bevy-skill-research/00-index.md

Bevy Skill Research — Index

Date: 2026-07-07

What We Want to Create

A Claude Code skill for Bevy game engine development — primarily an implementation helper that teaches how to correctly write Bevy code: how to structure plugins, compose systems, define components, handle events, manage hierarchy, process input, and avoid the silent failures that Bevy's flexible ECS makes easy to walk into.

The skill is NOT a migration guide or changelog. Its primary job is: when an agent is writing or modifying Bevy code, it should produce correct, idiomatic code for the current version.

However, because Bevy's rapid release cycle (0.16→0.17→0.18→0.19 in ~18 months) introduces fundamental renames and semantic shifts, the skill also needs version-aware reference material for situations like upgrades. An agent asked to migrate from 0.18 to 0.19 needs to know what changed and why — not just what the current API looks like. So the migration chain knowledge is retained as reference, not thrown away.

How This Research Evolved

Initial idea: upgrade-focused

The research started when we saw an agent fetch Bevy's 0.18→0.19 migration guide during an upgrade task. The question was: should a Bevy skill hold the migration chain as its core content, so agents don't have to fetch and parse migration guides at runtime?

The pivot: implementation-focused

We quickly realized the migration chain is a secondary use case. The primary problem — confirmed by blog posts, community discussions, and this project's 1500+ lines of errata — is that LLMs confidently generate Bevy code against outdated or incorrect patterns during normal day-to-day implementation work. The skill's core content should teach how to write correct Bevy code, organized by topic (plugins, ECS, events, hierarchy, input, camera), not by version transition.

What we researched

Two complementary knowledge sources, reflecting the two purposes:

1. Official API truth (reports 01–06) — how Bevy's subsystems actually work in 0.18/0.19, with version-change annotations where LLMs are most likely to use stale patterns. This is the implementation helper core.

2. Production battle scars (report 07) — gotchas extracted from a production Bevy 0.18 multiplayer game's errata, neutralized into generic examples. These are the "not in any docs" patterns that cost real debugging time. Also implementation helper material.

3. Landscape survey and design options (report 08) — ecosystem survey confirming no adequate skill exists, plus three architectural approaches with tradeoffs. This informs how to build the skill, not what goes in it.

The migration chain knowledge (0.16→0.17→0.18→0.19 breaking changes) is woven into reports 01–06 as annotations rather than being a standalone topic — because the skill's primary audience is an agent writing code today, not an agent performing a version migration. But the annotations are there, and a reference folder can hold the full migration details for when that situation arises.

Why We Did This Research

1. No adequate public skill exists. We surveyed the ecosystem (see report 08) and found nothing usable for Bevy 0.18+. The best candidate (bfollington/terma, 154 installs) covers only up to 0.17 and would actively mislead on current APIs.

2. This project already has better Bevy knowledge than any public skill — but it's locked in project-specific errata and CLAUDE.md files. A skill would extract and generalize that knowledge for reuse.

3. The skill needs to serve two modes: day-to-day implementation (always-loaded, compact) and version migration (on-demand, detailed). The research captures content for both.

4. The skill design has multiple viable approaches with real tradeoffs around size, scope, and maintenance burden (report 08). This research captures the options before committing.

Reports

API Ground Truth (from official docs and migration guides)

#	File	Topic
1	01-plugins.md	Plugin trait lifecycle, dependencies, states, schedules, run conditions
2	02-ecs-core.md	Components, resources, systems, queries, commands, ordering
3	03-hierarchy.md	ChildOf relationships, spawning/querying children, transform propagation
4	04-events-observers.md	Message/Event split (0.18), observers, lifecycle triggers, hooks
5	05-input.md	Keyboard, mouse, gamepad, touch input patterns
6	06-camera-gotchas.md	Camera setup, rendering, coordinates, full LLM-trap table

Production Knowledge and Design

#	File	Topic
7	07-lessons-from-production.md	15 neutralized gotchas from a production Bevy 0.18 multiplayer game
8	08-landscape-and-design-sketch.md	Ecosystem survey, skill architecture options, content priorities

Skill Design Approaches Under Consideration

Approach A: Single Compact Skill + Reference Folder

One bevy skill file (~500 lines) with the critical "don't get this wrong" content always loaded. Deeper reference docs in a references/bevy/ folder that the LLM can read on demand.

• Pro: Low per-trigger context cost, deep knowledge available when needed
• Con: Two things to maintain (skill + references)

Approach B: Single Comprehensive Skill

Everything in one skill file (~1500 lines). Always loaded, always complete.

• Pro: Simple, no secondary lookups needed
• Con: Heavy context cost every trigger (~3-4k tokens), may crowd out project-specific context

Approach C: Multiple Topic Skills

Split into bevy-ecs, bevy-events, bevy-rendering etc. Each triggers independently based on what code is being touched.

• Pro: Granular — only loads what's relevant
• Con: More files, more trigger descriptions to maintain, fragmented knowledge for cross-cutting concerns

Current Recommendation

Approach A — compact always-loaded cheat sheet with reference folder. The skill triggers broadly on any Bevy work, loads the critical renames/gotchas/decision guides (~500 lines), and points to reference docs for deeper dives on specific topics.

Content Priority (What LLMs Get Wrong Most)

Ranked by frequency of incorrect generation:

1. Event → Message rename and the Event/Message split (0.18)
2. ChildOf replacing Parent (0.16+), children iteration patterns
3. -> Result fallible systems (0.18)
4. Coordinate system (+Y up, -Z forward) vs GLTF (+Z forward)
5. Transform propagation timing (PostUpdate, not Update)
6. Resources-as-Components in 0.19
7. Material bind groups — group 3, not group 2
8. State::set() same-state transitions now fire (0.18)
9. Asset cache poisoning via load_with_settings
10. Schedule-dependent spawning breaking plugin expectations