# 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](https://tobyhede.com/blog/hard-mode/) (building a Bevy 0.17 space sim): Claude was "nearly always wrong" on unstable APIs without grounding. From [Chier Hu's blog post](https://chierfandev.com/claude-code-for-game-development/): 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