Bevy Skill

A portable, battle-tested knowledge pack for building games with the Bevy game engine — ECS architecture, system ordering, UI, build strategy, common pitfalls, and version-migration gotchas.

It's packaged as an agent skill (a SKILL.md plus reference docs), so Claude Code and other skill-aware agents can load it automatically — but it's really just well-organized Markdown. Read it yourself, drop it in a wiki, or feed it to any assistant.

Currently targets Bevy 0.19 (with a documented 0.18 → 0.19 migration section). The API notes are kept version-accurate; the ECS/design guidance is version-agnostic.

What's inside

bevy/
├── SKILL.md                          # entry point / overview
├── references/
│   ├── bevy_specific_tips.md         # API notes, 0.18→0.19 migration, build/perf, DDD for ECS
│   ├── common_pitfalls.md            # the mistakes that bite, and their fixes
│   ├── ecs_patterns.md               # component/query/system design patterns
│   ├── project_structure.md          # recommended module/file layout
│   └── ui_development.md             # Bevy UI (flexbox) patterns
└── evals/
    └── evals.json                    # prompt/expectation scenarios to grade the skill

Evals

bevy/evals/evals.json is a self-contained set of scenarios for grading the skill (or any Bevy assistant). Each entry has a prompt, an expected_output summary, and a list of concrete expectations — checkable claims a judge (LLM or human) scores pass/fail. They cover the 0.18→0.19 migration, frame-rate- independent motion, query-conflict resolution, deprecated bundles, plugin architecture, and the Windows wgpu/windows build split. Add a scenario when you add a tip, so the guidance stays verifiable.

Use it

As an agent skill (Claude Code, etc.): skills live in a .claude/skills/ directory. Copy the bevy/ folder into either:

• Per-project: <your-project>/.claude/skills/bevy/
• Global (all projects): ~/.claude/skills/bevy/

# into a project:
cp -r bevy /path/to/your-project/.claude/skills/
# or globally:
cp -r bevy ~/.claude/skills/

Claude Code discovers it automatically; invoke explicitly with /bevy.

As plain docs: just read bevy/SKILL.md and the files under bevy/references/, or paste the relevant one into whatever assistant you use.

Scope & accuracy

• API-specific advice (materials, messages/events, queries, colors, prepass, scene system) is pinned to a Bevy version and labelled as such — check the version header in bevy_specific_tips.md before applying it to a different release.
• The migration gotchas were verified against a real, large 0.18.1 → 0.19.0 upgrade, not the changelog alone.

Contributing

Corrections and version bumps welcome — especially freshly-verified migration deltas for new Bevy releases. Please note which Bevy version you verified against.

License

MIT — see LICENSE.