MAD Agents Skills

Коллекция агентских навыков для AI-ассистентов, работающих с Dart и Flutter проектами, реализованная в формате Agent Skills - открытого стандарта для расширения возможностей AI-агентов.

Каждый навык содержит структурированные знания на основе официальной документации, готовые примеры кода и подробные справочные материалы, которые могут использовать AI-агенты.

📋 Содержание

• Обзор
• Навыки
  • Dart Drift
  • Flutter Adaptive UI
  • Flutter Animations
  • Flutter Architecture
  • Flutter Drift
  • Flutter Internationalization
  • Flutter Navigation
  • Flutter Networking
  • Flutter Testing
• Файловая структура
• Как использовать
• Матрица применения навыков
• Лицензия
• Вклад в проект
• Дополнительные ресурсы

🎯 Обзор

Этот репозиторий содержит набор специализированных навыков для разработки на Dart и Flutter, организованных в соответствии с открытым стандартом Agent Skills.

Что такое Agent Skills?

Agent Skills - это открытый формат для предоставления AI-агентам новых возможностей и экспертизы. Это структурированные папки с инструкциями, скриптами и ресурсами, которые агенты могут обнаруживать и использовать для выполнения задач более точно и эффективно.

Формат разработан: Anthropic
Статус: Открытый стандарт
Поддержка: Ведущие AI-инструменты разработки

Состав навыка

Каждый навык включает:

• SKILL.md - описание навыка с метаданными и условиями применения
• Справочную документацию - детальные руководства в папке references/
• Примеры кода - готовые шаблоны и примеры в папке assets/
• Лучшие практики - рекомендации по использованию
• Скрипты (опционально) - вспомогательные утилиты в папке scripts/

Возможности Agent Skills

✨ Domain expertise - специализированные знания в конкретных областях
🚀 New capabilities - новые возможности для агентов
🔄 Repeatable workflows - стандартизированные рабочие процессы
🔗 Interoperability - переиспользование между различными AI-инструментами

🛠️ Навыки

Dart Drift

Директория: dart-drift/

Описание: Полное руководство по использованию библиотеки drift для работы с базами данных в Dart приложениях (CLI, серверные приложения, не-Flutter desktop приложения).

Когда использовать:

• Разработка Dart приложений, требующих локальное хранилище SQLite
• Подключение к PostgreSQL с типобезопасными запросами
• Необходимость в реактивных потоках данных
• Реализация миграций схемы БД
• Создание серверных сервисов с connection pooling

Ключевые возможности:

• Настройка с sqlite3 или drift_postgres
• Определение таблиц и ограничений
• SELECT, WHERE, JOIN, агрегации
• INSERT, UPDATE, DELETE, транзакции
• Реактивные stream-запросы
• Миграции схемы базы данных

Справочные материалы:

• setup.md - Настройка SQLite и PostgreSQL
• postgres.md - PostgreSQL-специфичные функции
• tables.md - Определение таблиц
• queries.md - Запросы к БД
• writes.md - Операции записи
• streams.md - Реактивные потоки
• migrations.md - Миграции схемы

---

Flutter Adaptive UI

Директория: flutter-adaptive-ui/

Описание: Создание адаптивных и отзывчивых Flutter UI, которые отлично работают на всех платформах и размерах экранов.

Когда использовать:

• Создание приложений для множества платформ (mobile, tablet, desktop, web)
• Адаптация layouts под разные размеры экранов
• Поддержка различных устройств ввода (touch, mouse, keyboard)
• Реализация responsive navigation patterns
• Оптимизация для больших экранов и складных устройств
• Использование паттернов Capability и Policy для platform-specific поведения

Ключевые концепции:

• 3-шаговый подход: Abstract → Measure → Branch
• Breakpoints: Compact (<600), Medium (600-840), Expanded (≥840)
• Layout правило: Constraints go down. Sizes go up. Parent sets position.
• Capability/Policy паттерн для платформо-специфичного поведения

Справочные материалы:

• layout-constraints.md - Система constraints с 29 примерами
• layout-basics.md - Основные layout виджеты
• layout-common-widgets.md - Container, GridView, ListView, Stack
• adaptive-workflow.md - Детальный 3-шаговый подход
• adaptive-best-practices.md - Лучшие практики дизайна
• adaptive-capabilities.md - Паттерн Capability/Policy

Примеры:

• responsive_navigation.dart - Переключение NavigationBar ↔ NavigationRail
• capability_policy_example.dart - Примеры классов Capability/Policy

---

Flutter Animations

Директория: flutter-animations/

Описание: Комплексное руководство по реализации анимаций во Flutter.

Когда использовать:

