flutter_skill_lints #

Analyzer plugin that turns the building-flutter-apps skill's architecture and code-quality rules into Dart analyzer diagnostics, plus a curated many_lints-inspired surface, so feedback shows up in your IDE, dart analyze, and full-project Flutter analyzer runs.

Designed for Riverpod + codegen Flutter apps.

Highly opinionated by design: This plugin enforces the accompanying building-flutter-apps skill's preferred architecture and code style. Treat it as a project policy package, not a neutral Dart/Flutter lint preset. Until v1.0.0, assume every release may include breaking changes as the lint surface is refined.

Highlights #

Quick Start #

1. Add the plugin to the top-level plugins section of analysis_options.yaml (it is not a pubspec.yaml dependency):

   include: package:flutter_lints/flutter.yaml
   
   plugins:
     riverpod_lint: ^3.1.9
     flutter_skill_lints: ^0.10.0
   
   analyzer:
     exclude:
       - ".dart_tool/**"
       - "**/*.g.dart"
       - "**/*.freezed.dart"
       - "**/*.gr.dart"
       - "**/*.arb"
     language:
       strict-casts: true
       strict-inference: true
       strict-raw-types: true
     errors:
       missing_required_param: error
       missing_return: error
   
   formatter:
     page_width: 100
   
   linter:
     rules:
       - always_use_package_imports
       - require_trailing_commas
       - prefer_single_quotes
       - directives_ordering
       - avoid_multiple_declarations_per_line
       - prefer_const_constructors
       - prefer_const_declarations
       - prefer_const_literals_to_create_immutables
       - prefer_final_locals
       # Effective Dart Design additions not covered by flutter_lints.
       - always_declare_return_types
       - type_annotate_public_apis
       - avoid_positional_boolean_parameters
       - avoid_equals_and_hash_code_on_mutable_classes
       - avoid_returning_this
       - avoid_setters_without_getters
       - prefer_mixin
       - use_to_and_as_if_applicable
       - avoid_dynamic_calls
       - avoid_print
       - avoid_void_async
       - cancel_subscriptions
       - close_sinks
       - discarded_futures
       - unawaited_futures
   

2. Restart the Dart Analysis Server (most editors expose "Dart: Restart Analysis Server"; otherwise restart the IDE).

3. Run analysis:

   dart analyze       # CLI/CI gate; do not path-scope analysis
   dart test
   

   Full-project flutter analyze can be useful locally, but the building-flutter-apps skill uses dart analyze for CLI/CI because path-scoped Flutter analysis can drop plugin diagnostics. flutter_skill_lints can read project files and report configuration drift through Dart-analysis diagnostics, but it does not replace flutter pub get or pub.flutter-io.cn publish validation.

Optional: install the companion skill #

If you use Claude Code or another agent runtime that consumes skills.sh skills, install the matching agent guidance:

npx skills add https://github.com/sgaabdu4/building-flutter-apps \
  --skill building-flutter-apps

Rules #

Exact inventory lives in doc/building-flutter-apps-lint-inventory.md. Do not duplicate diagnostic-ID tables here.

Examples #

Each snippet shows the minimum context for the diagnostic to fire.

// lib/features/counter/presentation/counter_notifier.dart
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'counter_notifier.g.dart';

@riverpod
class CounterNotifier extends _$CounterNotifier {
  @override
  int build() => 0;

  Future<void> incrementLater() async {
    await Future<void>.delayed(Duration.zero);
    state = state + 1; // use_ref_mounted_after_await
  }
}

Also flagged: raw string or named route calls (router_string_nav), direct GoRouter.of(context) usage (router_gorouter_of), injected router/context route calls that bypass generated helpers (router_direct_route_call), raw router or route definitions outside the router boundary or shared test router helper (router_raw_route_definition), and direct page-route Navigator APIs (router_untyped_navigator_push). Fix by calling generated typed route helpers:

ProductDetailRoute(id: id).go(context);
await ProductCreateRoute(parentId: id).push<void>(context);

import 'dart:async';
import 'package:flutter/widgets.dart';

Future<void> saveLater<T>() async {}

void buildButton(VoidCallback onPressed) {}

void build() {
  buildButton(() {
    saveLater<void>(); // use_unawaited_for_fire_and_forget_futures
  });

  buildButton(() {
    unawaited(saveLater<void>());
  });
}

Future<void> precacheCachedNetworkImages(
  Iterable<ImageProvider<Object>> images,
  BuildContext context,
) async {
  await Future.wait([
    for (final image in images) precacheImage(image, context),
  ]);
}

void setupImages(
  Iterable<ImageProvider<Object>> images,
  BuildContext context,
) {
  unawaited(precacheCachedNetworkImages(images, context));
}

// lib/features/users/domain/user.dart
class User {
  const User({required this.userId, required this.orgId});

  final String userId; // typed_id_raw_id
  final String orgId;
}

Configuration #

Keep the enabled diagnostics active. Do not hide a finding with ignore, ignore_for_file, an analyzer severity downgrade, a baseline, or a skipped test. Fix the source, correct the package family, or update the canonical rule when the contract is wrong. Generated files may be excluded only when generation and compilation prove those files are valid.

Troubleshooting #

Diagnostics don't appear. Restart the Dart Analysis Server after editing analysis_options.yaml. The plugin loads only at server start.

Plugin fails to load. Check that your project resolves the analyzer versions listed under Compatibility. Analyzer plugin APIs are not stable across major versions.

Conflict with riverpod_lint. Both plugins are designed to coexist when their top-level plugin constraints resolve with the analyzer 14.3 family.

Compatibility #

Targets the analyzer-14.3 shared plugin family and requires Dart 3.11 or later. Verified against:

• analysis_server_plugin 0.3.22
• analyzer 14.3.0
• analyzer_plugin 0.14.16
• analyzer_testing 0.4.1
• riverpod_lint 3.1.9 in a Dart 3.13 consumer

The real analysis-server smoke test resolves both plugins together, so the shared analyzer-14.3 family is the package contract.

Recheck before publishing a new release.

Development #

dart format .
dart analyze
dart test

Set up the repository hooks once:

sh scripts/setup-git-hooks.sh

Integration smoke test (creates a temporary Flutter app, gated):

RUN_FLUTTER_PLUGIN_SMOKE=1 dart test test/integration_plugin_smoke_test.dart \
  --reporter expanded

Release #

A version bump merged to main triggers the release workflow, which tags vX.Y.Z. The tag workflow publishes to pub.flutter-io.cn and creates the GitHub Release.

Attribution #

Inspired by many_lints. Portions of the internal analyzer rule implementation are distributed under the MIT license. See THIRD_PARTY_NOTICES.md.