Krow-workspace/.agents/skills

KROW Mobile Development Skills

This directory contains project-specific skills for AI agents working on the KROW mobile applications. These skills encode the development standards, architecture patterns, UI system usage, and release practices defined in the mobile documentation.

Overview

These skills help AI agents contribute effectively to mobile application development by providing:

• Clear guidelines on development standards and constraints
• Architecture patterns for Clean Architecture implementation
• Design system rules for consistent UI implementation
• Release procedures for version management and deployment

Available Skills

1. krow-mobile-development-rules

Purpose: Enforce development standards and prevent architectural degradation

Covers:

• File creation and package structure (feature-first packaging)
• Naming conventions (Dart standards)
• Logic placement boundaries (strict separation of concerns)
• Localization integration (core_localization package)
• Data Connect integration strategy
• Prototype migration rules
• Navigation with safe extensions
• Session management patterns
• Error handling requirements

Use When:

• Creating new mobile features or packages
• Implementing BLoCs, Use Cases, or Repositories
• Integrating with Firebase Data Connect backend
• Migrating code from prototypes
• Reviewing mobile code for compliance

Key Documentation:

• Source: docs/MOBILE/00-agent-development-rules.md

2. krow-mobile-architecture

Purpose: Maintain Clean Architecture across the mobile codebase

Covers:

• High-level architecture overview
• Package structure and responsibilities
• Dependency direction rules
• Feature isolation and communication
• Data Connect service and session management
• BLoC lifecycle and state emission safety
• Avoiding prop drilling patterns
• Data Connect connectors pattern overview

Use When:

• Architecting new mobile features
• Debugging state management or BLoC lifecycle issues
• Preventing prop drilling in UI code
• Managing session state and authentication
• Understanding package boundaries and dependencies
• Refactoring legacy code to Clean Architecture

Key Documentation:

• Source: docs/MOBILE/01-architecture-principles.md
• Related: docs/MOBILE/03-data-connect-connectors-pattern.md

3. krow-mobile-design-system

Purpose: Ensure visual consistency using immutable design tokens

Covers:

• Design system ownership and authority
• Colors usage rules (UiColors)
• Typography usage rules (UiTypography)
• Icons usage rules (UiIcons)
• Spacing and layout constants (UiConstants)
• Smart widgets usage
• Theme configuration
• POC → Production workflow
• Anti-patterns to avoid

Use When:

• Implementing any UI in mobile features
• Migrating POC/prototype designs to production
• Creating themed widgets or components
• Reviewing UI code for design system compliance
• Matching colors and typography from designs
• Adding icons, spacing, or layout elements

Key Documentation:

• Source: docs/MOBILE/02-design-system-usage.md

4. krow-mobile-release

Purpose: Manage mobile app releases, versioning, and hotfixes

Covers:

• Versioning strategy (semantic versioning with milestones)
• CHANGELOG management and format
• Git tagging strategy
• GitHub Actions workflows (product-release, hotfix)
• APK signing setup (24 GitHub Secrets)
• Release process (dev → stage → prod)
• Hotfix procedures
• Troubleshooting release issues

Use When:

• Preparing for mobile app releases
• Updating CHANGELOG files with new features
• Triggering GitHub Actions release workflows
• Creating hotfix branches for production issues
• Understanding version numbering
• Documenting release notes

Key Documentation:

• Source: docs/MOBILE/05-release-process.md
• Comprehensive: docs/RELEASE/mobile-releases.md (900+ lines)

Skill Organization

Each skill follows this structure:

.agents/skills/
├── krow-mobile-development-rules/
│   └── SKILL.md
├── krow-mobile-architecture/
│   └── SKILL.md
├── krow-mobile-design-system/
│   └── SKILL.md
└── krow-mobile-release/
    └── SKILL.md

Skill Descriptions

Each skill includes a description in its frontmatter that helps AI agents determine when to use it. These descriptions are designed to be "pushy" to ensure skills are triggered appropriately.

Using These Skills

For AI Agents

1. Skill triggering is automatic based on:

   • User task description matching skill description
   • Context keywords (mobile, flutter, feature, release, etc.)
   • Task type (implementation, architecture, UI, release)

2. Skills can be combined - multiple skills may be relevant:

   • Development rules + Architecture (implementing features)
   • Architecture + Design System (creating UI with proper structure)
   • Release + Development rules (preparing releases)

3. Reference documentation when needed:

   • Skills provide comprehensive guidance
   • Link to source documentation for deep dives
   • Include examples and anti-patterns

For Developers

These skills serve as:

• Quick reference for mobile development standards
• Onboarding material for new team members
• Code review checklist for ensuring compliance
• Architecture guide for feature implementation

Skill Maintenance

Updating Skills

When mobile documentation changes:

1. Review corresponding skill(s)
2. Update skill content to match new standards
3. Update examples and patterns
4. Keep descriptions current for proper triggering

Adding New Skills

Consider creating new skills for:

• New architectural patterns (e.g., state management approaches)
• New subsystems (e.g., analytics, crash reporting)
• Complex workflows spanning multiple skills
• Domain-specific patterns (e.g., payment processing)

Related Documentation

Mobile Documentation Structure

docs/MOBILE/
├── 00-agent-development-rules.md      → krow-mobile-development-rules
├── 01-architecture-principles.md      → krow-mobile-architecture
├── 02-design-system-usage.md          → krow-mobile-design-system
├── 03-data-connect-connectors-pattern.md (not in skills)
├── 04-use-case-completion-audit.md    (not in skills yet)
└── 05-release-process.md              → krow-mobile-release

docs/RELEASE/
└── mobile-releases.md                 → krow-mobile-release (comprehensive)

Enforcement

These skills encode NON-NEGOTIABLE standards. When AI agents:

• Create features → Must follow development rules
• Implement UI → Must use design system
• Prepare releases → Must follow release process
• Structure code → Must maintain Clean Architecture

Zero tolerance for violations ensures:

• Architectural integrity
• Visual consistency
• Code quality
• Maintainability
• Scalability

Questions or Issues?

If you encounter:

• Unclear guidelines - Refer to source documentation
• Conflicting patterns - Architecture document takes precedence
• Missing patterns - Document assumption and ask for clarification
• Technical debt - Follow skills for new code, refactor legacy gradually

Summary

These skills transform documentation into actionable, contextual guidance for AI agents working on KROW mobile applications. They ensure consistency, prevent architectural degradation, and accelerate development while maintaining quality standards.

Key Principles:

• Clean Architecture with strict boundaries
• Feature isolation via zero cross-feature imports
• Immutable design system
• Semantic versioning and structured releases
• Localization-first user interfaces

When in doubt, consult the skills or source documentation. Architecture is not negotiable.