Overhaul AI documentation architecture and getting started guides - #13778
Overhaul AI documentation architecture and getting started guides#13778jesskuras wants to merge 14 commits into
Conversation
- Centralize coding assistant setup instructions in /ai/get-started with tabs for Antigravity, Claude Code, Cursor, GitHub Copilot, Codex, and generic MCP clients. - Add /ai/tools explaining agent skills, the Dart and Flutter MCP server, Developer Knowledge MCP server, package skills, AI rules, and custom agents. - Add /ai/package-skills for app developers and package authors. - Cross-link package skills in /packages-and-plugins guides and sidebar. - Remove redundant and deprecated pages (/ai/create-with-ai, /ai/coding-assistants/*, /ai/agent-skills, /ai/mcp-server, /ai/ai-rules, /ai/best-practices/developer-experience, /ai/evals). - Configure 301 redirects for all removed pages in sites/docs/firebase.json. - Update sidebar navigation in default.yml and fix cross-site links.
f61b03b to
e1c06ee
Compare
|
Staged preview of the updated docs.flutter.dev site (updated for commit 07d70f4): https://flutter-docs-prod--docs-pr13778-ai-docs-overhaul-robeno19.web.app |
|
Staged preview of the updated flutter.dev site (updated for commit 07d70f4): https://flutter-dev-230821--www-pr13778-ai-docs-overhaul-grh8yqwe.web.app |
- Update CLI binary name to agy. - Replace placeholder command with MCP JSON config and universal skills installation.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request reorganizes and consolidates the AI-assisted development documentation for Flutter and Dart. It removes several redundant or outdated markdown files (such as agent-skills.md, ai-rules.md, antigravity.md, and mcp-server.md) and introduces two new guides: package-skills.md and tools.md. Additionally, it updates the get-started.md guide to serve as a comprehensive entry point for setting up various AI coding assistants, and updates relevant links, redirects, and the sidebar navigation accordingly. The review feedback highlights an outdated global configuration path for the Antigravity CLI and points out multiple instances of an invalid Dart CLI command syntax (using skills@ instead of skills).
| 1. Configure the Dart and Flutter MCP server in your project's | ||
| `.agents/mcp_config.json` file (or globally in | ||
| `~/.gemini/config/mcp_config.json`): |
There was a problem hiding this comment.
The global configuration path mentioned here (~/.gemini/config/mcp_config.json) is outdated and refers to the legacy Gemini CLI. Since this section is specifically for the Antigravity CLI, the global configuration should point to the new path: ~/.antigravity/mcp_config.json.
| 1. Configure the Dart and Flutter MCP server in your project's | |
| `.agents/mcp_config.json` file (or globally in | |
| `~/.gemini/config/mcp_config.json`): | |
| 1. Configure the Dart and Flutter MCP server in your project's | |
| `.agents/mcp_config.json` file (or globally in | |
| `~/.antigravity/mcp_config.json`): |
| When you add a dependency to your project, you can discover and install its | ||
| skills using the `skills` CLI: | ||
|
|
||
| ```bash | ||
| dart run skills@ get | ||
| ``` |
There was a problem hiding this comment.
The command dart run skills@ get contains an invalid package name skills@. Please remove the @ symbol to make it a valid Dart CLI command.
| When you add a dependency to your project, you can discover and install its | |
| skills using the `skills` CLI: | |
| ```bash | |
| dart run skills@ get | |
| ``` | |
| When you add a dependency to your project, you can discover and install its | |
| skills using the `skills` CLI: | |
| ```bash | |
| dart run skills get |
| If your project dependencies include skills, you can discover and install them | ||
| into your local workspace with a single command: | ||
|
|
||
| ```bash | ||
| dart run skills@ get | ||
| ``` |
There was a problem hiding this comment.
The command dart run skills@ get contains an invalid package name skills@. Please remove the @ symbol to make it a valid Dart CLI command.
| If your project dependencies include skills, you can discover and install them | |
| into your local workspace with a single command: | |
| ```bash | |
| dart run skills@ get | |
| ``` | |
| If your project dependencies include skills, you can discover and install them | |
| into your local workspace with a single command: | |
| ```bash | |
| dart run skills get |
|
|
||
| 1. Create a `skills/` directory in the root of your package repository. | ||
| 2. Inside `skills/`, create a subdirectory prefixed with your package name (for | ||
| example, `skills/my_package_network/`). |
There was a problem hiding this comment.
You can (and technically should) actually use hyphens instead of underscores, this is just a clash between the skills spec and dart package name rules, but skills are only supposed to use hyphens.
We do allow either, and afaik all the agents will allow underscores in practice, but its technically a spec violation.
| example, `skills/my_package_network/`). | |
| example, `skills/my-package-network/`). |
| configuration for the [Dart and Flutter MCP server](/ai/mcp-server). | ||
| By default, general-purpose AI assistants might not have the latest context on | ||
| Flutter patterns, project diagnostics, or third-party packages. Installing the | ||
| official Flutter agent plugins equips your assistant with dedicated tools and |
There was a problem hiding this comment.
| official Flutter agent plugins equips your assistant with dedicated tools and | |
| official Flutter agent plugin equips your assistant with dedicated tools and |
| In addition to core Flutter plugins, you can also equip your assistant with | ||
| [package skills](/ai/package-skills) shipped directly by third-party `pub.dev` | ||
| libraries. |
There was a problem hiding this comment.
| In addition to core Flutter plugins, you can also equip your assistant with | |
| [package skills](/ai/package-skills) shipped directly by third-party `pub.dev` | |
| libraries. | |
| In addition to core Flutter plugins, you can also equip your assistant with | |
| skills that are shipped directly by third-party `pub.dev` | |
| packages using the [skills](/ai/package-skills) package. |
| } | ||
| ``` | ||
|
|
||
| 1. Install official Flutter and Dart skills into your workspace: |
There was a problem hiding this comment.
I'm confused how Antigravity CLI plugins work. When I install the Flutter plugin in Antigravity 2.0, it goes into my ~/.gemini/config/plugins/flutter/ directory, and the Antigravity CLI can see it. But when I run agy plugins list, I don't see it.
I think this section will eventually be replaced with a simple agy plugin install command, but I don't know exactly what that should look like.
cc: @keertip
sfshaza2
left a comment
sfshaza2
left a comment
There was a problem hiding this comment.
@jesskuras, this is a great overhaul! I leave the technical accuracy to the tech reviewers (and the bot certainly has thoughts), but I spent some time on the staged site and it's so much cleaner, more concise, and clearer. I'm glad that the AI tab (which I'm not a fan of and would prefer to delete) just takes you to the same pages as the sidenav that you've restored. I know you have some feedback to incorporate, but I'm going to lgtm this so you can land when ready!
| Use when making network requests with my_package to ensure safe patterns. | ||
| --- | ||
|
|
||
| # Error Handling Guidelines |
There was a problem hiding this comment.
| # Error Handling Guidelines | |
| # Error handling guidelines |
lamek
left a comment
lamek
left a comment
There was a problem hiding this comment.
LGTM.
Much cleaner, great update Jess.
| ## How to perform a hot reload | ||
|
|
||
| If you are using an AI coding assistant like [Google Antigravity](/ai/antigravity), | ||
| If you are using an AI coding assistant like [Google Antigravity](/ai/get-started), |
There was a problem hiding this comment.
We can probably remove this as we link to the same place a few lines down.
|
|
||
| If you are using an AI coding assistant like [Google Antigravity](/ai/antigravity), | ||
| If you are using an AI coding assistant like [Google Antigravity](/ai/get-started), | ||
| you can use Agent mode to automatically hot reload your running application |
There was a problem hiding this comment.
This update is a good chance to clarify this. Suggestion:
If you are using an AI coding assistant like Google Antigravity, the assistant can automatically hot reload your running application after making changes, or when asked to "Reload the app".
6 participants
Description
This PR overhauls the content and information architecture of the Flutter AI documentation (
docs.flutter.dev/ai), unifying getting started workflows, consolidating conceptual guides, and removing outdated / redundant pages.Key Changes
/ai/get-started:/ai/tools:/ai/package-skills:dart run skills@ get.skills/<package_name>/SKILL.md./packages-and-plugins/using-packagesand/packages-and-plugins/developing-packages./ai/create-with-ai,/ai/coding-assistants/*,/ai/antigravity*,/ai/agent-skills,/ai/mcp-server,/ai/ai-rules,/ai/best-practices/developer-experience, and/ai/evals.sites/docs/firebase.jsonfor all removed routes.sites/docs/src/data/sidenav/default.yml.index.md,llms.txt,hot-reload.md, etc.).