Skip to main content

The utopia-hooks skill for AI Flutter development

A general coding agent writes utopia_hooks the way it writes anything else: by averaging its training data. It reaches for the pattern that was most common in its corpus, which is rarely the pattern this library intends. The AI-friendly page makes the case from the library's side, that hooks are easy for an agent to read and write. This page is the other half of that case, from the agent's side: the utopia-hooks skill is what tells the agent how the library is actually meant to be used, so it stops guessing.

The skill is a Claude Code plugin. An agent loads it as authoritative, project-correct reference, not as a suggestion it weighs against its prior. When the skill is installed and the work touches Flutter state, the agent reads the conventions before it writes, and writes to them.

What the skill encodes​

The skill is not a one-page cheat sheet. It is a priority-ordered set of reference files, each rated by impact (CRITICAL, HIGH, MEDIUM), so the agent reads the load-bearing ones first and drills into the rest by topic on demand.

At the top sit the conventions an agent gets wrong most often:

  • Screen / State / View. Every screen is the same three pieces: a State class that holds the data, a hook that builds it, and a View that renders it. The skill states the split as a rule, with the lightweight tier for trivial dialogs and the promotion trigger for when they grow.
  • The full hook catalog. useState, useMemoized, useEffect, useProvided, useInjected, the computed-state hooks, the wrappers - what each is for and which one to reach for, so the agent picks useAutoComputedState for a one-shot read and useMemoizedStream for a subscription rather than hand-rolling either.
  • The harder surfaces, by topic. Global state registration, app bootstrap and ordering, error handling, navigation conventions, multi-page shells, pagination, dependency injection, and unit-testing hook states with SimpleHookContext. Roughly fifteen reference files in total, each one a single topic the agent opens only when the task calls for it.

The reference files carry the worked examples; the agent reads the explanation in the same place it sees the code, so the two never drift in its context window.

The rules and the self-audit gate​

Reference material tells an agent what good looks like. It does not stop the agent from shipping something plausible but wrong. The skill closes that with two more layers.

First, a set of non-negotiable rules, stated flatly: the View never calls hooks and is always a StatelessWidget; the View constructor takes only state; the Screen is pure wiring and calls exactly one screen-state hook; navigation flows Screen to State to View as callbacks, never read from a provider inside a state hook; no manual loading state, always useAutoComputedState; no hand-rolled pagination, always usePaginatedComputedState; collections in State classes are always immutable. These are the same rules a human reviewer would raise in a pull request, written down so the agent applies them as it goes.

Second, a self-audit checklist the agent runs after it generates a screen. Each item is a one-line check that maps to a rule: does the View constructor take anything beyond state, does the Screen call any hook other than its screen-state hook, is there a useState<bool> standing in for a loading flag, is there a useState<List<T>> plus hasMore plus a cursor where a paginated hook belongs. The agent does not just write code and stop. It checks its own output against the same gate a reviewer would, and fixes what it finds before handing the work back.

Machine-checked through utopia_cli​

The rules in the skill are not only prose. The canonical analyzer for these conventions lives in utopia_cli, so the rules an agent follows are the same rules CI and pre-commit enforce. Guidance and validation come from one source and cannot drift apart.

In Claude Code, the plugin's PostToolUse hook runs utopia hooks analyze on every Dart edit the agent makes. A violation comes back as a structured finding, not a vague warning, so the agent can correct it immediately. That is what turns "looks idiomatic" into "passes the gate": the skill tells the agent the rule, the self-audit makes it check its own work, and the CLI confirms the result against the same engine the rest of the toolchain uses. For the full set of CLI surfaces the skill leans on - project inspection, screen scaffolding, repo-wide audits - see the utopia-skills ecosystem page.

What changes in the agent's output​

With the skill installed, the agent has a correct answer to reach for instead of reconstructing one from memory. Three things change in practice:

  • Idiomatic on the first try, more often. A new screen comes out as the Screen/State/View triad in the expected places, not as a scattering of setState calls or a monolithic HookWidget. Loading and pagination land as the right single hook rather than a hand-assembled bool plus try/catch/finally or a List plus hasMore plus a cursor.
  • Fewer hallucinations. When an agent does not know a library's conventions, it invents plausible ones. The skill removes the need to invent: the catalog, the rules, and the worked examples are right there, so the agent fills in a shape it has been shown rather than one it guessed.
  • Self-correction before review. The self-audit and the CLI gate catch the agent's own slips, so the first draft that reaches a human is already closer to mergeable, and review time goes to product decisions rather than convention nits.

Published and auditable​

The skill is open source, on the same marketplace as the rest of the tooling. That matters beyond convenience: a reviewer, a tech lead, or a CTO can read exactly how the agent is being guided before trusting a line of its output. The conventions are not buried in a vendor's private prompt. They are a published set of files anyone can read, the same files the agent reads, and the same skill a team keeps after any engagement ends. If you want to know how an agent will write utopia_hooks in your codebase, you read the skill.

Installation​

The skill runs its convention checks through the Utopia CLI, so activate the CLI first:

dart pub global activate utopia_cli

Then, in Claude Code, add the marketplace and install the skill:

/plugin marketplace add Utopia-USS/utopia-flutter-skills
/plugin install utopia-hooks@utopia-flutter-skills

The marketplace Utopia-USS/utopia-flutter-skills also carries the other Utopia plugins. The utopia-skills ecosystem page lists the full catalog.

See also​



Crafted for you by UtopiaSoftware 👾