compose-kotlin-agent-skills

Make your AI coding agent actually understand Jetpack Compose & Kotlin — on Android, Kotlin Multiplatform, and Compose Multiplatform.
Strict MVI · Kotlin 2.x K2 · Compose 2026 · CI-validated · 27 agents supported.

Quick install

Per-agent details → Setup · All 27 agents → agents/README.md

The problem

AI coding agents generate Kotlin/Compose code that compiles but gets the details wrong:

• _state.value = … instead of atomic _state.update { } — race conditions
• collectAsState() instead of collectAsStateWithLifecycle() — battery drain
• Hardcoded UI strings instead of stringResource(R.string.…) — broken localisation
• LazyColumn without key + contentType — broken scroll, recomposition storms
• GlobalScope.launch { } inside ViewModels — leaks
• mutableStateListOf in ViewModel — survives config change wrong

This skill kit fixes that by giving your AI agent:

1. A primary SKILL.md with the 2026 toolchain, strict MVI guardrails, and a dedicated banned-antipatterns reference.
2. 3 modular sub-skills (architecture, Compose, testing) loaded on demand — Compose sub-skill includes REVIEW MODE for screen audits.
3. 20 reference modules (00–19) covering every major Android/Kotlin topic.
4. 27 per-agent install guides so Cursor, Claude Code, Codex, Copilot, Gemini, etc. each load it correctly.
5. CI-validated — every SKILL.md is frontmatter-linted, link-checked, and registered in api/skills.lock on every push.

What this is NOT

TL;DR: clone this repo into your agent's skills folder. The agent reads it before writing Kotlin. That's it.

What changes when you install it

Platforms

Skill catalog

Full routing index → AGENTS.md

What's covered

Review mode

Ask your agent to audit a Composable or screen — triggers the 6-point checklist in skills/android-kotlin-compose/SKILL.md:

"Review TodoScreen.kt in REVIEW MODE" · "Audit this composable for banned antipatterns"

Cross-reference hits against references/00-banned-antipatterns.md. Example target: examples/todo-mvi/TodoScreen.kt.

How it works

You ask about Kotlin / Compose
        |
        v
  AI reads SKILL.md (routing + guardrails + banned antipatterns)
        |
        v
  Loads the right sub-skill
        |
        +-- skills/android-kotlin-architecture/SKILL.md
        +-- skills/android-kotlin-compose/SKILL.md
        +-- skills/android-kotlin-testing/SKILL.md
        |
        v
  Pulls topic reference
        |
        +-- references/00-banned-antipatterns.md
        +-- references/01-architecture.md
        +-- references/02-compose-ui.md
        +-- ... 20 references total (00–19)
        |
        v
  Writes code that follows the guardrails

Layer 1: root skill (SKILL.md) — single source of truth for toolchain versions, mandatory defaults, and banned antipatterns.

Layer 2: sub-skills (3 files) — focused playbooks loaded only when the task matches the domain.

Layer 3: references (20 files, 00–19) — deep dives with WRONG/RIGHT pairs, decision matrices, pinned versions.

Layer 4: validator (scripts/validate_skills.py) — CI enforces frontmatter, link integrity, and skill-registry parity.

File structure

compose-kotlin-agent-skills/
├── SKILL.md                              # Routing hub + MVI guardrails + banned antipatterns
├── AGENTS.md                             # agentskills.io meta-discovery index
├── CHANGELOG.md                          # Keep a Changelog · semver
├── ROADMAP.md                            # Planned milestones
├── api/
│   └── skills.lock                       # CI-tracked registry of every SKILL.md (md5)
├── skills/
│   ├── android-kotlin-architecture/SKILL.md
│   ├── android-kotlin-compose/SKILL.md
│   └── android-kotlin-testing/SKILL.md
├── references/                           # 20 topic deep-dives (00–19)
├── agents/                               # 27 per-agent install guides + index
├── examples/
│   ├── todo-mvi/                         # MVI todo list reference (VM + Screen + Repository)
│   ├── animated-clock/
│   └── authenticator/
├── assets/
│   └── logo.png
├── scripts/
│   ├── validate_skills.py                # Frontmatter + link + lock validator (JUnit XML capable)
│   └── update_lock.sh                    # Regenerate api/skills.lock after editing any SKILL.md
└── .github/
    ├── workflows/skill-lint.yml          # CI: validator + JUnit report
    ├── pull_request_template.md
    └── ISSUE_TEMPLATE/                   # bug, feature, new-agent

