DEV Community

Cover image for Flutter Agent Skills: How to Make Your AI Agent Actually Good at Flutter
Sayed Ali Alkamel
Sayed Ali Alkamel

Posted on

Flutter Agent Skills: How to Make Your AI Agent Actually Good at Flutter

#flutter #dart #ai #programming

TL;DR: Your AI coding assistant is a generalist. It writes Flutter that looks right but quietly reaches for 2022 patterns. Agent Skills are a new, official way (from the Dart and Flutter teams) to hand your agent task-specific, battle-tested workflows it loads on demand. Two repos, flutter/skills and dart-lang/skills, ship ready-to-use skills for responsive layouts, routing, testing, localization, static analysis, and more. Install in one command:

npx skills add flutter/skills --skill '*' --agent universal
npx skills add dart-lang/skills --skill '*' --agent universal

This post breaks down what they are, how they differ from rules files and MCP, the full catalog, what a real skill looks like under the hood, and whether they actually move the needle. (Spoiler: mostly yes, with one honest caveat.)

Let me tell you about a fight I have almost every day.

I ask my AI agent to make a screen adapt to tablets. It confidently hands me code that switches layout based on MediaQuery.orientationOf(context). It looks clean. It compiles. It even runs. And it's wrong, because device orientation has nothing to do with how much window space your app actually has on a foldable, in split-screen, or in a resizable desktop window.

The model isn't dumb. It's a generalist trained on a giant pile of Flutter code, much of it old. And here's the uncomfortable truth the Flutter team said out loud when they launched this feature: Flutter and Dart ship new features faster than LLMs can update their training data. That lag has a name, the knowledge gap, and it's why your agent keeps writing rookie Flutter with a straight face.

Agent Skills are the Flutter team's answer to that gap. I've been running them on real projects, and they're one of the few "AI workflow" things in 2026 that earned the hype instead of borrowing it. Let's get into it.

Table of Contents

The real problem: your AI is a generalist

AI agents can write Flutter and Dart. That's not in question anymore. The problem is which Flutter they write.

A generalist model has seen a million Stack Overflow answers, half of them deprecated. So when you ask for something specific, it averages across years of patterns and hands you the most statistically common answer, not the currently correct one. You get:

  • Layouts keyed off device type ("phone" vs "tablet") instead of available space.
  • Locked orientations that letterbox your app on foldables.
  • Hand-rolled fromJson that drifts from your actual model.
  • Routing glued together imperatively when your app needed deep links and browser history.
  • Hallucinated APIs that were never real, delivered with total confidence.

You already know this dance. You ask, it answers, you spend ten minutes correcting it back to what a senior Flutter dev would have written in the first place. Multiply that across a week and the "productivity tool" is quietly taxing you.

Agent Skills attack this at the source: instead of hoping the model remembers the right pattern, you give it the right pattern as a repeatable workflow.

What are Agent Skills, exactly?

An Agent Skill is a folder of plain-Markdown instructions, a SKILL.md file plus any supporting resources, that teaches an AI agent how to do one specific job the way a professional would.

Think of it as a task-oriented blueprint. Not "here's everything about Flutter," but "here is the exact, correct, step-by-step way to build an adaptive layout, including the traps to avoid and a checklist to verify you're done."

The mechanism that makes this practical is something the Flutter team calls progressive disclosure, and if you write Flutter you already understand it intuitively: it's deferred loading for your context window.

Here's the idea. Your agent doesn't slurp every instruction from every skill into its context up front. That would torch your token budget and bury the signal. Instead:

  1. The agent reads only the lightweight metadata of each skill first (a name and a short description of when to use it).
  2. When a task actually matches (say, you ask for a responsive layout), it pulls in the full instructions for that one skill, on demand.

Lazy-loaded expertise. The agent stays lean until the moment it needs to be an expert, then loads exactly the right playbook. That's the whole trick, and it's why this scales to dozens of skills without drowning the model.

Skills vs Rules vs MCP: who does what

This is where most people get confused, because Flutter now gives you three ways to steer an AI agent. They're not competitors; they're layers. Here's the mental model I use:

Layer What it is What it controls Analogy
Rules files Persistent project-wide config (e.g. an AI rules file) The agent's general behavior across every task The house style guide that's always in effect
Agent Skills Task-specific SKILL.md workflows, loaded on demand The step-by-step know-how for one specific job The expert playbook you open for a specific task
MCP (Dart & Flutter MCP server) A server exposing real tools to the agent The machinery: hot reload, runtime errors, analysis The power tools in the workshop

The cleanest way to say it: MCP gives the agent the tools. A Skill teaches the agent how to use those tools correctly for a specific task. Rules set the tone for everything.

In practice they stack beautifully. The MCP server lets the agent connect to your running app and hot reload after a change. A skill tells it when and why to do that as part of, say, fixing a layout overflow. Rules keep the whole thing consistent with your project's conventions. Together, that's an agent that behaves less like an intern and more like a teammate who's read your codebase's standards.

The full catalog: every official Flutter and Dart skill

