From 6311470723c85c2d304621c012e9425a72649f5d Mon Sep 17 00:00:00 2001 From: Kevin Lamenzo Date: Tue, 8 Sep 2026 19:53:37 +0000 Subject: [PATCH] docs: document agentic rules and manual setup for supported assistants (b/558792468) Add agentic rules documentation back to the /ai documentation suite, explaining what agent rules are, linking to the official repository, and providing instructions for manually configuring rules across supported AI coding assistants (Claude Code, Cursor, Codex, and GitHub Copilot). - Add 'Agent rules' as a core mechanism to /ai/tools and update the comparison table. - Add a focused Agent rules section in /ai/tools. - Provide future-proof rule instructions in each agent tab in /ai/get-started, linking to the official rules repository. Fixes: b/558792468 --- sites/docs/src/content/ai/get-started.md | 50 +++++++++++++++++++++++- sites/docs/src/content/ai/tools.md | 18 ++++++++- 2 files changed, 66 insertions(+), 2 deletions(-) diff --git a/sites/docs/src/content/ai/get-started.md b/sites/docs/src/content/ai/get-started.md index 60a2522037..d4d4c4a52a 100644 --- a/sites/docs/src/content/ai/get-started.md +++ b/sites/docs/src/content/ai/get-started.md @@ -20,12 +20,15 @@ An **agent plugin** bundles the tools and knowledge that an AI assistant needs to understand and modify your Flutter codebase. When you install an official Flutter agent plugin, it connects your assistant -to three core capabilities: +to four core capabilities: * **[Agent skills](/ai/tools#agent-skills)**: on-demand procedural guides from the official Flutter and Dart repositories that teach the assistant how to perform specific tasks, such as creating responsive layouts, managing state, or writing widget tests. +* **[Agent rules](/ai/tools#agent-rules)**: persistent instructions that guide + an assistant's responses, such as proactively triggering stateful hot reload + when editing Flutter widgets. * **[Dart and Flutter MCP server](/ai/tools#dart-and-flutter-mcp-server)**: a Model Context Protocol (MCP) server that connects the assistant to the Dart SDK, giving it real-time access to analyzer diagnostics, symbol @@ -135,6 +138,15 @@ Equip Claude Code with official Flutter and Dart skills and MCP configuration: claude plugin install dart-flutter@dart-flutter ``` +**Configure agent rules** + +Claude Code plugins discover skills and MCP servers, +but do not automatically load plugin rules. +To equip Claude Code with official Flutter rules, +add the rules you want from the +[official rules repository](https://github.com/flutter/agent-plugins/tree/main/rules) +to your project's `CLAUDE.md` file. + **Verify installation** Verify that the plugin is active in Claude Code: @@ -171,6 +183,15 @@ plugins directory: 1. Restart Cursor. The editor automatically discovers the bundled skills and configures the Dart and Flutter MCP server. +**Configure agent rules** + +Cursor supports file-scoped rules in the `.cursor/rules/` directory +using `.mdc` files. +To equip Cursor with official Flutter rules, +download the `.mdc` files from the +[official rules repository](https://github.com/flutter/agent-plugins/tree/main/rules) +into your project's `.cursor/rules/` directory. + @@ -194,6 +215,16 @@ Equip Codex with official Flutter and Dart skills and MCP configuration: codex plugin add dart-flutter@dart-flutter ``` +**Configure agent rules** + +Codex plugins install skills and MCP servers, +but do not automatically bundle rules. +To equip Codex with official Flutter rules, +download the `.md` rule files from the +[official rules repository](https://github.com/flutter/agent-plugins/tree/main/rules) +into your project's `.agent/rules/` directory, +or append the rule instructions to `CODEX.md`. + **Verify installation** Verify that the plugin is active in Codex: @@ -238,6 +269,15 @@ npx skills add flutter/agent-plugins --skill '*' --agent universal --yes npx skills add dart-lang/skills --skill '*' --agent universal --yes ``` +**Configure agent rules** + +GitHub Copilot supports custom workspace instructions in +`.github/copilot-instructions.md`. +To equip Copilot with official Flutter rules, +add the rules you want from the +[official rules repository](https://github.com/flutter/agent-plugins/tree/main/rules) +to your project's `.github/copilot-instructions.md` file. + @@ -279,6 +319,14 @@ npx skills add flutter/agent-plugins --skill '*' --agent universal --yes npx skills add dart-lang/skills --skill '*' --agent universal --yes ``` +**Configure agent rules** + +If your coding assistant supports project instructions or rules +(such as Windsurf `.windsurfrules` or Cline `.clinerules`), +copy or download rules from the +[official rules repository](https://github.com/flutter/agent-plugins/tree/main/rules) +into your assistant's configuration file. + diff --git a/sites/docs/src/content/ai/tools.md b/sites/docs/src/content/ai/tools.md index 75557fcc1c..a9499f8796 100644 --- a/sites/docs/src/content/ai/tools.md +++ b/sites/docs/src/content/ai/tools.md @@ -12,7 +12,7 @@ development tasks accurately. ## Tooling ecosystem overview -The Flutter AI tooling ecosystem consists of five complementary components: +The Flutter AI tooling ecosystem consists of six complementary components: 1. **Agent skills**: task-oriented blueprints that teach assistants how to perform specific workflows (such as creating responsive layouts or writing @@ -27,6 +27,8 @@ The Flutter AI tooling ecosystem consists of five complementary components: 5. **Specialized agents**: dedicated agent personas equipped with focused tools and system instructions for isolated workflows, such as accessibility auditing. +6. **Agent rules**: persistent rules added to the context window every time + you start a new session with your assistant. --- @@ -157,6 +159,19 @@ review your code for accessibility: --- +## Agent rules + +**Agent rules** are persistent rules added to the context window +every time you start a new session with your assistant. +Rules establish project conventions and common constraints +across your codebase. + +To explore official Flutter rules, +visit the [flutter/agent-plugins](https://github.com/flutter/agent-plugins) +repository. + +--- + ## When to use what Use the following mental model to understand how different AI mechanisms @@ -169,6 +184,7 @@ interact: | **Developer Knowledge MCP** | Online search | Live docs, API references | | **Package skill** | From dependencies | Library APIs, code generation | | **Specialized agent** | Isolated subagent | Accessibility audits | +| **Agent rule** | Persistent context | Project conventions, constraints | {:.table .table-striped}