Flutter Agent Kit

A tool-agnostic guidance kit for Flutter / Dart development.

English | 简体中文

A tool-agnostic guidance kit for Flutter / Dart development. It ships one substantive guide — AGENTS.md — as the single source of truth, plus a marketplace-agnostic SKILL.md that any skill-capable agent can load (e.g. via skills.sh), reference docs under references/, and Dart helper scripts. The same AGENTS.md is consumed directly by any tool that prefers project-level guidance, so the content stays in one place.

✨ What's inside

File / folder	Purpose
AGENTS.md	Core guidance — the full, tool-agnostic Flutter / Dart playbook: coding conventions, architecture (app & plugin), state management, dependencies & versioning, error handling, navigation, i18n, testing, async/streams, assets, serialization, and more. Single source of truth.
SKILL.md	Marketplace-agnostic auto-load entry. A self-contained bundle of AGENTS.md, auto-generated by scripts/.../build_skill so the skill still works on marketplaces (e.g. skills.sh) that only download SKILL.md.
references/	Deeper docs: flutter_style.md, pubspec.md, architecture.md, platform_channel.md (Android / iOS / Linux / macOS / Windows / Web / OpenHarmony).
scripts/dart/	Helper scripts in Dart (*.dart).
scripts/python/	The same helper scripts in Python (*.py). Identical behavior & CLI: verify, create_feature, bump_version.
install.dart / install.py	Detects your AI tool and places/soft-links the right entry file. Pick the Dart or Python runtime.

🚀 Install (recommended)

Pick whichever runtime you have — the Dart SDK (any Flutter dev already has it) or just Python 3.

git clone https://github.com/zero-labsco/flutter-agent-kit.git
cd flutter-agent-kit
dart run install.dart      # Dart runtime
# or / 或
python install.py          # Python runtime

install.dart / install.py detect installed tools and wire up the kit. This covers the most common local tools; for the full, always-growing list of marketplace-supported agents, install via skills.sh instead (see below).

Tool	What the installer does
CodeBuddy	Symlinks this kit into ~/.codebuddy/skills/flutter-agent-kit/ (auto-loads via SKILL.md).
Claude Code	Symlinks into ~/.claude/skills/flutter-agent-kit/ (also reads SKILL.md).
Codex	Symlinks into $CODEX_HOME/skills/flutter-agent-kit/ (defaults to ~/.codex/skills/; reads SKILL.md).
OpenCode	Symlinks into ~/.config/opencode/skills/flutter-agent-kit/ (Windows: %USERPROFILE%\.config\opencode\skills\; reads SKILL.md).
Cursor	Copies AGENTS.md content into the project's .cursorrules / Cursor rules.
Gemini CLI	Copies AGENTS.md into the project's GEMINI.md (per-project context file).
Aider	Copies AGENTS.md into the project's CONVENTIONS.md (Aider's convention file).
Zed	Copies AGENTS.md into the project's .rules (Zed's project rules file).
GitHub Copilot (VS Code)	Copies AGENTS.md into the current project's .github/copilot-instructions.md.
other (picker only)	Names a custom project-level instruction file for any tool not listed (e.g. CLAUDE.md, .windsurfrules).

