AGENTS.md — compose-kotlin-agent-skills

Enterprise Android/Kotlin agent skill kit. Plain-text index for agentic IDEs (Cursor, Claude Code, Codex, Gemini, Copilot, Windsurf, OpenHands, and 20+ others).

Repository: https://github.com/haidrrrry/compose-kotlin-agent-skills
Primary skill: SKILL.md — read this first for every Kotlin/Android task.

Platforms: Android · Kotlin Multiplatform · Compose Multiplatform (target) · macOS / Linux / Windows (host) · 27 agents.

Build & Validation

# Validate all SKILL.md files (frontmatter + links) — must pass before merge
python3 scripts/validate_skills.py

# Strict mode + lock parity + JUnit report (matches CI exactly)
python3 scripts/validate_skills.py \
  --strict \
  --lock-check api/skills.lock \
  --junit junit-results.xml

# When you add or remove a SKILL.md, regenerate the lock file:
python3 scripts/validate_skills.py --write-lock api/skills.lock

CI runs the same script on every push and pull request (.github/workflows/skill-lint.yml) and uploads junit-results.xml as an artifact.

Skill Catalog

Skill	Path	Load When
compose-kotlin-agent-skills (primary)	SKILL.md	Any Android/Kotlin/Compose work — toolchain, MVI guardrails, banned antipatterns
android-kotlin-architecture	skills/android-kotlin-architecture/SKILL.md	Clean Architecture, MVVM/MVI, modules, UseCases, UiState/Event/Effect
android-kotlin-compose	skills/android-kotlin-compose/SKILL.md	Compose UI, recomposition, Material 3, edge-to-edge, animations, performance
android-kotlin-testing	skills/android-kotlin-testing/SKILL.md	ViewModel tests, Compose UI tests, Hilt fakes, Turbine, CI quality gates

Reference Modules (deep dives)

Load from references/ after reading the matching skill above. One level deep only — do not chain reference-to-reference.

Architecture & Platform

Reference	Topic
references/00-banned-antipatterns.md	Master banned table — WRONG/RIGHT lookup
references/01-architecture.md	Clean Arch, MVVM, MVI, module structure
references/04-coroutines-flow.md	StateFlow, structured concurrency, errors
references/05-hilt-di.md	Hilt, scopes, EntryPoint, testing
references/06-room-db.md	Room, migrations, offline-first
references/07-navigation.md	Navigation 3, type-safe routes, deep links
references/08-kmp-cmp.md	KMP, expect/actual, shared ViewModel
references/09-networking.md	Ktor, JWT, DTO mappers
references/14-datastore.md	DataStore, SharedPreferences migration
references/15-paging3.md	Paging 3, RemoteMediator, asState()
references/18-gradle-build-logic.md	Convention plugins, KSP, R8, baseline profiles
references/19-xml-to-compose-migration.md	XML → Compose, RxJava → Flow

Compose & Performance

Reference	Topic
references/02-compose-ui.md	Composition, stability, Modifier order, theming
references/03-animations.md	Springs, Canvas, gestures, shared elements
references/10-performance.md	Recomposition, LazyColumn, baseline profiles
references/16-coil-image.md	Coil 3.4, AsyncImage, cache
references/17-accessibility.md	TalkBack, semantics, WCAG

Quality & Ship

Reference	Topic
references/11-testing.md	Turbine, Compose tests, Hilt TestInstallIn
references/12-camera-mlkit.md	CameraX, ML Kit pose, angle math
references/13-release-checklist.md	Signing, R8, Play Store

Agent Install Guides (27 platforms)

Directory: agents/ · Index: agents/README.md · Paste snippet: agents/_shared-snippet.md

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

Replace <agent-dir> per agent (.cursor, .claude, .codex, .windsurf, etc.) — see the matching file in agents/.

Production Code Examples

Example	Source
examples/todo-mvi/	MVI todo list — ViewModel, Screen, Repository (antipattern-safe reference)
examples/animated-clock/	AnimatedClockJetpacl — Canvas, CMP, particles
examples/authenticator/	Authenticator — Room, MVVM, Koin, theming

What This Repository Is

Agent skill kit = markdown instructions for coding AIs (Cursor, Claude Code, Codex, etc.) — not an Android library, not Alexa/Bixby, not an on-device LLM SDK.

Install: git clone into .cursor/skills/compose-kotlin-agent-skills or .claude/skills/compose-kotlin-agent-skills.

Not the same as Compose UI libraries (coachmark / onboarding / theming Composables you add via Gradle). Those ship UI in your app. This repo teaches your coding agent how to write Kotlin/Compose correctly.

Boundaries — Do Not

• Confuse this repo with a Gradle dependency, voice-assistant skill, or Compose UI library
• Invent dependency versions — use the version table in SKILL.md
• Use GlobalScope, naked _state.value =, or hardcoded UI strings
• Skip LazyColumn keys or use collectAsState() on Android screens
• Merge without passing python3 scripts/validate_skills.py --strict --lock-check api/skills.lock
• Add reference files without linking them from SKILL.md or this index
• Add a new SKILL.md without bumping api/skills.lock and the catalog table above

Verification Prompt

Read AGENTS.md and SKILL.md. Structure a Navigation 3 screen with MVI UiState,
edge-to-edge insets, and collectAsStateWithLifecycle. Cite banned antipatterns you avoided.

Expected: Kotlin 2.x, AGP 9, _state.update { }, stringResource, NavKey routes, no GlobalScope.