Kotlin KMP Agent Skills

A public catalog of AI agent skills for Kotlin Multiplatform projects.

These skills are intentionally opinionated and grounded in official Android, Kotlin Multiplatform, and Gradle guidance. Built for reusable public use — not for one private codebase.

Skills

🏗️ Architecture & Implementation

| Skill | What it does | |---|---| | kotlin-project-architecture-review | Reviews KMP architecture, PRs, and layer boundaries. Produces a verdict, issue list, and concrete recommendations. | | kotlin-project-feature-implementation | Guides feature implementation with a pre-coding checklist, layer-by-layer rules, and state pipeline design. Forward-looking only — not a review skill. | | kotlin-project-modularization | Reviews or designs module boundaries, dependency direction, visibility control, and granularity. | | kotlin-project-state-management | Covers state-holder pattern selection across KMP targets — ViewModel, shared presenter, MVI — including effect handling and UiState modeling. |

🎨 UI & Navigation

| Skill | What it does | |---|---| | kotlin-ui-compose-multiplatform | Reviews shared Compose UI — state-driven architecture, composable decomposition, layout/modifier discipline, and previewability. | | kotlin-ui-adaptive-resources | Reviews adaptive UI strategy — window-size classes, canonical layouts, navigation adaptation, and multi-window support. | | kotlin-navigation-compose-multiplatform | Reviews Compose Multiplatform navigation — route modeling, back stack ownership, NavOptions, deep links, and browser URL binding. |

🔌 Platform Boundaries

| Skill | What it does | |---|---| | kotlin-platform-kmp-bridges | Reviews platform-specific integrations — source-set placement, hierarchical sharing, expect/actual usage, and entry-point wiring. | | kotlin-platform-app-links-and-deep-links | Reviews Android App Links and deep links — intent-filter design, host verification, assetlinks.json, and manifest scope. |

🗄️ Data, Testing & Build

| Skill | What it does | |---|---| | kotlin-data-kmp-data-layer | Reviews KMP data layers — repositories, data sources, source-of-truth design, conflict resolution, and error handling. | | kotlin-testing-kmp | Reviews test strategy — kotlin.test, unit tests, instrumented tests, Compose UI tests, test doubles, and screenshot testing. | | kotlin-build-kmp-gradle-governance | Reviews Gradle build structure — shared build logic, convention plugins, version catalogs, and source-set configuration. |

🐛 Bug Fix & Refactoring

| Skill | What it does | |---|---| | kotlin-project-bugfix | Guides root-cause analysis, minimal fix strategy, and regression prevention for KMP bugs. | | kotlin-kmp-refactor-safety | Reviews refactoring safety — behavioral preservation, test coverage, migration strategies, and rollback plans. |

Orchestration

Beyond individual skills, this repository includes a full agent pipeline for automated ticket execution, code review, and fixes. The orchestration system is designed to work with Claude Code and can be installed alongside the skills.

Agent Pipeline

Five specialized agents work together in a structured pipeline:

| Agent | Role | Definition | |-------|------|------------| | Planner | Analyzes tickets, inspects the codebase, and produces structured implementation plans | agents/planner.md | | Implementer | Executes approved plans by writing production-grade code that fits existing architecture | agents/implementer.md | | Validator | Verifies builds pass using an escalating strategy (metadata → Android → tests → detekt) | agents/validator.md | | Reviewer | Performs strict code review across 10 dimensions (architecture, coroutines, KMP, security, etc.) | agents/reviewer.md | | Fixer | Applies minimal, targeted fixes for blockers and major issues found by the reviewer | agents/fixer.md |

9-Phase Execution Pipeline

The execute-ticket command orchestrates a full ticket lifecycle:

Phase 1: BRANCH       → Create feature branch from ticket ID
Phase 2: PLAN         → Planner agent analyzes ticket + codebase, produces plan
                        ↳ User approval gate
Phase 3: IMPLEMENT    → Implementer agent executes the approved plan
Phase 4: VALIDATE     → Validator runs metadata → android → tests → detekt
Phase 5: REVIEW       → Reviewer performs 10-dimension code review
Phase 6: FIX          → Fixer resolves all blockers and major issues
Phase 7: RE-VALIDATE  → Validator re-runs after fixes (must be clean)
Phase 8: FINALIZE     → Stage, commit, push to remote
Phase 9: OUTPUT       → Generate PR-ready summary

Validation Hooks

Shell scripts in hooks/ provide standalone validation:

| Hook | Purpose | Usage | |------|---------|-------| | validate-compile.sh | Metadata compilation for a module | ./validate-compile.sh <filepath> | | validate-detekt.sh | Detekt code quality for a module | ./validate-detekt.sh <filepath> | | validate-tests.sh | Unit tests for a module | ./validate-tests.sh :module:path | | finalize-summary.sh | Git state summary for end-of-pipeline | ./finalize-summary.sh |

Permission Model

Two settings files control what Claude Code can do:

settings.json (base, conservative) — allows read operations, git read commands, gradlew tasks, and file inspection. Denies editing secrets/keystores/credentials and destructive git operations. Includes a PostToolUse hook that logs file modifications.

settings.local.json (extended, for local/CI) — adds full edit/write, git commit/push/rebase, GitHub CLI, ADB commands, and destructive operations.

GitHub Actions

Two workflow templates automate PR review and fixes:

claude-pr-review.yml — triggers on PR open/sync to main. Reviews the diff for architecture, KMP correctness, state management, Compose performance, coroutines, and missing tests. Skips Claude's own PRs and [skip-review] titles.

claude-pr-fix.yml — triggers on @claude fix comments in PRs. Reads the diff and all review feedback, applies minimal targeted fixes, commits and pushes. Never expands scope.

Install

Quick install (npx)

Run this from your KMP project root:

npx kotlin-kmp-agent-skills

The interactive installer lets you choose what to install:

1. Everything — skills + agents + commands + hooks + settings + GitHub workflows
2. Skills only — just the 14 KMP skill definitions
3. Orchestration only — agents + commands + hooks + settings (no workflows)
4. Pick individually — choose each component

Existing files are preserved by default (the installer asks before overwriting).

Manual install

Copy individual components as needed:

# Skills
cp -r skills/* .claude/skills/

# Agents + commands
cp -r agents .claude/agents
cp -r commands .claude/commands

# Hooks
cp -r hooks .claude/hooks

# Settings
cp settings.json .claude/settings.json
cp settings.local.json .claude/settings.local.json

# GitHub Actions
cp -r .github/workflows/* .github/workflows/

Post-install

• Add ANTHROPIC_API_KEY to your repository secrets if you installed the GitHub workflows.
• Edit the module-path patterns in hooks/validate-compile.sh and hooks/validate-detekt.sh to match your project's module structure.

The path .claude/ is the default for Claude Code. Adjust if your agent framework uses a different directory.

What these skills address

KMP projects tend to drift in predictable ways. This catalog focuses on where that drift happens most:

| Area | Common drift | |---|---| | Source sets | Platform code in commonMain; shared code that assumes one platform | | State ownership | Multiple writable sources of truth; effects modeled as persistent state | | Data layer | Repositories that only mirror endpoints; DTOs leaking into UI | | Navigation | NavController passed deep into composables; stringly-typed routes | | Platform bridges | expect/actual overused where interfaces would be simpler | | Deep links | Unverified App Links; assetlinks.json misconfigured on one of several hosts | | Adaptive UI | Phone layout stretched to tablet; no window-size-class strategy | | Testing | Business logic only tested through UI; kotlin.test absent from shared source sets | | Modularization | common/core modules as dumping grounds; cyclic dependencies | | Build | Repeated Gradle config; no convention plugins; platform deps in common source sets |

Design principles

These skills assume the following defaults unless a codebase has a strong reason to differ:

• Layered architecture — UI, domain (optional), data, platform
• Single source of truth — one clear owner per data type
• Unidirectional data flow — events up, state down
• Immutable UI state — exposed from state holders, rendered by UI
• Effect separation — one-time effects distinct from persistent UiState
• Repository boundaries — data sources hidden behind repositories
• Source-set discipline — shared code as high as valid, platform code at the edges
• Minimal expect/actual — used narrowly; interfaces preferred for complex abstractions
• Test pyramid — most confidence from lower-level tests, not UI/instrumented tests
• Centralized build governance — convention plugins, version catalogs, explicit repositories

Naming convention

All skills follow:

kotlin-<category>-<functional-name>

Available categories:

| Category | Purpose | |---|---| | project | Cross-cutting KMP project-level concerns (architecture, modularization, state management) | | ui | Compose UI, layout, adaptive behavior | | navigation | Navigation structure, routes, deep links | | data | Repositories, data sources, source-of-truth | | platform | Platform bridges, expect/actual, Android-specific platform concerns | | testing | Test strategy, test layers, test tooling | | build | Gradle structure, convention plugins, version catalogs | | architecture | Standalone architecture-pattern skills (rare) |

Scope

This repository is for public, reusable skills only.

Not included:

• Secrets or private infrastructure details
• Internal hostnames or proprietary workflows
• Project-specific assumptions presented as universal KMP defaults

Not assumed as universal baseline (can be layered on top in project-specific variants):

• A specific DI framework
• A specific database library
• A specific CI provider
• A fixed AGP / Gradle / Kotlin compatibility matrix
• Stack-specific ProGuard / R8 rules

Contributing

See CONTRIBUTING.md.

References

• Android Architecture
• Architecture Recommendations
• UI Layer
• Domain Layer
• Data Layer
• Application Fundamentals

• Guide to Android app modularization
• Common modularization patterns
• Gradle Convention Plugins
• Gradle Version Catalogs
• Android Kotlin Multiplatform Plugin

• Navigation Principles
• Navigate to a destination
• Navigate with options
• Pass data between destinations
• Animate transitions
• Conditional navigation
• Back stack
• About App Links
• Create deep links
• Add App Links
• Configure website associations

• Adaptive layouts in Compose
• Support different display sizes
• Window size classes
• Multi-window mode
• Build adaptive navigation
• Canonical layouts
• List-detail layout
• Supporting pane layout

• Testing fundamentals
• What to test
• Test doubles
• Testing strategies
• Local unit tests
• Robolectric
• Instrumented tests
• Screenshot testing

• KMP project structure
• KMP hierarchy
• Share code on similar platforms
• Expected and actual declarations
• Use platform-specific APIs
• Compose Multiplatform
• Compose adaptive layouts
• Compose previews
• Navigation in Compose Multiplatform
• Deep links in Compose navigation
• Navigation 3 (alpha)
• Compose Multiplatform testing
• KMP DSL reference

Apache-2.0 · Built for Claude and compatible AI coding agents