Scope of this table: these are the tools the installer can auto-wire for you (user-level symlink or per-project file). The kit itself is tool-agnostic — any other skill-capable agent can load SKILL.md directly via a marketplace (e.g. npx skills add https://skills.sh/...); that path does not go through this installer and is unaffected by the list above.

Re-run the installer any time to update (idempotent).

Options

Flag	Meaning	Optional?
-p, --project <path>	Target project root for Cursor/Copilot entries.	Optional (defaults to auto-detect nearest Flutter project)
-t, --tool <tool>	Wire only one tool (non-interactive): codebuddy | claude | codex | opencode | cursor | gemini | copilot | aider | zed.	Optional (omit = interactive picker, or all in non-interactive shells)
-h, --help	Print usage and exit.	Optional

Works in cmd, PowerShell, bash, zsh — just quote paths that contain spaces, e.g. -p "D:\My Project\app".

支持 cmd、PowerShell、bash、zsh —— 路径含空格时加引号即可， 如 -p "D:\My Project\app"。

Target a specific project (non-intrusive)

Run the installer from the kit folder and pass a target project root with --project. Cursor / Copilot entries are written directly into that project instead of scanning upward from the kit — the kit folder itself is never modified.

dart run install.dart -p /path/to/my_project
# or / 或
python install.py -p /path/to/my_project

Since you always run the installer from the kit folder, -p (short for --project) is the simplest way to point at the target project. 由于安装脚本本就在 kit 目录运行，-p（--project 的简写）是指定目标项目最简洁的方式。 Omit it to fall back to auto-detecting the nearest Flutter project by walking up from the kit folder. 省略则回退到从 kit 目录向上查找最近的 Flutter 项目。

Choosing tools (interactive picker)

Run with no -t and the installer shows an interactive list of all supported tools, 5 per page (type n / p to page). Type a number and press Enter to toggle it — multi-select, space/comma separated, accumulates across pages. When you're done, press Enter on an empty line to confirm (you must pick at least one — there is no "select all"). Type q / quit / exit to quit. (Navigation is number-key + Enter — no arrow-key support.) A trailing other entry lets you name a custom project-level instruction file (e.g. CLAUDE.md, .windsurfrules) for any tool not in the list — it is written into the target project like the other project-level entries. When you pick a project-level tool (Cursor / Copilot / Gemini / Aider / Zed / other) without passing --project, the installer prompts you for the target project root so the file lands in that project; leave it empty to auto-detect the nearest Flutter project. In a non-interactive shell (CI, piped output) it skips the prompt and wires every supported tool.

不带 -t 运行时，安装脚本会显示交互清单，列出所有支持的工具，每页 5 个 （输入 n / p 翻页）。按编号选择——支持多选，空格或逗号分隔，跨页累计； 按 d 确认，或直接回车选全部。末尾的 other 项可让你为列表之外的工具 指定自定义项目级指令文件（如 CLAUDE.md、.windsurfrules）——它会像其他项目级 入口一样写入目标项目。当你选了某个项目级工具（Cursor / Copilot / Gemini / Aider / Zed / other）却未传 --project 时，安装脚本会询问目标项目根目录，让文件落到 该项目；留空则自动查找最近的 Flutter 项目。在非交互环境（CI、管道输出）下会跳过 提示，自动接入所有支持的工具。

dart run install.dart            # interactive picker / 交互清单
python install.py               # interactive picker / 交互清单

Limit to a single tool (non-interactive)

Use -t <tool> (short for --tool) to wire only one tool without the prompt. Valid values: codebuddy, claude, codex, opencode, cursor, gemini, copilot.

使用 -t <tool>（--tool 的简写）可跳过交互、只接入某一个工具。合法取值： codebuddy、claude、codex、opencode、cursor、gemini、copilot。

dart run install.dart -p /path/to/my_project -t cursor
# or / 或
python install.py -p /path/to/my_project --tool copilot

🛠 Helper scripts (Dart + Python)

The helpers ship twice — once in Dart under scripts/dart/ and once in Python under scripts/python/. Pick whichever runtime you have; the CLI and behavior are identical.

Script	Dart	Python	Purpose
Verify	dart run scripts/dart/verify.dart [--no-publish]	python scripts/python/verify.py [--no-publish]	Runs flutter analyze + flutter test + publish dry-run.
Create feature	dart run scripts/dart/create_feature.dart <name> [--pattern mvvm|mvp]	python scripts/python/create_feature.py <name> [--pattern mvvm|mvp]	Scaffolds lib/features/<name>/{data,domain,presentation/} with per-layer barrels, a presentation/view_model/ (default MVVM) or presentation/presenter/ (MVP) layer, and a feature barrel.
Bump version	dart run scripts/dart/bump_version.dart <major|minor|patch>	python scripts/python/bump_version.py <major|minor|patch>	Bumps pubspec.yaml and prints the git tag command.
Build skill	dart run scripts/dart/build_skill.dart	python scripts/python/build_skill.py	Regenerates the self-contained SKILL.md bundle from AGENTS.md (run after editing guidance).

Contributing: AGENTS.md + references/ are the single source of truth. After editing either, re-run build_skill so the bundled SKILL.md stays in sync. Never hand-edit SKILL.md. 贡献提示: AGENTS.md 与 references/ 为唯一真源。修改后请重跑 build_skill 以保持打包的 SKILL.md 同步,请勿手动编辑 SKILL.md。

📦 Install (manual fallback)

The installer automates everything below, including any tool not in the list via the interactive other option (it copies AGENTS.md into your project under a filename you name — e.g. CLAUDE.md, .windsurfrules). So in normal use you should never need this section.

Only fall back to manual placement when the script genuinely can't run in your environment (non-supported OS, no Dart/Python, etc.). Place the files yourself:

• User-level skills (CodeBuddy / Claude Code / Codex / OpenCode): copy this folder into ~/.codebuddy/skills/, ~/.claude/skills/, ~/.codex/skills/, or ~/.config/opencode/skills/.
• Project-level entries (Cursor / Copilot / Gemini / Aider / Zed / any "other" tool): copy AGENTS.md into the target project as the tool's instruction file — .cursorrules, .github/copilot-instructions.md, GEMINI.md, CONVENTIONS.md, .rules, or whatever your agent reads. This is exactly what the script's other option does for you.

Most users should instead install straight from a marketplace — e.g. npx skills add https://skills.sh/... — which works with any skill-capable agent and pulls the bundled SKILL.md directly.

🔄 Updating

Pull latest and re-run dart run install.dart (or python install.py).

📄 License

Released under the MIT License.