К основному содержанию
скилл CX Codex

bloc — скилл для Claude Code: что делает и как установить

Скилл для Claude Code: помогает создавать Cubit и Bloc, выбирать форму состояния и подключать bloc-виджеты к дереву. Помогает унифицировать state management в проекте.

MIT ★ 674 обновлён 2026-10-29

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rules
Открыть на GitHub

Что делает bloc

Скилл описывает работу с bloc и flutter_bloc во Flutter: как заводить Cubit и Bloc, как хранить состояние и как подключать их к дереву виджетов. Внутри — таблица выбора между Cubit и Bloc, конвенции имён для событий и состояний, два способа описать состояние и готовые скелеты классов.

Состояние моделируется либо sealed-классами с подклассами Initial/InProgress/Success/Failure, либо одним классом с enum статуса и copyWith. Первый вариант берут, когда состояния взаимоисключающие и хочется исчерпывающий switch; второй — когда полей много и их надо сохранить после ошибки. Скилл советует начинать с Cubit и переходить на Bloc только когда требований становится больше.

Архитектура разложена на три слоя: презентация, бизнес-логика, данные. Bloc не должен ходить в data provider напрямую, только через репозиторий, а связать два блока между собой можно через BlocListener в UI. Повторный emit с тем же состоянием bloc просто игнорирует, поэтому поля в props у Equatable должны реально меняться.

Какие задачи решает

  • завести Cubit для нового экрана и не тащить логику в виджеты
  • выбрать между sealed-классами и enum статуса при описании состояния
  • развести BlocBuilder и BlocListener по дереву виджетов
  • переписать существующий state management под конвенции bloc
  • написать юнит-тесты для Cubit или Bloc

Примеры запросов агенту

  • Сделай LoginCubit с состояниями initial, loading, success и failure, логин вызывай через _authRepository
  • Разбей LoginState на sealed-классы и обработай все случаи через switch в UI
  • Переименуй события ProfileBloc в прошедшее время и сделай обработчики приватными

Как установить bloc

1Через маркетплейс плагинов

/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rules

Команда ставит плагин flutter-ai-skills целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add evanca/flutter-ai-rules --skill bloc -a claude-code

3Вручную: положить файлы

~/.claude/skills/bloc/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/bloc/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о bloc

Как установить bloc в Claude Code?

Через маркетплейс плагинов: сначала /plugin marketplace add evanca/flutter-ai-rules, затем /plugin install flutter-ai-skills@flutter-ai-rules.

Что делает скилл bloc?

Задаёт правила проектирования, написания и тестирования state management на bloc и flutter_bloc: состояния, события, слои архитектуры, bloc-виджеты в дереве.

Чем Cubit отличается от Bloc по этому скиллу?

Cubit берут для простого состояния, где события не нужны. Bloc — для сложных потоков, когда важна трассировка событий или нужны трансформеры вроде debounce и throttle.

Исходный текст

SKILL.md · MIT
---
name: bloc
description: "Use when creating a Cubit or Bloc, modeling state with sealed classes or status enums, wiring BlocBuilder/BlocListener/BlocProvider, writing bloc tests, or choosing between Cubit and Bloc."
license: MIT
---

# Bloc Skill