• Добавление движения и визуальных эффектов в приложение
• Имплементация implicit animations (простые переходы)
• Создание explicit animations (полный контроль)
• Реализация hero animations (shared element transitions)
• Создание staggered animations (последовательные/перекрывающиеся)
• Использование physics-based animations

Типы анимаций:

Implicit Animations - для простых случаев:

• AnimatedContainer, AnimatedOpacity
• TweenAnimationBuilder
• Анимация триггерится изменением состояния

Explicit Animations - для полного контроля:

• AnimationController, Tween, CurvedAnimation
• AnimatedWidget, AnimatedBuilder
• Мониторинг состояния анимации
• Множественные одновременные анимации

Hero Animations - shared element transitions:

• Стандартные hero transitions
• Radial hero animations
• Навигация между экранами

Staggered Animations - последовательные эффекты:

• Interval-based timing
• Ripple effects
• Меню с последовательным появлением

Physics-Based - естественные движения:

• Spring simulations
• Fling animations
• Gravity-based анимации

Справочные материалы:

• implicit.md - Implicit анимации
• explicit.md - Explicit анимации с AnimationController
• hero.md - Hero transitions
• staggered.md - Staggered паттерны
• physics.md - Physics-based анимации
• curves.md - Справочник по Curves

Шаблоны:

• implicit_animation.dart
• explicit_animation.dart
• hero_transition.dart
• staggered_animation.dart

---

Flutter Architecture

Директория: flutter-architecture/

Описание: Комплексное руководство по архитектуре Flutter приложений с использованием MVVM паттерна и feature-first организации.

Когда использовать:

• Проектирование или рефакторинг архитектуры Flutter приложения
• Выбор между feature-first и layer-first структурой проекта
• Реализация MVVM паттерна во Flutter
• Создание масштабируемой структуры для команд
• Добавление новых функций к существующей архитектуре
• Применение лучших практик и паттернов проектирования

Организация проекта:

Feature-First (рекомендуется для команд):

• Организация по бизнес-функциям
• Средние и большие приложения (10+ функций)
• Командная разработка (2+ разработчика)
• Самодостаточные feature-модули

Layer-First (традиционный):

• Организация по архитектурным слоям
• Малые и средние приложения
• Соло-разработчики или малые команды
• Простая бизнес-логика

Архитектурные слои:

• UI Layer: Views (widgets) и ViewModels (UI логика)
• Data Layer: Repositories (SSOT) и Services (источники данных)
• Domain Layer: Use-cases для сложной бизнес-логики (опционально)

Паттерны проектирования:

• Command Pattern - инкапсуляция действий
• Result Type - типобезопасная обработка ошибок
• Repository Pattern - абстракция над источниками данных
• Offline-First - оптимистичные UI обновления

Справочные материалы:

• concepts.md - Основные принципы архитектуры
• feature-first.md - Feature-first организация
• mvvm.md - Реализация MVVM паттерна
• layers.md - Слои и их взаимодействие
• design-patterns.md - Общие паттерны

Примеры:

• command.dart - Шаблон Command паттерна
• result.dart - Result type для обработки ошибок
• examples/ - Примеры применения архитектуры

---

Flutter Drift

Директория: flutter-drift/

Описание: Полное руководство по использованию библиотеки drift для локального хранилища в Flutter приложениях.

Когда использовать:

• Создание Flutter приложений с локальной SQLite базой данных
• Необходимость типобезопасных запросов
• Реализация реактивных stream-запросов
• Миграции схемы базы данных
• Эффективные CRUD операции
• Кроссплатформенная поддержка (mobile, web, desktop)

Ключевые возможности:

• Настройка с drift_flutter пакетом
• Интеграция StreamBuilder для реактивного UI
• Паттерны Provider/Riverpod
• Platform-specific настройка (mobile, web)
• In-memory database для тестирования
• Миграции схемы с версионированием

Справочные материалы:

• setup.md - Flutter-специфичная настройка
• tables.md - Определение таблиц
• queries.md - SELECT запросы
• writes.md - INSERT, UPDATE, DELETE
• streams.md - Реактивные потоки
• migrations.md - Миграции БД
• flutter-ui.md - Интеграция с Flutter UI

---

Flutter Internationalization

Директория: flutter-internationalization/

Описание: Полное руководство по интернационализации Flutter приложений с использованием gen-l10n и intl пакетов.

Когда использовать:

• Добавление поддержки локализации в Flutter приложение
• Перевод UI текста на множество языков
• Форматирование чисел и дат для разных локалей
• Настройка мультиязычной поддержки для Material/Cupertino
• Реализация RTL (right-to-left) языков
• Управление ARB файлами и переводами

Подходы:

gen-l10n (рекомендуется):

• Современный, автоматизированный подход
• ARB файлы + кодогенерация
• Лучше для новых проектов и команд

intl package:

• Руч