Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rules
Open on GitHub

What 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 BuildContext leaking into business logic during review
  • Swap a catch-all Container for Padding or SizedBox
  • 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.dart for 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-rules

This 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-code

3Manually: put the files in place

~/.claude/skills/flutter-best-practices/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flutter-best-practices/

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

Similar skills

All skills for Mobile →

From the same set39

The whole set →
firebase-analytics firebase-analytics is a Claude Code skill for configuring Firebase Analytics in Flutter apps. It activates for event logging, user properties, funnels, and screen-view tracking. CX Codex +1 ★ 674repo stars patrol-e2e-testing patrol-e2e-testing is a skill for building and running Patrol 4.x end-to-end tests for Flutter apps, covering user flows, OS permission dialogs and cross-platform checks. CX Codex +1 ★ 674repo stars revenuecat-testing revenuecat-testing builds a structured QA plan for RevenueCat in-app subscriptions, verifies sandbox events, and debugs purchase restore flows. CX Codex +1 ★ 674repo stars firebase-app-check This skill guides Firebase App Check setup in Flutter, including provider choice, debug tokens, token refresh, and enforcement rollout. CX Codex +1 ★ 674repo stars flutter-app-architecture flutter-app-architecture enforces layered Flutter architecture with MVVM, repositories, services, and unidirectional data flow. CX Codex +1 ★ 674repo stars riverpod This skill guides Riverpod work in Flutter and Dart, from provider setup to lifecycle handling and tests. Use it when an agent needs project-specific state-management guidance. CX Codex +1 ★ 674repo stars architecture-feature-first architecture-feature-first sets up a layered, feature-first structure for Flutter apps, splitting UI, data and an optional domain layer. CX Codex +1 ★ 674repo stars inclusive-design inclusive-design guides agent workflows on low-end hardware, metered 2G connections, global name formats, and novice stress. Distinct from WCAG audits. CX Codex +1 ★ 674repo stars

Project sponsors

Companies that keep this analytics open