Design, implement, and test state management using the [bloc](https://pub.dev/packages/bloc) and [flutter_bloc](https://pub.dev/packages/flutter_bloc) libraries.

## When to Use

Use this skill when:

* Creating a new Cubit or Bloc for a feature.
* Modeling state (choosing between sealed classes and a single state class with status enum).
* Wiring `BlocBuilder`, `BlocListener`, `BlocConsumer`, or `BlocProvider` in the widget tree.
* Writing unit tests for a Cubit or Bloc.
* Deciding between Cubit and Bloc.
* Refactoring existing state management to follow bloc conventions.

---

## 1. Cubit vs Bloc

| Situation | Use |
|---|---|
| Simple state, no events needed | `Cubit` |
| Complex flows, event traceability needed | `Bloc` |
| Advanced event processing (debounce, throttle) | `Bloc` with event transformers |

**Default to `Cubit`. Refactor to `Bloc` only when requirements grow.**

---

## 2. Naming Conventions

### Events (Bloc only)
- Named in **past tense**: `LoginButtonPressed`, `UserProfileLoaded`.
- Format: `BlocSubject` + optional noun + verb.
- Initial load event: `BlocSubjectStarted` (e.g., `AuthenticationStarted`).
- Base event class: `BlocSubjectEvent`.

### States
- Named as **nouns** (states are snapshots in time).
- Base state class: `BlocSubjectState`.
- Sealed subclasses: `BlocSubject` + `Initial` | `InProgress` | `Success` | `Failure`.
  - Example: `LoginInitial`, `LoginInProgress`, `LoginSuccess`, `LoginFailure`.
- Single-class approach: `BlocSubjectState` + `BlocSubjectStatus` enum (`initial`, `loading`, `success`, `failure`).

---

## 3. Modeling State

### When to use a sealed class with subclasses
- States are **well-defined and mutually exclusive**.
- Type-safe exhaustive `switch` is desired.
- Subclass-specific properties exist.

```dart
@immutable
sealed class LoginState extends Equatable {
  const LoginState();
}

final class LoginInitial extends LoginState {
  @override
  List<Object?> get props => [];
}

final class LoginInProgress extends LoginState {
  @override
  List<Object?> get props => [];
}

final class LoginSuccess extends LoginState {
  const LoginSuccess(this.user);
  final User user;
  @override
  List<Object?> get props => [user];
}

final class LoginFailure extends LoginState {
  const LoginFailure(this.message);
  final String message;
  @override
  List<Object?> get props => [message];
}
```

Handle all states exhaustively in the UI:
```dart
switch (state) {
  case LoginInitial():  ...
  case LoginInProgress(): ...
  case LoginSuccess(:final user): ...
  case LoginFailure(:final message): ...
}
```

### When to use a single class with a status enum
- Many shared properties across states.
- Simpler, more flexible; previous data must be retained after failure.

```dart
enum LoginStatus { initial, loading, success, failure }

@immutable
class LoginState extends Equatable {
  const LoginState({
    this.status = LoginStatus.initial,
    this.user,
    this.errorMessage,
  });

  final LoginStatus status;
  final User? user;
  final String? errorMessage;

  LoginState copyWith({
    LoginStatus? status,
    User? user,
    String? errorMessage,
  }) {
    return LoginState(
      status: status ?? this.status,
      user: user ?? this.user,
      errorMessage: errorMessage ?? this.errorMessage,
    );
  }

  @override
  List<Object?> get props => [status, user, errorMessage];
}
```

### State rules (both approaches)
- Extend `Equatable` and pass all relevant fields to `props`.
- Copy `List`/`Map` properties with `List.of`/`Map.of` inside `props`.
- Annotate with `@immutable`.
- Always emit a **new instance**; never reuse the same state object.
- Duplicate states are ignored by bloc — ensure meaningful state changes.

---

## 4. Cubit Implementation

```dart
class LoginCubit extends Cubit<LoginState> {
  LoginCubit(this._authRepository) : super(const LoginState());

  final AuthRepository _authRepository;

  Future<void> login(String email, String password) async {
    emit(state.copyWith(status: LoginStatus.loading));
    try {
      final user = await _authRepository.login(email, password);
      emit(state.copyWith(status: LoginStatus.success, user: user));
    } catch (e) {
      emit(state.copyWith(status: LoginStatus.failure, errorMessage: e.toString()));
    }
  }
}
```

Rules:
- Only call `emit` inside the Cubit/Bloc.
- Public methods return `void` or `Future<void>` only.
- Keep business logic out of UI.
- When overriding `storage` in a `HydratedCubit`, pass it as a named parameter: `super(initialState, storage: storage)`.

---

## 5. Bloc Implementation

```dart
sealed class LoginEvent {}
final class LoginSubmitted extends LoginEvent {
  LoginSubmitted({required this.email, required this.password});
  final String email;
  final String password;
}

class LoginBloc extends Bloc<LoginEvent, LoginState> {
  LoginBloc(this._authRepository) : super(LoginInitial()) {
    on<LoginSubmitted>(_onLoginSubmitted);
  }

  final AuthRepository _authRepository;

  Future<void> _onLoginSubmitted(
    LoginSubmitted event,
    Emitter<LoginState> emit,
  ) async {
    emit(LoginInProgress());
    try {
      final user = await _authRepository.login(event.email, event.password);
      emit(LoginSuccess(user));
    } catch (e) {
      emit(LoginFailure(e.toString()));
    }
  }
}
```

Rules:
- Trigger state changes via `bloc.add(Event())`, not custom public methods.
- Keep event handler methods private (`_onEventName`).
- Internal/repository events must be private and may use custom transformers.

---

## 6. Architecture

Three layers — each must stay in its own boundary:

```
Presentation  →  Business Logic (Cubit/Bloc)  →  Data (Repository → DataProvider)
```

- **Data Layer**: Repositories wrap data providers. Providers perform raw CRUD (HTTP, DB). Repositories expose clean domain objects.
- **Business Logic Layer**: Cubits/Blocs receive repository data and emit states. Inject repositories via constructor.
- **Presentation Layer**: Renders UI based on state. Handles user input by calling cubit methods or adding bloc events.

Rules:
- Blocs must not access data providers directly — only via repositories.
- No direct bloc-to-bloc communication. Use `BlocListener` in the UI to bridge blocs.
- For shared data, inject the same repository into multiple blocs.
- When a repository must expose its latest value synchronously (for example `currentUser`), write each update into a small injectable in-memory cache client and read from that cache, falling back to an empty value. Injecting the cache client keeps the repository testable.
- Initialize `BlocObserver` in `main.dart`.

---

## 7. Flutter Bloc Widgets

| Widget | Use |
|---|---|
| `BlocProvider` | Provide a bloc to a subtree |
| `MultiBlocProvider` | Provide multiple blocs without nesting |
| `BlocBuilder` | Rebuild UI on state change |
| `BlocListener` | Side effects only (navigation, dialogs, snackbars) |
| `MultiBlocListener` | Listen to multiple blocs without nesting |
| `BlocConsumer` | Rebuild UI + side effects together |
| `BlocSelector` | Rebuild only when a selected slice of state changes |
| `RepositoryProvider` | Provide a repository to the widget tree |
| `MultiRepositoryProvider` | Provide multiple repositories without nesting |

```dart
BlocProvider(
  create: (context) => LoginCubit(context.read<AuthRepository>()),
  child: LoginView(),
);

BlocBuilder<LoginCubit, LoginState>(
  builder: (context, state) {
    return switch (state.status) {
      LoginStatus.loading => const CircularProgressIndicator(),
      LoginStatus.success => const HomeView(),
      LoginStatus.failure => Text(state.errorMessage ?? 'Error'),
      LoginStatus.initial => const LoginForm(),
    };
  },
);

BlocListener<LoginCubit, LoginState>(
  listener: (context, state) {
    if (state.status == LoginStatus.failure) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text(state.errorMessage ?? 'Login failed')),
      );
    }
  },
  child: LoginForm(),
);
```

Rules:
- Use `context.read<T>()` in callbacks (not in `build`).
- Use `context.watch<T>()` in `build` only when necessary; prefer `BlocBuilder`.
- Never call `context.watch` or `context.select` at the root of `build` — scope with `Builder`.
- Handle **all** possible states in the UI (initial, loading, success, failure).

---

## 8. Testing

Use `bloc_test` package. Mock repositories with `mocktail`.

```dart
import 'package:bloc_test/bloc_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:test/test.dart';

class MockAuthRepository extends Mock implements AuthRepository {}

void main() {
  group('LoginCubit', () {
    late AuthRepository authRepository;
    late LoginCubit loginCubit;

    setUp(() {
      authRepository = MockAuthRepository();
      loginCubit = LoginCubit(authRepository);
    });

    tearDown(() => loginCubit.close());

    test('initial state should be LoginState with status initial', () {
      expect(loginCubit.state, const LoginState());
    });

    blocTest<LoginCubit, LoginState>(
      'should emit [loading, success] when login succeeds',
      build: () {
        when(() => authRepository.login(any(), any()))
            .thenAnswer((_) async => fakeUser);
        return loginCubit;
      },
      act: (cubit) => cubit.login('[email protected]', 'password'),
      expect: () => [
        const LoginState(status: LoginStatus.loading),
        LoginState(status: LoginStatus.success, user: fakeUser),
      ],
    );

    blocTest<LoginCubit, LoginState>(
      'should emit [loading, failure] when login throws',
      build: () {
        when(() => authRepository.login(any(), any()))
            .thenThrow(Exception('error'));
        return loginCubit;
      },
      act: (cubit) => cubit.login('[email protected]', 'wrong'),
      expect: () => [
        const LoginState(status: LoginStatus.loading),
        isA<LoginState>().having((s) => s.status, 'status', LoginStatus.failure),
      ],
    );
  });
}
```

Rules:
- Always call `tearDown(() => cubit.close())`.
- Use `blocTest` for state emission assertions.
- Use `group()` named after the class under test.
- Name test cases with "should" to describe expected behavior.
- Register fallback values for custom types: `registerFallbackValue(MyEvent())`.

---

## 9. Common Pitfalls

| Pitfall | Fix |
|---|---|
| Emitting the same state instance twice | Always create a new state object; bloc ignores duplicate emissions via `==`. |
| Calling `context.watch` inside callbacks | Use `context.read` in callbacks; `watch` is only valid inside `build`. |
| Forgetting `Equatable` props | Add every field to `props`; missing fields cause silent state update bugs. |
| Mutable state fields | Keep state `@immutable`; use `copyWith` or new sealed subclass instances. |
| Business logic in widgets | Move all logic into the Cubit/Bloc; widgets only dispatch events or call methods. |

```dart
// BAD — mutating state in-place
state.items.add(newItem);
emit(state);

// GOOD — emit a new state with copied list
emit(state.copyWith(items: [...state.items, newItem]));
```

---

## References

- [Bloc GitHub Repository](https://github.com/felangel/bloc)

© Ivanna Kaceviča · MIT · evanca/flutter-ai-rules

Похожие скиллы

Все скиллы по теме «Мобильная разработка» →
flutter-expert https://github.com/Jeffallan Скилл flutter-expert для разработки кросс-платформных приложений на Flutter 3+ и Dart. Помогает с виджетами, управлением состоянием через Riverpod или Bloc, маршрутизацией GoRouter и оптимизацией производительности. CX Codex +1 14 900установок dart-flutter-patterns affaan-m Скилл dart-flutter-patterns для Claude Code и Codex: готовые паттерны Dart и Flutter — null safety, состояние, навигация, сеть. Ускоряет написание и ревью кода на Flutter. CX Codex +1 6 400установок flutter-dev MiniMax-AI Скилл flutter-dev для Claude Code помогает создавать Flutter-приложения и настраивать управление состоянием, навигацию и тесты. Он подключается к задачам с виджетами, адаптивной вёрсткой и производительностью. CX Codex +1 2 000установок flutter Mindrally Задаёт правила разработки на Flutter и Dart: чистую архитектуру по фичам, управление состоянием через Riverpod или BLoC и ограничения на вложенность виджетов. CX Codex +1 975установок flutter-development aj-geddes Скилл flutter-development для разработки мобильных приложений на Flutter и Dart: виджеты, состояние через Provider или BLoC, навигация, интеграция с API. CX Codex +1 727установок flutter-app-expert-cursorrules-prompt-file PatrickJS Правило flutter-app-expert-cursorrules-prompt-file настраивает Cursor на разработку мобильных приложений на Flutter 3.x с чистой архитектурой, BLoC и Material 3. Помогает держать единообразную структуру фич и тестов. CX Codex +1 ★ 41 178звёзд репо

Из того же набора39

Весь набор →
accessibility Скилл accessibility разбирает задачу по чек-листу WCAG — клавиатура, скринридер, контраст, формы — и находит конкретные нарушения доступности. Включается по словам a11y, ARIA, alt text, focus order, contrast. CX Codex +1 ★ 674звёзд репо firebase-cloud-firestore Скилл firebase-cloud-firestore учит агента настраивать Cloud Firestore во Flutter-проекте: схему данных, запросы, листенеры и правила безопасности. CX Codex +1 ★ 674звёзд репо generate-images-with-firebase-ai Скилл generate-images-with-firebase-ai помогает настроить генерацию картинок через Firebase AI Logic и Gemini в Flutter, избегая ошибок квот, сбоев App Check и пустых ответов. CX Codex +1 ★ 674звёзд репо code-review Скилл code-review проверяет изменения в Flutter/Dart-проекте по чек-листу: от логики и тестов до безопасности и стиля. Пригодится перед слиянием PR или MR. CX Codex +1 ★ 674звёзд репо firebase-auth Скилл firebase-auth настраивает авторизацию Firebase в приложениях на Flutter. Помогает подключить почту, социальные сети, эмулятор и корректно отслеживать сессии пользователей. CX Codex +1 ★ 674звёзд репо firebase-messaging Скилл firebase-messaging для Claude Code настраивает Firebase Cloud Messaging в Flutter: разрешения, токены и обработку push-уведомлений в фоне и открытом приложении. CX Codex +1 ★ 674звёзд репо flutter-pre-caching Скилл flutter-pre-caching подсказывает, как заранее загрузить шрифты, картинки и анимации во Flutter, чтобы убрать мигание и задержку первого рендера. CX Codex +1 ★ 674звёзд репо flutter-ai-skills Плагин flutter-ai-skills для Claude Code и Codex содержит 36 скиллов по Flutter, Dart и Firebase на основе официальной документации. Агент загружает их при работе с соответствующим кодом. CX Codex ★ 674звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой