g4borg
325e278af1
Add plugin skeleton with versioned skill directories, TODO SKILL.md scaffolds with goals for skill-creator, and copy over bevy-skill-research reports from spacecraft into docs/workpad/research/.
131 lines
7.7 KiB
Markdown
131 lines
7.7 KiB
Markdown
# 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
|