Setup {#setup}

The skill is just markdown. Every agent below reads the same content — pick yours.

Cursor

git clone https://github.com/haidrrrry/compose-kotlin-agent-skills.git \
  .cursor/skills/compose-kotlin-agent-skills

Cursor auto-discovers .cursor/skills/*/SKILL.md. For a rules-file alternative see agents/cursor.md.

Claude Code

# Personal — available in all your projects
git clone https://github.com/haidrrrry/compose-kotlin-agent-skills.git \
  ~/.claude/skills/compose-kotlin-agent-skills

# Project-specific
git clone https://github.com/haidrrrry/compose-kotlin-agent-skills.git \
  .claude/skills/compose-kotlin-agent-skills

Add a 5-line block to your project's CLAUDE.md — see agents/claude.md.

Codex CLI (OpenAI)

git clone https://github.com/haidrrrry/compose-kotlin-agent-skills.git

Then add a reference block to your project's root AGENTS.md — see agents/codex.md.

Gemini CLI

git clone https://github.com/haidrrrry/compose-kotlin-agent-skills.git

Then add a reference block to GEMINI.md — see agents/gemini.md.

GitHub Copilot

Clone into .github/skills/compose-kotlin-agent-skills/ and add a block to .github/copilot-instructions.md — see agents/copilot.md.

Other agents (22 more)

Windsurf · Kimi · DeepSeek · Cline · Aider · Continue.dev · OpenCode · Zed · Amazon Q · JetBrains AI / Junie · Sourcegraph Cody · Replit Agent · Augment · Roo Code · Goose · OpenHands · Qwen Code · Trae · Tabnine · Factory Droid · Devin · Bolt.new

Full table → agents/README.md
Paste-anywhere snippet → agents/_shared-snippet.md

Quick example

After setup, talk to your AI agent normally:

"My LazyColumn jank — fix it."

Or run REVIEW MODE against the bundled example:

"Review examples/todo-mvi/TodoScreen.kt in REVIEW MODE"

See examples/todo-mvi/README.md for the MVI patterns it demonstrates.

What happens:

1. Agent reads SKILL.md for the routing rules.
2. Loads skills/android-kotlin-compose/SKILL.md and references/10-performance.md.
3. Checks your code for missing key / contentType, unstable items, heavy work in item blocks.
4. Returns a fix that follows the guardrails — key = { it.id }, @Immutable data class, derivedStateOf where appropriate.

No hallucinated APIs. No GlobalScope. No _state.value = ….

Validate locally

python3 scripts/validate_skills.py --strict --lock-check api/skills.lock

CI runs the same command on every push and pull request. If you edit any SKILL.md:

./scripts/update_lock.sh

Then commit api/skills.lock alongside your change.

FAQ

Best Kotlin / Compose skill for Cursor?

Clone this repo into .cursor/skills/compose-kotlin-agent-skills and point Cursor rules at SKILL.md. Covers Compose, MVI, Hilt, Room, Navigation 3, and the banned-antipatterns table.

How do I add Kotlin rules to Claude Code?

git clone https://github.com/haidrrrry/compose-kotlin-agent-skills.git ~/.claude/skills/compose-kotlin-agent-skills

Claude auto-discovers SKILL.md in the skills folder.

MVVM vs MVI — which does this enforce?

MVI with atomic StateFlow updates. UiState + UiEvent + UiEffect. Naked state assignment (_state.value = ...) is explicitly banned.

Kotlin Multiplatform / Compose Multiplatform?

See references/08-kmp-cmp.md — shared ViewModel, expect/actual, Ktor networking, SQLDelight vs Room.

Is this a Compose UI library or an Alexa skill?

No. It's markdown instructions for coding AIs — clone with git, not implementation(...). The word "skill" follows the agentskills.io format, unrelated to voice assistants.

Contributing

PRs welcome — see .github/pull_request_template.md.

Every new sub-skill must:

1. Live under skills/<kebab-case-name>/SKILL.md with valid frontmatter.
2. Pass python3 scripts/validate_skills.py --strict.
3. Be registered in AGENTS.md.
4. Bump api/skills.lock via ./scripts/update_lock.sh.

License

MIT — see LICENSE.

Author: haidrrrry