flutter-best-practices — Claude Code skill: what it does, install
flutter-best-practices is a Claude Code skill with rules for Flutter and Dart: layers, feature folders, widget choices, and tests. The agent reads the reference file matching the task.
MIT ★ 674 updated 2026-10-29
/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rulesWhat flutter-best-practices does
The skill sets ground rules for a Flutter codebase. Two layers, UI and data, with dependencies running one way: View → ViewModel → Repository → Service. Widgets carry no business logic. A feature owns one folder instead of being scattered across shared blocs/ and widgets/ buckets. State is modelled as an immutable union type so every case gets handled.
Five reference files sit behind it: architecture-layers.md, feature-structure.md, dart-coding-practices.md, enterprise-scale.md, localization-package-boundaries.md. The agent opens the one matching your task, and reads two when they overlap. Checklists cover adding a screen, reviewing Flutter code and starting a project. A one-line fix can lean on the ten core rules in SKILL.md alone.
The assumed package set is bloc with freezed, provider, melos, leancode_lint, patrol. Treat it as a starting point: when the repo already runs something else, the skill says to use the local equivalent. On existing code it follows surrounding conventions and flags conflicts with the standard instead of rewriting in silence. Expect review comments, not a bulk refactor.
What it helps with
- Place a feature's state, widgets and models in a single folder
- Decide whether logic belongs in a view model, a repository or a service
- Catch
BuildContextleaking into business logic during review - Swap a catch-all
ContainerforPaddingorSizedBox - Plan a Melos monorepo before several teams start adding packages
Example prompts for the agent
- Add a checkout screen: define the state first, then the cubit, then the widgets
- Review
lib/features/cart/cart_cubit.dartfor layer mistakes and unhandled states - Sketch the folder layout for a new Flutter app built by two teams
How to install flutter-best-practices
1Plugin marketplace
/plugin marketplace add evanca/flutter-ai-rules/plugin install flutter-ai-skills@flutter-ai-rulesThis installs the whole flutter-ai-skills plugin with all its skills
2Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-best-practices -a claude-code3Manually: put the files in place
~/.claude/skills/flutter-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/flutter-best-practices/
1Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-best-practices -a codex2Manually: put the files in place
.agents/skills/flutter-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-best-practices -a cursor2Manually: put the files in place
.cursor/skills/flutter-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install evanca/flutter-ai-rules skills/flutter-best-practices2Manually: put the files in place
.github/skills/flutter-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill flutter-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/evanca/flutter-ai-rules --path skills/flutter-best-practicesManually: put the files in place
.devin/skills/flutter-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about flutter-best-practices
How do I install flutter-best-practices in Claude Code?
Add the marketplace with /plugin marketplace add evanca/flutter-ai-rules, then install the plugin: /plugin install flutter-ai-skills@flutter-ai-rules.
What does flutter-best-practices do?
It hands the agent Flutter and Dart standards: layer separation, feature structure, widget choice, modern Dart syntax, tests. For each task it opens the matching reference file.
Does it work if my app uses a different state management package?
Yes. The listed packages are a default assumption, not a requirement, and the skill tells the agent to use project-local equivalents when the codebase already relies on something else.
Source text
SKILL.md · MIT
---
name: flutter-best-practices
description: "Use when writing, reviewing, refactoring, or planning Flutter/Dart code — screens, features, project structure, state management, folders, widgets, cubits/blocs, repositories, services, or tests."
license: MIT
---
# Flutter Best Practices
Standards for building maintainable Flutter apps, distilled from the official
Flutter architecture guide and LeanCode's experience shipping 40+ Flutter
projects (including a 30-developer banking app). Apply these when writing new
code; when touching existing code, prefer consistency with the surrounding
codebase and raise conflicts with these standards rather than silently
rewriting.
## How to use this skill
Read the reference file that matches the task. Read more than one when tasks
overlap (e.g. a new feature touches both structure and coding style).
| Task | Read |
|---|---|
| Design layers, decide where logic lives, MVVM, repositories/services | [references/architecture-layers.md](references/architecture-layers.md) |
| Create/organize a feature, folder structure, state management wiring | [references/feature-structure.md](references/feature-structure.md) |
| Write or review Dart/Flutter code, widgets, tests, lints | [references/dart-coding-practices.md](references/dart-coding-practices.md) |
| Multi-team/multi-package apps, monorepo, navigation, localization, API contracts, E2E tests | [references/enterprise-scale.md](references/enterprise-scale.md) |
| App localization setup, reusable UI package string ownership, language picker visibility | [references/localization-package-boundaries.md](references/localization-package-boundaries.md) |
For a quick task (small widget fix, one-line review comment), the core rules
below may be enough on their own.
## Core rules (always apply)
### Architecture
1. **Separate UI from data.** Two broad layers: UI (views + view models /
cubits) and Data (repositories + services). Dependencies point one way:
`View → ViewModel → Repository → Service`. Lower layers never import upper
layers. Repositories never depend on each other.
2. **Views hold no business logic.** Widgets may contain show/hide
conditionals, animation, layout, and simple routing logic — nothing that
transforms or decides about data. All data logic lives in the view model
(or cubit/bloc), which has no access to `BuildContext`.
3. **Organize by feature, not by layer.** Everything a feature needs — state
management, widgets, models — lives under one feature directory. Don't
create top-level `blocs/`, `widgets/`, `models/` buckets that scatter a
feature across the tree.
4. **State is immutable and explicit.** Model UI state as a sealed/union type
(initial / inProgress / failure / ready) so every case is handled
exhaustively. One-off effects (snackbars, navigation) are events, not
state.
5. **Add layers only when they pay for themselves.** Start with
view-model → API client. Introduce a repository when you need caching,
offline, or merging sources. Introduce a use case only when logic merges
multiple repositories, is genuinely complex, or is reused by several view
models.
### Coding
6. **Prefer intent-revealing widgets over `Container`.** Use `Padding`,
`SizedBox`, `ColoredBox`, `DecoratedBox`, `Center` — they are const-able
and self-describing. `Container` is fine only when combining several
properties at once.
7. **Use modern Dart.** Pattern matching (`if (x case final v?)`), switch
expressions with exhaustiveness, records and destructuring, collection
`if`/`for`/spreads instead of `.add()` loops, expression bodies for
pass-through async functions (no redundant `async`/`await`).
8. **Prefix sliver-returning widgets with `Sliver`** so misuse in the wrong
scroll context is caught at a glance.
9. **Tests tell a story.** Use expressive matchers (`isEmpty`, `throwsA`,
`isA`, `completion`) and minimize dependencies — plain `Text`/`SizedBox`
over design-system widgets in test fixtures. Test cubits/view models in
isolation from the widget tree.
10. **Every `// ignore:` gets a reason** on the same or preceding line. Log
errors with dedicated `error`/`stackTrace` parameters, never string
interpolation.
## Workflow checklists
### Adding a new feature/screen
1. Read [references/feature-structure.md](references/feature-structure.md)
and mirror the existing project's conventions for the feature directory.
2. Define the state as a union type first; then the cubit/view model; then
the widgets. Constructor-inject dependencies; scope them to the feature's
widget subtree.
3. Data comes in through a repository or typed API client — never fetched
inside a widget.
4. Add unit tests for the cubit/view model logic before wiring UI details.
### Reviewing Flutter code
Check, in order of importance:
1. Logic in the right layer (rule 1–2)? Any `BuildContext` in business logic?
2. State modeled as immutable union types, all cases handled?
3. Feature self-contained, or does it reach into another feature's internals?
4. Widget choices (rule 6), modern Dart (rule 7), sliver naming (rule 8)?
5. Tests present for logic, readable, minimal dependencies?
6. Unexplained `// ignore:`, string-interpolated error logs, deprecated
patterns still spreading?
### Starting a new project
1. Read [references/architecture-layers.md](references/architecture-layers.md)
for the layer blueprint and
[references/feature-structure.md](references/feature-structure.md) for the
folder skeleton.
2. If more than ~2 teams or clearly separable domains are involved, read
[references/enterprise-scale.md](references/enterprise-scale.md) and
consider a Melos monorepo with one package per domain from day one.
3. Set up strict lints early (`leancode_lint` or equivalent + custom rules) —
retrofitting is far more expensive.
## Package palette
Defaults that these standards assume (swap for project-local equivalents when
the codebase already uses something else):
- **State:** `bloc` (Cubit) + `freezed` for union-type states;
`bloc_presentation` for one-off UI events
- **DI:** `provider` scoped to widget subtrees (accepting its lack of
compile-time safety as the lesser evil)
- **Boilerplate reduction:** `flutter_hooks`
- **Monorepo:** `melos`
- **Localization:** `flutter_localizations` + `intl` with `.arb` files
- **Lints:** `leancode_lint`
- **E2E/UI tests:** `patrol`
The official Flutter guide is state-management-agnostic (MVVM with
ChangeNotifier works too); what matters is the layer separation, not the
package. See the reference files for rationale and trade-offs.
© Ivanna Kaceviča · MIT · evanca/flutter-ai-rules