Skip to content

feat: Add package skills for the Flame CLI and Flame best practices - #4223

Merged
spydon merged 6 commits into
mainfrom
package-skills
Nov 16, 2026
Merged

spydon merged 6 commits into
mainfrom
package-skills

Conversation

@spydon

@spydon spydon commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Description

This adds package skills to the flame package, so that AI
coding agents in a Flame project can install them with dart run skills get and follow them.

The skills live in packages/flame/skills/ since a game depends on flame directly, while
flame_cli is usually activated globally and would not be picked up by the installer.

  • flame-cli: How to use the flame command to create a game and to run, look at, inspect,
    control and play it. It has rules such as starting the game with flame run in the background,
    using --json and the exit codes, pausing before snapshots, using flame wait instead of
    sleeping and when to use reload --merge, and walks through the common tasks. A condensed
    reference of every command and option is in references/commands.md.
  • flame-best-practices: Rules for building a Flame 2 game, covering the game structure with the
    world, camera and viewport, the component lifecycle, input, collision detection, assets with
    full paths, effects and timers, overlays and routing, performance (with a section on not
    creating objects in update and render), hot reload shadows, testing with flame_test, and
    the removed Flame 1 APIs to avoid.

The code examples in the skills use primary constructors, since flame_lint enables
use_primary_constructors, and they pass flutter analyze with flame_lint.

skills_lint is added as a development dependency of flame, configured in skills_lint.yaml,
and run by test/skills_lint_test.dart. It checks the skill names, the frontmatter, that every
relative link resolves within its skill, and that dart pub publish includes the skills.

The root README, which is also the README of the flame package, gets a section about the skills
that tells agents to install them with dart run skills@ get.

Checklist

  • I have followed the Contributor Guide when preparing my PR.
  • I have updated/added tests for ALL new/updated/fixed functionality.
  • [-] I have updated/added relevant documentation in docs and added dartdoc comments with ///.
  • [-] I have updated/added relevant examples in examples or docs.

Breaking Change?

  • Yes, this PR is a breaking change.
  • No, this PR is not a breaking change.

Related Issues

Adds two package skills to the flame package, which consumers install with `dart run skills get`:

- flame-cli: How to use the flame command to create, run, look at, inspect, control and play a game.
- flame-best-practices: Rules for structuring a Flame 2 game, the component lifecycle, input, collisions, assets, effects, overlays, performance, hot reload and testing.

The skills are validated by skills_lint in test/skills_lint_test.dart.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The CLI guidance contains incorrect reload and input workflows, unreliable startup and failure handling, and misleading JSON output claims.

7 open issues
What changed in this PR

Adds installable AI-agent skills to the flame package, covering Flame 2 development practices and CLI workflows for creating, running, and inspecting games.

Changes:

  • Adds best-practices and CLI skills, including a command reference.
  • Adds skill validation configuration, a development dependency, and a test.
  • Documents skill installation in the root README.
File Description
README.md Documents available skills and installation commands.
packages/​flame/​test/​skills_lint_test.dart Validates skill configuration and content.
packages/​flame/​skills/​flame-cli/​SKILL.md Describes CLI workflows for development and game inspection.
packages/​flame/​skills/​flame-cli/​references/​commands.md Provides command, option, and output references.
packages/​flame/​skills/​flame-best-practices/​SKILL.md Documents Flame 2 patterns and examples.
packages/​flame/​skills_lint.yaml Configures skill naming, links, and publication checks.
packages/​flame/​pubspec.yaml Adds the skills_lint development dependency.

Review effort: Balanced

spydon and others added 2 commits November 11, 2026 19:10
Bound the startup wait and wait for a loaded component, document the JSON output exceptions, run the merging reload instead of a plain one, hold keys while stepping, keep the assertion exit code in the end to end check, and stop recommending --machine for flame run.
@macedondev

Copy link
Copy Markdown

It would be great if each package had its own skills, making it easier for both AI and developers to provide context and build faster.

@ufrshubham ufrshubham left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Just needs some points for the culling APIs

@spydon
spydon merged commit 1d69da2 into main Nov 16, 2026
9 checks passed
@spydon
spydon deleted the package-skills branch November 16, 2026 18:52
LordixDemon added a commit to LordixDemon/flame that referenced this pull request Nov 17, 2026
Brings in the upstream fix for findPostProcessFromContext (flame-engine#4221), the
package skills (flame-engine#4223) and documentation link fixes (flame-engine#4234, flame-engine#4235).

The only conflict was in post_process_component.dart: the fork's own
lookup through CameraComponent.currentCamera is replaced by upstream's
walk over CameraComponent.currentCameras, and the camera import that
the upstream version no longer needs is dropped.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants