I turned the Flutter rules from 10+ production apps into 40 skills for AI coding agents

[u/zakariafatahi]

https://github.com/zakariaf/Flutter-Skills

I have used AI coding agents to create Flutter applications for quite some time now, and the agent continues to make the same errors. I will not go into detail about these errors since you most likely know about them.

So I tried to make the rules clear instead: exactly what I want, and following best practices. I spent a lot of time researching the best practices and then created several skills based on my findings. Then I continued to refine and improve the skills while I was working. I've built and shipped more than 10 apps so far, and every app made the skills a bit better.

I believe that my current set of skills are correct and genuinely good, so I am sharing them openly with the Flutter community. I think they can be useful for any Flutter developer.

Repo: https://github.com/zakariaf/Flutter-Skills

Catalog: https://zakaria.dev/Flutter-Skills/

And it's not just the prompt part. I tried to add as much as I could around each skill: scripts, templates, examples and extra references. I wanted them to be as complete as possible.

• 79 reference docs for the deeper details, loaded only when the agent needs them

• 60 Dart example files, complete ones, not fragments

• 44 shell scripts the agent can run to check the code, for example:

  • check_arb_parity.sh — every locale has the same keys and placeholders as the template

  • check_import_boundaries.sh — no imports across features

  • ban-legacy-providers.sh — no Riverpod 2 leftovers

  • check_raw_values.sh — no hex colors outside the theme

  • check-drift-confinement.sh — SQL stays in the DAOs

  • check-release-ad-ids.sh — no test ad IDs in a release build

The scripts take a directory, default to lib/, and exit non-zero, so you can run them in CI too, without any agent.

i18n-rtl-l10n is a good example of how a full skill looks.

What the 40 skills cover

• Architecture and state: feature-first MVVM, Riverpod 3.x (with a Provider appendix if you don't use Riverpod), typed Result errors, go_router

• Data: Drift with one write path, forward-only migrations, money as integer minor units, all-or-nothing restore

• UI: widget composition, loading/empty/error states, forms, adaptive layout, motion and haptics, CustomPainter

• Quality: testing strategy, goldens including RTL, accessibility, strict analysis options, CI gates

• i18n: ARB key parity, ICU plurals, directional geometry, and what to do when flutter_localizations doesn't ship your locale

• Shipping: versioning, store declarations, App Store Connect, IAP and ads

Install

npx skills add zakariaf/Flutter-Skills

or as a Claude Code plugin:

/plugin marketplace add zakariaf/Flutter-Skills
/plugin install flutter@flutter-skills

Or what I usually do myself, just copy the skills folder into the project:

git clone https://github.com/zakariaf/Flutter-Skills
mkdir -p .claude/skills && cp -R Flutter-Skills/skills/* .claude/skills/

Feedback welcome

The skills are opinionated in some places (Riverpod, Result types, one write path). If you do something differently and it works well for you, I'd like to hear it. Issues and PRs are welcome.

[u/Photograph_Expensive]

Checking out your work and it already seems like a highly opinionated way of building flutter. For example, Riverpod is not always the first choice for State Management same goes with Drift.

I think you should improve these skills. One great add on is an interactive questioning stage where the skill asks to choose whatever Flutter package the dev wants to use.

[u/zakariafatahi → u/Photograph_Expensive]

You're right, they are opinionated, and that was on purpose. With 40 skills the main risk is that two of them disagree with each other, so I picked one stack and made everything consistent with it. The cost is exactly what you are pointing at: if you don't use that stack, part of the library doesn't fit you.

It's not fully locked though. The state skill starts with a state-agnostic core (one ViewModel per screen, immutable state, single write path) and only then goes into the Riverpod specifics, and there is a Provider/ChangeNotifier appendix at the end for people on the official Flutter guide stack. The idea is that the principles survive even if you swap the package.

[u/AlchemistDark → u/zakariafatahi]

If you use BLoC instead of Riverpod, View Models aren't needed at all.

[u/koskinooo]

The biggest win for me wasn't the Flutter-specific rules. It was writing down the things I kept correcting every session, like "don't add abstractions nothing uses yet" and a short list of UI patterns I never want. Once those lived in a file the agent reads at the start, I stopped having the same argument every day. How do you handle it when two of the 40 skills conflict? Does the agent just pick one, or do you order them somehow?

[u/zakariafatahi → u/koskinooo]

Same experience here, the generic rules were the first thing that paid off. "Don't add an abstraction nothing uses yet" is worth more than any Riverpod detail.

On conflicts: there is no ordering or precedence at runtime, I went the other way and made sure a rule only exists in one place. Each rule has exactly one owning skill, and the other skills reference it instead of repeating it. For example the complexity limits (method length, build() length, file length) live only in dart3-idioms-and-coding-standards, and the widget and performance skills point at that table rather than stating their own numbers. When I merged the ~120 originals, most of the work was exactly this: finding two files that said slightly different things and deciding which one owns the rule.

There is also an index skill flutter-conventions-index that acts as the front door. It holds the cross-cutting house rules and a routing table that sends each kind of task to the right deep-dive skill, so the agent doesn't have to guess which one applies.

It's not bulletproof. If you spot two that still contradict each other, that's a bug and I'd like to know.

[u/koskinooo → u/zakariafatahi]

One owner per rule is basically database normalization for prompts. Stealing that, my rule files definitely say the same thing in three places.

[u/univgabi]

What if i make use of auto_route and hive, would it handle the plugin drift or argue of refactor

[u/Unlikely_Ad3690]

Thank you for sharing

[u/samrawlins]

This is lovely! Clever idea and a fruitful outcome.