███████╗██╗     ██╗   ██╗████████╗████████╗███████╗██████╗
██╔════╝██║     ██║   ██║╚══██╔══╝╚══██╔══╝██╔════╝██╔══██╗
█████╗  ██║     ██║   ██║   ██║      ██║   █████╗  ██████╔╝
██╔══╝  ██║     ██║   ██║   ██║      ██║   ██╔══╝  ██╔══██╗
██║     ███████╗╚██████╔╝   ██║      ██║   ███████╗██║  ██║
╚═╝     ╚══════╝ ╚═════╝    ╚═╝      ╚═╝   ╚══════╝╚═╝  ╚═╝
 ██████╗ ██████╗ ████████╗██╗███╗   ███╗██╗███████╗███████╗██████╗
██╔═══██╗██╔══██╗╚══██╔══╝██║████╗ ████║██║██╔════╝██╔════╝██╔══██╗
██║   ██║██████╔╝   ██║   ██║██╔████╔██║██║███████╗█████╗  ██████╔╝
██║   ██║██╔═══╝    ██║   ██║██║╚██╔╝██║██║╚════██║██╔══╝  ██╔══██╗
╚██████╔╝██║        ██║   ██║██║ ╚═╝ ██║██║███████║███████╗██║  ██║
 ╚═════╝ ╚═╝        ╚═╝   ╚═╝╚═╝     ╚═╝╚═╝╚══════╝╚══════╝╚═╝  ╚═╝

⚡ Flutter Optimiser

Evidence-based performance skills for AI coding agents

imageValidate skills imageLicense: MIT imageAgent skills imageFormat imageTooling

Table of contents:

• Skills
• How they fit together
• Install
• Usage
• Validate
• Layout
• Status and limits

Important

Principle: inspect first, measure, change only what evidence justifies, preserve all business behaviour.

A set of agent skills for auditing and optimising any production Flutter app, based on Flutter's official performance guidance. One router skill plus eight focused skills, following the Agent Skills open format: drop them into Claude Code, Codex, Cursor, Copilot, OpenCode, or any SKILL.md-compatible agent.

🧩 Skills

🗺️ How they fit together

flowchart TD
    S["⚡ flutter-performance-specialist<br/>router · guardrails · report format"]
    S --> A["🔍 flutter-perf-audit<br/>investigate + plan"]
    S --> B["🏗️ flutter-perf-build-and-rebuild<br/>build() · const · rebuild scope"]
    S --> L["📜 flutter-perf-lists-and-scrolling<br/>lazy lists · extents"]
    S --> D["🧮 flutter-perf-derived-state<br/>caching · client vs backend"]
    S --> I["🧵 flutter-perf-isolates<br/>CPU-bound work off the UI isolate"]
    S --> P["🖼️ flutter-perf-images-and-assets<br/>decoding · densities · SVG vs raster"]
    S --> E["✨ flutter-perf-rendering-effects<br/>blur · opacity · clips · shadows"]
    S --> V["📈 flutter-perf-profiling-and-validation<br/>measure · verify · regression"]

Several concerns usually apply. The router handles them in this order of expected payoff: derived state and rebuild scope → lists → isolates → images → effects.

📦 Install

Tip

Install flutter-performance-specialist plus every flutter-perf-* skill; the router links to its siblings by relative path.

Claude Code plugin (installs the skills and agent profiles together):

/plugin marketplace add KinwiseNZ-DevOps/flutter-optimiser
/plugin install flutter-optimiser@flutter-optimiser-marketplace

ChatGPT desktop plugin (local, skills and bundled hooks):

This repo has a portable plugin.json manifest and a repo marketplace at .agents/plugins/marketplace.json. Open this repo as a trusted project and restart ChatGPT desktop, then install Flutter Optimiser from the Plugins Directory. Review and trust bundled hook scripts before they run.

Or copy or symlink the skills/ subfolders you want into your agent's skills directory:

To install supplied Claude Code, GitHub Copilot or Codex profiles into a project, run python scripts/install_agents.py --host claude-code --target PATH. Other compatible hosts receive the skills only. Each supported host has one main flutter-performance-specialist-workflow profile and one optional flutter-performance-specialist-implementation-planner helper.

Always on

In Claude Code, Flutter Optimiser loads a short ruleset into every session as soon as the plugin is installed (measure before changing, behaviour preserved, no blanket rewrites). It tells you its state at the start of each session and costs roughly 450 tokens.

• Say "stop optimiser mode" to pause it for the current session, and "start optimiser mode" to resume.
• Ask Claude to set the saved mode to on, off or auto. It writes that word into ~/.claude/.flutter-optimiser.mode. You can also edit that file yourself, and deleting it returns to the default (auto).
• It needs Node on the machine, because the start-up hook runs a small Node script. Without Node the hook quietly does nothing.
• Other agents have no start-up hook here. Paste skills/flutter-performance-specialist/references/always-on-rules.md into that agent's instruction file instead.

Safety checks

The same hooks run a few checks while you work. Each one only asks, warns or adds a reminder; none changes your files on its own.

Switch any check with ~/.claude/.flutter-optimiser.features.json, for example {"packageGuard": false, "sessionLog": true}, or ask Claude to write it. The saved mode (on, off or auto) applies to every check. If several of these plugins are installed, each risky action is checked once, not once per plugin.

Privacy: packageGuard and licenseGuard send package names, and linkGuard sends the links it checks, to the public registry or site. Nothing else leaves your machine. Turn those checks off if that is a concern.

🚀 Usage

Tip

You never need to memorise skill names. Just describe the problem in plain words; the router picks the right skill automatically. But if you want short, reliable phrases that always work, use these:

The 3-step flow (this is all most people need):

1. "audit my flutter app"        → read-only investigation + plan
2. "go ahead with the plan"      → one change at a time, routed to the right skill
3. "verify it on my device"      → profile-mode measurement + final report

Short phrases that trigger each skill:

Note

Skills also trigger on their own when your request matches (e.g. pasting a janky ListView(children: …) snippet is enough). In Claude Code you can also invoke explicitly with /flutter-performance-specialist, but the plain phrases above are shorter and work across every agent.

✅ Validate

python scripts/skills_tool.py check

Checks: frontmatter, name/folder match, description length and trigger, body under 500 lines, every relative link resolves (including README.md and AGENTS.md), agent profile naming with no more than two profiles per host and exactly one -workflow main agent, at least 3 eval cases per skill, catalogue freshness, no project-specific terms from reference-content/strip-terms.txt, and no em or en dashes in file names or in any text outside reference-content/. After the starter skill is deleted it also rejects leftover placeholders and setup-only paths that are tracked by Git or not ignored. Stdlib only, no dependencies.

🗂️ Layout

Repository layout

skills/<name>/SKILL.md      one folder per skill (+ references/ where needed)
resources/agents/           optional native profile sources
scripts/install_agents.py   install supplied profiles into a project
evals/cases.jsonl           3+ behavioural cases per skill
evals/triggers.jsonl        triggering tests per skill: obvious, paraphrase, unrelated
scripts/skills_tool.py      validate, regenerate catalogue (stdlib only)
AGENTS.md                   agent-facing repo map

📌 Status and limits

Note

• Evals in evals/cases.jsonl are case definitions with expected behaviours; no runner or baseline results exist yet.
• Skills are based on Flutter's official docs and have not yet been tested against a live codebase.
• Licensed under MIT (see LICENSE).

⚡ Built on the Agent Skills open format · grounded in Flutter's official performance docs