Both repos are maintained by the actual Dart and Flutter teams and licensed BSD-3-Clause, so this isn't some random community dump; it's first-party guidance. Here's what shipped.

Flutter skills (flutter/skills)

Skill What it does
flutter-build-responsive-layout Build layouts that adapt to window space using LayoutBuilder, MediaQuery, Expanded/Flexible
flutter-fix-layout-issues Diagnose and fix overflows and unbounded-constraint errors ("RenderFlex overflowed", etc.)
flutter-apply-architecture-best-practices Structure the app in the recommended layered approach (UI, Logic, Data)
flutter-setup-declarative-routing Wire up MaterialApp.router with go_router for deep linking and browser history
flutter-implement-json-serialization Generate fromJson/toJson model classes correctly
flutter-use-http-package Make GET/POST/PUT/DELETE calls to REST APIs with the http package
flutter-setup-localization Add flutter_localizations + intl, configure l10n.yaml, scaffold translations
flutter-add-widget-test Write component tests with WidgetTester for rendering and interactions
flutter-add-widget-preview Add interactive widget previews via the previews.dart system
flutter-add-integration-test Configure Flutter Driver and turn agent UI actions into permanent integration tests

Dart skills (dart-lang/skills)

Skill What it does
dart-run-static-analysis Run dart analyze and auto-apply mechanical fixes with dart fix --apply
dart-fix-static-analysis-errors A workflow for hunting down and fixing analyzer errors after edits
dart-fix-runtime-errors Pull an active stack trace, locate the failing line, fix it, verify via hot reload
dart-add-unit-test Write and organize unit tests with package:test
dart-generate-test-mocks Generate mocks with package:mockito + build_runner
dart-collect-coverage Collect coverage with the coverage package and emit an LCOV report
dart-resolve-package-conflicts Fix pub get version conflicts
dart-build-cli-app Build CLI utilities: entrypoint structure, exit codes, cross-platform scripts
dart-use-pattern-matching Apply switch expressions and pattern matching where they belong
dart-migrate-to-checks-package Migrate assertions from package:matcher to package:checks

Look at that list as a Flutter dev and the value clicks immediately: these are exactly the tasks where a generalist model fumbles the current best practice. Adaptive layout. Routing. Localization. Serialization. The unglamorous, easy-to-get-subtly-wrong stuff.

Anatomy of a skill: what's actually inside that file

"A Markdown file" sounds underwhelming until you open one. Let me show you the flutter-build-responsive-layout skill, because it's the perfect rebuttal to that orientation bug I opened with.

A skill is structured guidance: rules, anti-patterns, workflows-as-checklists, and runnable examples. Here's the core of what this one teaches the agent:

The non-negotiable rules:

  • Use MediaQuery.sizeOf(context) to measure the app window, not the physical device.
  • Use LayoutBuilder and branch on constraints.maxWidth.
  • Do not use MediaQuery.orientationOf or OrientationBuilder near the top of the tree to swap layouts; orientation doesn't reflect available window space.
  • Do not check hardware type ("phone" vs "tablet"). Flutter runs in resizable windows, split-screen, and picture-in-picture.
  • Internalize the core rule: Constraints go down. Sizes go up. Parent sets position.
  • Don't lock orientation. It letterboxes your app on foldables and large-screen Android tiers.

That's a senior Flutter dev's hard-won instinct, written down where the model can't ignore it.

A workflow as an explicit checklist (the agent literally walks this):

[ ] Identify the widget that needs adaptive behavior.
[ ] Wrap the tree in a LayoutBuilder.
[ ] Extract constraints.maxWidth from the builder callback.
[ ] Define a breakpoint (e.g. largeScreenMinWidth = 600).
[ ] If maxWidth > breakpoint: return the large-screen layout (Row + sidebar).
[ ] Else: return the small-screen layout (Column / standard nav).
[ ] Run validator -> resize the window -> review transitions -> fix overflows.
Enter fullscreen mode Exit fullscreen mode

And a runnable reference example:

import 'package:flutter/material.dart';

const double largeScreenMinWidth = 600.0;

class AdaptiveLayout extends StatelessWidget {
  const AdaptiveLayout({super.key});

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        if (constraints.maxWidth > largeScreenMinWidth) {
          return _buildLargeScreenLayout();
        } else {
          return _buildSmallScreenLayout();
        }
      },
    );
  }

  Widget _buildLargeScreenLayout() {
    return Row(
      children: [
        const SizedBox(width: 250, child: Placeholder(color: Colors.blue)),
        const VerticalDivider(width: 1),
        Expanded(child: const Placeholder(color: Colors.green)),
      ],
    );
  }

  Widget _buildSmallScreenLayout() => const Placeholder(color: Colors.green);
}
Enter fullscreen mode Exit fullscreen mode

See what happened? The skill doesn't just say "be responsive." It bans the exact wrong instinct (orientation), prescribes the right one (constraints.maxWidth), hands over a verification loop, and gives a canonical example. The agent stops guessing and starts executing a known-good plan. That's the difference between "AI that writes Flutter" and "AI that writes your team's Flutter."

Get it running in two minutes

