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 and Dart agent skills for my AI coding agent?
Run npx skills add flutter/agent-plugins --skill '*' --agent universal --yes and npx skills add dart-lang/skills --skill '*' --agent universal --yes. This places skill files into the .agents/skills/ directory, which is discovered automatically by Claude Code, Cursor, Antigravity, Codex, GitHub Copilot CLI, and Gemini CLI. Use --agent <name> to target a specific agent instead of universal. Developers standardizing AI coding setups across teams can track tooling changes like this via daily.dev.
What is the difference between an agent skill and a rules file like CLAUDE.md in Claude Code?
A rules file such as CLAUDE.md or AGENTS.md holds project-wide facts that are always loaded into context, like the SDK version, package name, and installed libraries. A skill is a task-specific Markdown file loaded progressively, only when a task matches its description, containing detailed how-to guidance such as file organization rules or Bloc naming conventions. Keeping detailed instructions out of always-loaded rules files preserves context budget. Anyone deciding where to store AI agent conventions can compare approaches like this on daily.dev.
Why should a StatefulWidget and its State class never be split into separate files when an AI agent refactors Flutter code?
Splitting them breaks Flutter's compilation model because the private State class references the widget through the 'widget' property, whose type is established at the State<T> class declaration level, making the two classes a single inseparable compilation unit. AI agents without explicit guidance may attempt this split since general Dart knowledge doesn't reveal this Flutter-specific constraint, causing compile errors. Flutter developers debugging AI-generated refactors can find guidance like this through daily.dev.
Share this post