Flutter AI Skills and Rules for Cursor, Copilot, Antigravity, and Other AI-Powered IDEs

<img src="media/flutter_ai_rules.png" width="500" alt="Flutter Rules for Windsurf, Cursor">

⚡ TLDR

Primary method: Copy skill folders from skills/ into your IDE's skills directory (e.g., .cursor/skills/, .windsurf/skills/). The agent will automatically use relevant skills based on your tasks.

For traditional rules: If you want to use .cursor/rules or .windsurfrules, just copy the contents of the rule set of your choice (e.g., combined/flutter_dart__under_6K.md) into your IDE's global or local rules.
For maximum control, you can also copy the /rules folder into your project and reference rules as needed (e.g., "Read @rules/firebase/ and set up a project with Realtime Database, App Check, and Analytics.").

🚀 Introduction

This repository provides a comprehensive, (almost) non-opinionated collection of Flutter-related rules tailored for use with Windsurf, Cursor, and other AI-powered IDEs. These rules are designed to improve your development workflow, ensure consistency, and help you get the most out of your AI coding assistant.

📁 Repository Structure

• skills/
  NEW! Skills are an open standard for extending agent capabilities. A skill is a folder containing a SKILL.md file with instructions that the agent can follow when working on specific tasks. They are essentially what “dynamic rules” used to be — applied automatically when the agent determines they are relevant based on the description.

  Copy or symlink any skill folder into .cursor/skills/, .agent/skills/, or another supported location.

• rules/
  Contains individual rule files, each focused on a specific topic or tool (e.g., bloc.md, effective_dart.md, etc.).
  These files are:

  • Based only on official documentation from Flutter, Dart, or relevant package websites.
  • Categorized by subject to make them easy to mix, match, and reference.
  • Meant to be refined, adjusted, or extracted based on your project needs.

• combined/
  Contains pre-made, curated sets of rules that combine commonly used topics (e.g., Flutter + Riverpod + Mockito).
  These files:

  • Are kept under 6,000 characters to comply with Windsurf's limit.
  • Can be used as-is by copying them into your global or local rules configuration.

✅ How To Use

Option 1: Skills - Agent Will Decide What to Use

1. Browse the skills/ folder.
2. Copy or symlink skill folders into your IDE's skills directory (e.g., .cursor/skills/, .windsurf/skills/).
3. The agent will automatically use relevant skills based on your task descriptions.
4. You're ready to go - skills activate contextually without manual selection.

Option 2: Use Pre-Made Combined Rules

If you want a quick setup with traditional rules:

1. Browse the combined/ folder.
2. Copy a file that suits your project.
3. Paste it into your IDE's global or local rules config.
4. You're ready to go.

Option 3: Use Individual Rule Files

If you prefer more control:

1. Browse the rules/ folder.
2. Pick files relevant to your project (e.g., riverpod.md, bloc.md, etc.).
3. You can:
   • Include them directly in your IDE setup.
   • Reference them in prompts to add context.
   • Extract only the parts that are useful for your context.
   • Include them partially or fully in a PRD (Product Requirements Document).

<div align="center"> <img src="media/mocktail_md_01.png" width="300" alt="Example usage with Mocktail rules"> <img src="media/mocktail_md_02.png" width="300" alt="Example usage with Mocktail rules"> </div>

Everything is modular — use what works best for you.

Option 4: Download All Skills via CLI

You can fetch the latest skills directly into your project with a single command:

git clone --depth 1 https://github.com/evanca/flutter-ai-rules.git temp_repo && mkdir -p .skills && cp -r temp_repo/skills/* .skills && rm -rf temp_repo

This will copy all skills into a .skills folder in your project. After all skills are in the .skills folder, you can reference them individually based on your needs. For example:

"Read @.skills/bloc/SKILL.md and create test coverage for new methods."

Pro tip:
You can also configure your IDE to automatically load skills from this .skills folder, or reference them in prompts for specific guidance.

📏 No Opinions, Just Documentation

All rules are sourced from official documentation — no personal preferences or subjective interpretations. That’s intentional. You’re free to alter them to your taste, but this repo keeps things objective by sticking to the source.

Note: This might sometimes lead to contradictory rules (e.g., if one package suggests one folder architecture and another recommends a different one).

📌 Use Cases

• Install skills in your IDE for automatic, contextual assistance during development.
• Set up global rules for a Flutter project in your IDE.
• Configure project-specific constraints for popular state management packages.
• Provide clear expectations in a PRD when working with a team.
• Extract only what you need to avoid rule clutter.
• Reference individual skills or rules in prompts for specific guidance.

🛠️ Contributing

Contributions are welcome! If you'd like to suggest a new rule or improve an existing one, here’s how you can help:

1. Fork this repository.
2. Add or modify rules in the appropriate folder.
3. Submit a pull request with a clear explanation of your changes.
   Make sure to include an official documentation link for any rule set you’re adding or modifying to keep everything objective and reliable.

📚 References

Here are the official sources that have been used to build these rules:

Flutter

• Flutter App Architecture - Official Flutter architecture guidelines
• Flutter Common Errors - Common errors documentation
• Flutter ChangeNotifier State Management - Simple state management with ChangeNotifier

Dart

• Effective Dart - Official Dart style guidelines
• Dart 3 Updates - Documentation on Dart 3 features including:
  • Records
  • Patterns
  • Pattern Types
  • Branches

State Management

• Bloc Library - Official Bloc library documentation
• Provider - Official Provider package documentation
• Riverpod - Official Riverpod documentation

Testing

• Mockito - Official Mockito for Dart documentation
• Mocktail - Official Mocktail documentation

Firebase

• Firebase for Flutter - Official Firebase Flutter documentation
• Code with Andrea - How to Setup Flutter & Firebase with Multiple Flavors using the FlutterFire CLI