evanca/flutter-ai-rules

Flutter AI Skills and Rules for Claude, Codex, Cursor, and Other AI-Powered IDEs

evanca/flutter-ai-rules is a collection of 36 small guidance files ("skills") that AI coding tools — Claude Code, Codex, Cursor, Antigravity, and others — load on their own when they detect a matching task. The content is drawn only from official documentation: Flutter, Dart, Firebase, and the packages' own docs. No personal opinions or invented conventions.

What a "skill" is

A skill is a folder containing a SKILL.md file. The AI agent reads a short description, decides the task matches, then pulls in the full guidance automatically. For example: touch auth code and Firebase Auth guidance loads; touch a Riverpod provider and Riverpod guidance loads. You never paste rules into a config or type an @-mention.

Quick start

npx skills add evanca/flutter-ai-rules

That installs everything. It requires Node 22.20+ (older versions fail immediately). Alternatives that work on any Node version (or none):

Browse or install one skill only: npx skills add evanca/flutter-ai-rules --list / --skill flutter-best-practices
Install as a plugin for Claude Code, Codex, Cursor, or Antigravity — keeps the set updated in place (full commands in the README)
Manual copy: copy or symlink a skill folder into .claude/skills/, .cursor/skills/, .codex/skills/, .agents/skills/, or .windsurf/skills/ — or vendor the whole set into your project with a git clone one-liner
Reference a skill explicitly when you want it: "Read @.skills/bloc/SKILL.md and create test coverage."

Windsurf/Devin have no plugin manifest (manual copy is the path). GitHub Copilot doesn't read SKILL.md at all — use the legacy rule files instead (below).

What's inside

The 36 skills are grouped:

Category	Examples	What triggers them
Flutter/Dart foundations (8)	best practices, effective Dart, Dart 3 updates, app architecture, error handling, layout with Row/Column, pre-caching	writing/reviewing Flutter code, scaffolding projects, layout errors
State management (4)	Bloc, Riverpod, Provider, ChangeNotifier	setting up providers, wiring state, optimizing rebuilds
Testing & review (5)	testing, Mockito, Mocktail, Patrol E2E, code review	unit/widget/golden tests, mocking, PR review
Firebase (15)	Auth, Firestore, Storage, Analytics, Crashlytics, Messaging, Remote Config, Cloud Functions, App Check, Data Connect, AI features	any Firebase task — auth state, schemas, uploads, events, feature flags, etc.
Shipping & product (4)	accessibility, inclusive design, RevenueCat testing, Dart Genkit agents	a11y, i18n, purchase testing, AI agents in Dart

Legacy options: rules & combined bundles

Before skills existed, the repo shipped two older formats. Both still work and are maintained, but skills are recommended because they load only when relevant instead of consuming context on every request. Use the legacy paths only if your tool lacks skill support or you want one static file:

rules/ — six broad foundation files (effective Dart, app architecture, errors, Dart 3 updates, testing, code review). Reference by name in prompts. Package-specific guidance (Bloc, Riverpod, Firebase, Mockito…) is skills-only now.
combined/ — seven topic bundles, each in a full and an under-6,000-character variant (to fit Windsurf's hard limit). Paste one into your rules config.
GitHub Copilot — copy a combined bundle to .github/copilot-instructions.md, or copy rule files to .github/instructions/ with Dart-only frontmatter, or paste a bundle into a root AGENTS.md (works for Copilot, Codex, and Antigravity at once).

Size guidance by tool

The README includes a table of each tool's own documented size recommendations (accessed 2026-07-11). Highlights:

Claude Code — CLAUDE.md under 200 lines (soft); SKILL.md under 500 lines (soft); description 1,536 chars (hard)
Cursor — rules under 500 lines (soft); no numeric SKILL.md limit
OpenAI Codex — no rule limit; skill bundles limited to 50 MB zip / 25 MB per file / 500 files
Antigravity — 12,000 chars per rule file (hard); no SKILL.md limit stated
Windsurf — 6,000 chars global rules; 12,000 chars per file (both hard); no SKILL.md limit
GitHub Copilot — instructions under ~2 pages (soft); no repo-level SKILL.md support

This repo keeps its combined bundles under 6,000 characters to satisfy the strictest limit (Windsurf's). "Hard" means enforced/truncated; "soft" is a quality recommendation.

Design philosophy: no opinions

Everything traces to official documentation — links provided for each source.
Skills may contradict each other because their sources do (e.g., two packages recommending different folder layouts). Both get shown.
Content is re-fetched from upstream on a schedule, so skills track official guidance as it changes.
You're free to alter anything to your taste — the repo itself stays objective.

Contributing & license

Fork, add/modify a skill (in skills/) or rule (in rules/), open a PR.
One hard requirement: include an official documentation link for anything added or changed. If the source isn't in ATTRIBUTION.md, add it there with its license; if the license isn't permissive, restate the guidance instead of quoting.
License: MIT for the repo's own content (topic choices, trigger descriptions, wording/structure). The underlying documentation keeps its own terms — mostly CC BY 4.0 for Flutter/Dart/Firebase, code samples under BSD-3 or Apache 2.0, package READMEs under MIT/Apache 2.0, and a few sources (Apple, Google Play, RevenueCat) that aren't openly licensed and are therefore restated as fact, not copied. Redistributing requires keeping source links per CC BY attribution. Full mapping in ATTRIBUTION.md.

Bottom line

One install gives your AI coding agent contextual, documentation-sourced Flutter/Dart/Firebase guidance that appears exactly when needed — no manual config, no context bloat, no invented conventions. Plugins keep it updated; manual copies work everywhere else; legacy rule files serve tools without skill support.