How to use the Flutter Bloc/Cubit State Guide agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file. An agent runtime that loads SKILL.md files reads the instructions when a request matches the skill's description. This skill only changes the advice and code the agent writes. It does not run anything by itself.

The skill covers four things: choosing between Cubit and Bloc, setting up bloc and flutter_bloc correctly, following lifecycle and UI binding rules, and writing tests for both kinds of state holder.

• Cubit for simple, direct state updates such as counters, toggles, filters, form flags and theme mode.
• Bloc for event-driven flows with loading, success and failure transitions, such as auth, pagination, checkout, sync and multi-step workflows.
• Architecture rule: the repository or service owns I/O, the bloc or cubit owns state, and the UI only dispatches actions and renders state.
• Testing rule: test a Cubit by calling methods and asserting emitted states; test a Bloc by adding events and asserting the transition sequence.

How do you install the bloc-cubit skill?

Download the ZIP file from this page and unzip it. The skill is delivered as a single file, SKILL.md. You can install it in one of two places:

• For all your projects: unzip it into ~/.claude/skills/ so the bloc-cubit folder containing SKILL.md sits inside that directory.
• For one project: unzip it into your project's .claude/skills/ folder.
• In the Claude apps: go to Settings, then Capabilities, then Skills, and upload the skill there.

How do you trigger the skill with natural requests?

You do not need a special command. Describe the Flutter state work you are doing, and mention Bloc, Cubit, flutter_bloc or state management. The skill's description covers choosing Bloc vs Cubit, using bloc and flutter_bloc together, lifecycle, testing and safe defaults, so requests about those topics are the ones it is meant to match.

• Should this login flow be a Bloc or a Cubit?
• Set up state management for my settings screen with flutter_bloc.
• Add a BlocProvider for my cart feature and make sure it gets disposed correctly.
• Write bloc tests for my checkout events and their state transitions.
• Why is my widget rebuilding too often? Should I use buildWhen or BlocSelector?

What examples of good output should you expect?

The guide asks the agent to show the smallest working Bloc or Cubit first, explain why it chose Bloc or Cubit, and state whether the dependency should be bloc or flutter_bloc. If lifecycle is manual, the agent should also include cleanup and testing notes.

For a Dart-only package, the skill says to add bloc. For a Flutter UI, it says to add flutter_bloc and let it bring bloc in as a dependency, so you do not need to add both.

What does the skill need, and what about scripts and network?

The skill needs a Flutter or Dart project, because the guidance targets the bloc and flutter_bloc packages, and an agent runtime that loads SKILL.md files. It runs no scripts and uses no network. The file contains no code samples or version numbers to check against, so the agent is told to follow the current Flutter state management docs and the bloc package docs rather than the skill itself.

Because the skill runs nothing, the main safety point is to review the code the agent writes, especially lifecycle handling and any network calls, before you commit it.

• Runs scripts: no.
• Uses network: no.
• Licence: MIT.

What are the common mistakes the skill warns about?

The skill lists pitfalls it expects the agent to avoid. These are useful checks for you as well.

• Do not put network calls directly in widgets.
• Do not use Bloc for trivial local state.
• Do not add both bloc and flutter_bloc in a Flutter app when only flutter_bloc is needed.
• Do not forget close() on instances you create manually.
• Do not manually close instances owned by BlocProvider.
• Do not emit duplicate states unless the transition is meaningful.
• Do not let one bloc grow into an app-wide dumping ground.

Tips for getting the best results

State the feature and its complexity in your request, for example whether it has events, async loading or only simple toggles. That is the main input the Cubit vs Bloc decision depends on.

Check the agent's package versions and API calls against the official docs, since the skill does not contain a reference to verify against.

• Name the feature boundary, so the agent knows where to place BlocProvider.
• Ask for tests alongside the code, so the transition sequence is covered from the start.
• Mention if you already use another state library, so the agent does not mix patterns.