The skills are distributed through an npx CLI, so you'll need Node.js installed. From your project root:

# All Flutter skills
npx skills add flutter/skills --skill '*' --agent universal

# All Dart skills
npx skills add dart-lang/skills --skill '*' --agent universal
Enter fullscreen mode Exit fullscreen mode

A couple of things worth knowing:

  • The --agent universal flag drops everything into the standard .agents/skills directory, the folder that compatible agents auto-discover. Commit it, and your whole team (and CI) inherits the same expertise.
  • Want a subset instead of '*'? Swap in a specific skill name, e.g. --skill flutter-build-responsive-layout.
  • Update later with npx skills update.

Once they're installed, my favorite first move is to just ask the agent what it's now capable of:

"Review my .agents/skills directory. Which installed skills can help with making this dashboard work on tablet and desktop?"

It'll surface flutter-build-responsive-layout, explain the plan, and you're off; no guessing which incantation to type.

The honest take: hype or substance?

When these dropped, the Flutter corner of X and Reddit did what it always does: screenshots, "AI coding just changed again," the works. I want to be straight with you, because hype helps no one.

The substance is real. This isn't a vibe. It's first-party, task-scoped guidance that demonstrably stops common, current mistakes, and because of progressive disclosure it does so while lowering token usage and raising accuracy. For the unglamorous 80% of app work (layouts, routing, serialization, localization, tests), it's a genuine upgrade. I've shipped cleaner first drafts because of it.

Here's the caveat. Skills are guardrails, not a brain transplant. They make your agent reliably correct on known tasks; they don't make it inventive on novel architecture, and they won't save a vague prompt. The initial set is deliberately scoped to "the most common hurdles"; the Flutter team has been explicit that this is a starting point, not a finished product, and they're openly asking the community to file issues and contribute more.

So the right framing isn't "AI can now build my app." It's: your agent just stopped failing the easy stuff, so you can spend your judgment on the hard stuff. That's a trade I'll take every single day.

If you're already using Cursor, Claude Code, Antigravity, or any agent that reads .agents/skills, there's basically no reason not to try this on your next task.

Write your own skill

Once you feel the difference, you'll want to encode your team's patterns: your state management choice, your folder conventions, your API client. Because a skill is just a Markdown folder, that's very doable. The shape that works:

  1. Create the folder under .agents/skills/your-skill-name/ with a SKILL.md inside.
  2. Write tight metadata. A name and a one-line "use this when…" description. This is the part the agent reads first, so make the trigger condition unambiguous.
  3. State the rules and anti-patterns. Don't just say what to do; say what not to do. The "don't use orientation" line is what makes the responsive skill bulletproof.
  4. Add a workflow checklist. Spell out the steps as a literal task list the agent can march through and self-verify.
  5. Include a runnable example. One canonical, correct snippet is worth a thousand adjectives.

Then evaluate it like code: try it, watch where the agent still drifts, tighten the wording, repeat. Treat skill-writing as a loop (create, test, refine), not a one-and-done config file. The teams that win with AI in 2026 aren't the ones with the best model; they're the ones with the best-encoded knowledge.

FAQ

What are Flutter Agent Skills?
They're folders of Markdown instructions (SKILL.md files) that give an AI coding agent task-specific, expert Flutter and Dart workflows. They're maintained officially by the Dart and Flutter teams in the flutter/skills and dart-lang/skills repositories.

How are Agent Skills different from a rules file?
Rules configure the agent's general behavior across all tasks. A skill gives step-by-step instructions for one specific job, and is loaded only when that job comes up.

How do skills relate to the Dart & Flutter MCP server?
MCP provides the tools (hot reload, runtime errors, analysis). Skills provide the know-how to use those tools correctly. They're complementary layers, not alternatives.

Where do skills get installed?
Into the .agents/skills directory in your project, which compatible agents discover automatically. Use npx skills add ... --agent universal to target that standard location.

Do I need anything special to install them?
Just Node.js, since the skills CLI runs via npx.

Does this only work with one specific AI tool?
No. The .agents/skills convention is designed to be picked up by compatible agents broadly, which is the point of the universal flag.

Will skills make my AI write perfect apps?
No, and that's the honest part. They make it reliably correct on common, well-defined tasks. Novel architecture and vague prompts are still on you.

Wrapping up

The story of AI-assisted Flutter in 2026 isn't "the model got smarter." It's "we got better at telling the model what we already know." Agent Skills are the cleanest expression of that shift I've seen: take the hard-won patterns a senior Flutter dev carries in their head, write them down once, and hand them to your agent exactly when they're needed.

Install the official sets, ask your agent which skills apply to your current task, and watch the rookie mistakes quietly disappear. Then start encoding your own. That's where the real leverage is.

If you try this, I want to hear how it goes, especially which skill saved you the most correcting. Drop it in the comments, and if this was useful, follow me for more on Flutter, Dart, and building with AI agents without losing the plot. 🥊

Sources: Flutter docs: Agent skills, flutter/skills, dart-lang/skills, and the official Dart & Flutter team launch announcement (May 2026).

Top comments (0)