A comprehensive handbook on using and writing 'agent skills' - structured Markdown files stored in .agents/skills/ - to teach AI coding agents (Claude Code, Antigravity, OpenAI Codex, Cursor, GitHub Copilot CLI, Gemini CLI) how a specific Flutter/Dart team writes code. Covers installing the official flutter/agent-plugins and dart-lang/skills repositories via the skills CLI, the anatomy of a skill file (YAML frontmatter plus Markdown body), progressive disclosure for context management, per-agent configuration details, a deep dive into official Flutter and Dart skills, and guidance for writing custom skills based on real codebase mistakes like private build methods, Map instead of typed models, and inconsistent state management.
Table of contents
Table of ContentsPrerequisitesWhat Are Agent Skills?The Problem: Why AI Agents Get Flutter WrongHow Skills Work: Progressive DisclosureThe Anatomy of a Skill FileInstalling Official Flutter and Dart SkillsUsing Skills with Claude CodeUsing Skills with AntigravityUsing Skills with OpenAI CodexUsing Skills with CursorUsing Skills with Other AgentsThe Official Flutter Skills: A Deep DiveThe Official Dart Skills: A Deep DiveThe flutter-file-organization Skill: A Complete WalkthroughWriting Your Own Skills: The Complete GuideEssential Flutter Skills Every Team Should HaveEssential Dart Skills Every Developer Should WriteSkills for Architecture and Large CodebasesAdvanced Skill PatternsPackage-Level Skills: Teaching the Agent Your LibrariesSkills vs Rules vs MCP: Knowing the DifferenceOrganizing Skills in a TeamBest Practices for Writing SkillsCommon Mistakes When Writing SkillsConclusionReferencesQuestions this post answers
How do I install the official Flutter agent skills for my AI coding agent?
Run npx skills add flutter/agent-plugins --skill '*' --agent universal --yes, which installs all official Flutter skills into the .agents/skills/ directory. This covers responsive layouts, GoRouter routing, json_serializable serialization, widget and integration testing, and Bloc-based clean architecture. Pair it with npx skills add dart-lang/skills --skill '*' --agent universal --yes for Dart-specific skills like static analysis and pattern matching. Developers wiring up AI agents for Flutter work track setup guides like this on daily.dev.
Where should agent skill files live in a Flutter project and what format do they use?
Skill files live in the .agents/skills/ directory at the project root as Markdown files with YAML frontmatter containing name, description, aliases, and sources fields. This location follows the universal specification at agentskills.io, so tools like Claude Code, Cursor, Antigravity, and OpenAI Codex all discover the same skills without needing agent-specific copies. Teams standardizing AI agent conventions across tools compare setups like this on daily.dev.
Why does my AI coding agent keep mixing Bloc, Provider, and setState in the same Flutter codebase?
Without an agent skill specifying your state management choice, the agent draws from mixed training data and picks whatever pattern appears most in similar contexts, resulting in inconsistent Bloc, Provider, or setState usage across sessions. Writing a skill file that names your team's chosen pattern (e.g., flutter_bloc) and its API surface (BlocProvider, BlocBuilder) constrains the agent to that convention consistently. Developers debugging inconsistent AI-generated Flutter code check practical fixes like this on daily.dev.