Skip to content

uwuclxdy/agenticat / skills/clean-flutter

clean-flutter

Verified

Idiomatic Flutter and Dart rules: feature-first layout, Riverpod, freezed, go_router, const correctness.

Clean Flutter

Flutter and Dart conventions for writing, reviewing, and refactoring. The core rules below always apply. Load the one reference file matching the task's domain; don't load them all.

If the clean-code skill is installed, its language-agnostic principles (function size, naming hygiene, comment discipline) still apply. Where generic advice conflicts with Flutter idiom, this skill wins: "replace switch with polymorphism" maps to exhaustive switch over a sealed class, which in Dart is the intended tool, not a smell.

Task touchesFile
Project layout, MVVM layering, repository boundaries, Resultreferences/architecture.md
Providers, Notifier/AsyncNotifier, ref.watch/read/listen, DI, autoDisposereferences/state-management.md
Routes, deep links, nested or guarded navigationreferences/navigation.md
Data models, freezed, JSON serialization, build_runner workflowreferences/models-serialization.md
Writing tests: unit, widget, golden, integrationreferences/testing.md
Rebuild storms, async-gap crashes, layout overflow, dynamic leaksreferences/pitfalls.md
Picking a package (storage, network, forms, i18n, background), pubspec hygienereferences/packages.md

Toolchain & Setup

  • Pin the Flutter SDK with fvm (.fvmrc, fvm use) and commit the pin so every machine and CI build the same stable SDK.
  • very_good_analysis in analysis_options.yaml as the lint floor. It layers strict-casts, strict-raw-types, and strict-inference on top of flutter_lints, catching the exact classes of mistake generated code produces (implicit dynamic, unchecked casts). Fix warnings; never loosen a rule to silence one. flutter analyze stays clean in CI.
  • Codegen (freezed, json_serializable, riverpod_generator, retrofit) runs through dart run build_runner build --delete-conflicting-outputs. Generated *.g.dart and *.freezed.dart are build output: regenerate after editing the annotated source, never hand-edit them. Detail in references/models-serialization.md.

Widgets & Build

  • build() is pure: no side effects, no I/O, no allocation you can hoist out. It runs often; assume every rebuild is free to happen at any time.
  • const wherever the analyzer allows (prefer_const_constructors). A const widget is skipped on rebuild, the cheapest perf win and the one generated code drops most.
  • Extract widget subtrees into their own StatelessWidget/ConsumerWidget classes, not Widget _buildFoo() methods. A helper method rebuilds with its parent and can't be const; a widget class gets its own rebuild boundary and const-ness.
  • Compose small widgets. A deep build method that could be five classes is the Flutter equivalent of a 200-line function.
  • Keys only where identity matters (reordered or inserted list items, state preserved across a position change). Don't scatter keys nothing reads.

State

  • Riverpod with codegen (@riverpod) is the default for both state and DI. ref.watch in build to react to changes; ref.read in callbacks and event handlers for a one-shot read. Watching in a callback re-subscribes on every call; reading in build misses updates. Detail in references/state-management.md.
  • Push state to the smallest widget that needs it. Scope ref.watch with .select(...) so a one-field change doesn't rebuild the whole screen.
  • setState is fine for genuinely local ephemeral state (a toggle, focus, an animation flag). Not for app state or anything shared across widgets.
  • Package-specific deprecation/trend verdicts (GetX, Isar, old Hive, golden_toolkit) live in references/pitfalls.md's Named traps list, even when the package's own topic has a dedicated reference file (e.g. state-management.md).

Async & Lifecycle

  • After any await inside a State or callback, a BuildContext may be dead. Guard with if (!context.mounted) return; (or if (!mounted) return; in a State) before touching context, Navigator, setState, or a controller. use_build_context_synchronously flags the common cases, not all of them.
  • Dispose what you create. TextEditingController, ScrollController, AnimationController, FocusNode, and StreamSubscription all leak and can fire after teardown without a matching dispose()/cancel().

Errors

  • Repositories catch throwing calls (network, disk, platform channels) internally and return a sealed Result<T> (Ok/Failure); callers switch on it exhaustively. The failure path becomes part of the signature instead of an invisible throw. Detail in references/architecture.md.
  • Let genuine bugs (programmer error, broken preconditions) throw and reach crash reporting. Don't wrap them in a try/catch that swallows them into a silent no-op.

Naming & Style

  • lowerCamelCase for members and locals, UpperCamelCase for types, lowercase_with_underscores for files and directories. Match dart format; never hand-format around it.
  • Private by default (_name); widen visibility only when another library needs it.
  • async/await over raw .then() chains. Type every public signature and let strict-inference reject accidental dynamic.

Pre-Submit Checklist

  • flutter analyze clean under very_good_analysis; no rule loosened to pass
  • codegen regenerated after any model/provider edit; no hand-edited *.g.dart/*.freezed.dart
  • const on every eligible widget; subtrees extracted to classes, not _build methods
  • no BuildContext/Navigator/setState after an await without a mounted guard
  • every controller, subscription, and notifier disposed
  • ref.watch in build, ref.read in callbacks, ref.listen for side effects; watch scoped with .select
  • repository calls return Result; genuine bugs throw rather than being swallowed
  • no unmaintained package added (pub.dev signals checked, see references/packages.md)
  • tests fail if the logic breaks; layer chosen per the pyramid (references/testing.md)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall