Flutter Skills
A collection of production-focused skills for AI coding assistants working on Flutter and Dart. Each skill is a folder of guidance: when to apply it, which decisions matter, and which failure modes to avoid.
These folders are not Flutter packages. Nothing in this repository belongs in an application's pubspec.yaml. Installation for Cursor, Claude Code, Codex, GitHub Copilot, Gemini CLI, OpenCode, and other agents is in INSTALL.md.
Contents
How a skill works
The repository contains 70 skill folders under skills/. Every folder has a SKILL.md manifest with YAML frontmatter. The description field is the trigger: a compatible assistant uses it to decide when the skill applies. The rest of the file is the operating guidance.
Supporting material stays inside that folder. Open it only when the manifest points to it.
| Path | Role |
|---|
SKILL.md | Required. Scope, trigger, and operating guidance. |
references/ | Longer, version-sensitive, or platform-specific guidance. Present in most skills. |
examples/ | Worked examples. A few skills include them. |
evals/evals.json | Sample prompts and expected behavior. Present in a few skills. |
agents/openai.yaml | Optional display name, short description, and default prompt for tools that read it. |
Copy the whole folder. A skill that links to references/ will not work if only SKILL.md is copied.
Some manifests also set compatibility. That field is a research baseline for that skill, not a Flutter version for this repository. Follow the skill's instruction to inspect the target project's SDK and package versions before using version-sensitive APIs.
Requirements
Using a skill requires an agent that loads a directory containing SKILL.md. The commands in INSTALL.md target the directories those agents document. Reading this repository needs only a browser. Applying a skill needs the Flutter or Dart project you are changing.
The multi-agent installer npx skills needs Node.js 22.20 or later. gh skill install needs GitHub CLI. Manual copy needs git or curl. Individual skills name the packages and platforms they cover.
Getting started
- Pick a skill from the catalog. The examples below use
flutter-go-router-engineering.
- Install that folder for your agent. From the Flutter app:
npx skills add ariaramin/flutter-skills --skill flutter-go-router-engineering
- Start a new agent session and ask for the work in ordinary language. The skill's
description decides when it applies.
For a personal install that follows you across projects, add -g. Paths, Windows commands, GitHub CLI, and copy-by-hand steps are in INSTALL.md.
Install a skill
| Need | Command |
|---|
| Choose agents interactively | npx skills add ariaramin/flutter-skills --skill flutter-go-router-engineering |
| Claude Code on this machine | npx skills add ariaramin/flutter-skills --skill flutter-go-router-engineering -g -a claude-code -y --copy |
| Cursor in this app, shared with Codex and Copilot | gh skill install ariaramin/flutter-skills flutter-go-router-engineering --agent cursor --scope project |
| A folder you place yourself | Copy a skill yourself |
Cursor, Codex, Copilot, Gemini CLI, and OpenCode can share ~/.agents/skills/<skill-name>/. Claude Code uses ~/.claude/skills/<skill-name>/ instead. Project copies live under the app, for example .agents/skills/ or .claude/skills/.
git clone https://github.com/ariaramin/flutter-skills.git
cd flutter-skills
mkdir -p ~/.agents/skills
cp -R skills/flutter-go-router-engineering ~/.agents/skills/
The landing page can download a folder with curl, wget, npx degit, or a sparse clone. Those commands do not choose an agent directory. INSTALL.md has the full placement table, the other agent flags, and what to check when a skill does not show up.
Use a skill
Installed skills are instructions for the assistant, not libraries for the app. Do not add them as dependencies.
Example: with skills/flutter-go-router-engineering installed, ask:
Add an auth redirect so signed-out users cannot open /account, and keep the existing shell routes.
The skill tells the assistant to inspect the current router, treat public URLs as a compatibility contract, and keep redirects deterministic. Its compatibility note targets a researched go_router baseline and still requires checking the versions in the app.
Two other shapes show up often:
Related skills
Several skills sit next to each other. Use the narrower one when it matches.
| Task | Skill |
|---|
| Framework motion: springs, gesture velocity, interruption, reduced motion | Flutter motion engineering |
The Material animations package: OpenContainer, shared-axis, fade-through, and related transitions | Flutter animations |
| Choosing, auditing, or rejecting a dependency | Flutter package selection |
| Designing, testing, versioning, or publishing a package or plugin | Flutter/Dart package engineering |
| General application changes across architecture, performance, and testing | Flutter production engineering |
Flutter motion engineering records a local validation baseline of Flutter 3.47.0 stable, Dart 3.13.0, and DevTools 2.60.0. That baseline is not a claim about the newest SDK patch. The skill has three reference guides. references/examples/ contains four Dart library files and six tests in test/motion_test.dart. Profile motion on the target device before treating it as fast.
Document capture is also split on purpose:
Skill catalog
Each link opens that skill's SKILL.md.
Foundations and architecture
- Dart args — production command-line interfaces, subcommands, flags, and executable tooling.
- Dart & Flutter Equatable — value equality, immutable state, and reliable rebuild behavior.
- Freezed — immutable models, sealed unions, JSON serialization, and code generation.
- Dart & Flutter FFI — native integration, memory ownership, ABI safety, and platform packaging.
- Dart meta — annotations, API contracts, immutability, and analyzer-guided modernization.
- Senior Flutter architecture — production Flutter/Dart architecture with explicit trade-offs.
- Design patterns — 22 classic object-oriented patterns, with source-backed decisions, examples, and trade-offs.
- Senior mobile architecture — architecture reviews and refactoring across iOS, Android, and cross-platform apps.
- Flutter production engineering — architecture, performance, scalability, cross-platform behavior, testing, profiling, and maintainability.
- Flutter multi-environment — development, staging, and production flavors, configuration, and delivery pipelines.
UI and user experience
- Figma to Flutter — Flutter implementation of Figma frames, Auto Layout, tokens, and responsive multi-platform UI.
- HTML to Flutter — production Flutter ports of HTML/CSS/JavaScript interfaces.
- React to Flutter — behavior-preserving React web migrations to Flutter.
- Flutter animations — Material motion, transitions, accessibility, and animation performance.
- Flutter motion engineering — interaction continuity, interruptible springs, platform transitions, rendering diagnostics, accessibility, and tested Dart examples.
- Rive Flutter — C++ runtime integration, state machines, inputs, layout, lifecycle, and multi-platform rendering with
rive.
- Lottie for Flutter — pure Dart vector animations, composition caching, frame-rate throttling, dynamic delegates, marker playback, and list performance with
lottie.
- Flutter Confetti — lifecycle-safe, accessible celebration effects and particle performance.
- Flutter native splash — Android, iOS, and web launch resources, transitions, flavors, and startup behavior.
- Flutter image performance — image loading, decoding, caching, rendering, and memory use.
Performance and reliability
- Flutter expert tips — practical implementation, debugging, refactoring, and modernization.
- Flutter concurrency, memory & performance — isolates, async workflows, lifecycle management, and resource efficiency.
- Flutter caching — cache policy, invalidation, offline data, HTTP freshness, and resource bounds.
- Mobile API caching — cache strategy, HTTP semantics, offline synchronization, and account isolation for iOS, Android, Flutter, React Native, and Kotlin Multiplatform.
- Mobile app shrinking & release optimization — R8 keep rules, resource and dependency reduction, native symbols, app thinning, tree shaking, and release validation across Android, iOS, Flutter, React Native, and Kotlin Multiplatform.
- Flutter jank optimization — profiling and fixing dropped frames, slow scrolling, and latency.
- Flutter UI performance — frame-budget analysis, rebuild, layout, paint, and raster optimization, and production profiling.
- Flutter memory leaks — lifecycle defects, leak tracking, and regression prevention.
- Flutter Squadron concurrency — workers, worker pools, cancellation, and web workers.
Observability
- Flutter Firebase Analytics — product-event schemas, consent, identity, screen and ecommerce measurement, DebugView, and reporting quality.
- Flutter Sentry — crash reporting, tracing, symbolication, privacy, and production observability.
- Flutter production logging — structured, privacy-conscious diagnostics and error reporting.
Networking, navigation, and platform capabilities
- Flutter Firebase Messaging — FCM delivery across Android, iOS, macOS, and web.
- Flutter Dio — production HTTP clients, auth, retries, transfers, and observability.
- Flutter Dio cache interceptor — HTTP caching, revalidation, store selection, offline fallback, key isolation, and invalidation with
dio_cache_interceptor.
- Flutter go_router — routing, deep links, redirects, nested navigation, and web URLs.
- Flutter app links — Universal Links, Android App Links, and secure link delivery.
- Flutter url_launcher — external URI handling across platforms.
- Flutter share_plus — cross-platform text, URI, file, and generated-content sharing.
- Flutter WebView — embedded web content, navigation policy, security, and lifecycle.
- Flutter local notifications — permissions, scheduling, time zones, interactions, and recovery.
- Flutter permission_handler — runtime permissions, platform configuration, and privacy-aware flows.
Storage and dependency injection
- Flutter Supabase — Auth, row-level security, database access, Realtime, Storage, Edge Functions, and production security.
- Flutter Drift — relational persistence, reactive queries, migrations, concurrency, and cross-platform SQLite.
- Flutter Hive — local persistence, schema changes, encryption, and recovery.
- hydrated_bloc — Bloc and Cubit state persistence, keys, schema evolution, security, and testing.
- Flutter path_provider — durable filesystem storage and cleanup.
- Flutter get_it & injectable — dependency lifetimes, scopes, startup, and testing.
Security
Testing and delivery
- Test before deploy — release-ready test selection using the "34 Test Before Deploy" taxonomy.
Build, signing, and store release live in Flutter production build & release under Foundations.
Repository layout
skills/<name>/SKILL.md Skill manifest
skills/<name>/references/ Optional supporting guidance
index.html, styles.css, script.js
Static landing page
.nojekyll GitHub Pages: serve files as-is
assets/social-preview.jpg Social preview image
.github/workflows/validate.yml Manifest check
.github/ISSUE_TEMPLATE/ Issue forms, including skill requests
INSTALL.md Agent installation guide
CONTRIBUTING.md Contribution rules
PUBLISHING.md GitHub publication and release checklist
There is no root pubspec.yaml and no GitHub Actions workflow other than skill validation.
Landing page
index.html, styles.css, and script.js are a dependency-free catalog page. It has no build step.
The cards and download paths come from skills and categories in script.js. That list matches the skill catalog: every folder, grouped the same way. slug is the folder name under skills/. Hero and collection counts are filled from this list.
Run locally
Open index.html directly, or serve the repository root:
python3 -m http.server 8000
Then open http://localhost:8000.
Change the page
- Edit the visible copy in
index.html. The page credits Aria Ramin and links to this GitHub repository.
- Edit
skills and categories together when adding or renaming a card. slug must be the real folder name.
- Edit the custom properties at the top of
styles.css to retheme the page.
- Change
repository in script.js if the GitHub repository moves. The install commands use that value.
Selecting cards generates curl, wget, npx degit, and Git sparse-checkout commands. npx degit downloads the complete skills/ folder. The other commands download the selected folders.
GitHub Pages
The site is published from the main branch root at https://ariaramin.github.io/flutter-skills/. .nojekyll keeps GitHub Pages from running Jekyll over the skill folders. A push to main updates the site.
Validation
.github/workflows/validate.yml runs on pull requests and on pushes to main. The job fails when:
- any
skills/*.skill archive is present
skills/ contains no SKILL.md files- any directory directly under
skills/ is missing SKILL.md
Run the same check locally:
bash -c '
shopt -s nullglob
archives=(skills/*.skill)
(( ${#archives[@]} == 0 )) || { echo "Skills are folders with SKILL.md. Remove .skill archives."; exit 1; }
manifests=(skills/*/SKILL.md)
(( ${#manifests[@]} )) || { echo "No SKILL.md manifests found."; exit 1; }
for dir in skills/*/; do
[[ -f "${dir}SKILL.md" ]] || { echo "$dir is missing SKILL.md"; exit 1; }
done
echo "Validated ${#manifests[@]} skills."
'
A directory under skills/ that has no SKILL.md fails this check. Keep research notes inside an existing skill folder, or give a new skill its own manifest.
Contributing
Contributions are licensed under the MIT License, as stated in CONTRIBUTING.md. Keep each change focused on one skill or one documentation concern. Do not include secrets, private URLs, customer data, or unpublished source material. Verify version-sensitive package and API guidance against current primary documentation.
Pull requests use the repository's pull request template. The Validate skills check must pass before merge. Release steps are in PUBLISHING.md. New skill ideas can use the skill-request issue form.
License
Distributed under the MIT License. See CODE_OF_CONDUCT.md and SECURITY.md for participation and vulnerability reporting. Skills are instructional text; SECURITY.md also covers guidance that could expose credentials, weaken application security, or create unsafe release practices.
Flutter and the related logo are trademarks of Google LLC. This is an independent community project and is not endorsed by Google.
