AGENTS.md — Agent Skills for Android

Skill-First Execution Model

When working on an Android project with agent skills installed, always check for a matching skill before implementing directly. Skills provide battle-tested workflows that prevent common mistakes.

Structured Lifecycle

Work follows a five-phase lifecycle. Each phase has dedicated skills:

DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP

Skill Directory Structure

Skills live in skills/{skill-name}/SKILL.md:

skills/
├── interview-me/SKILL.md
├── idea-refine/SKILL.md
├── spec-driven-development/SKILL.md
├── planning-and-task-breakdown/SKILL.md
├── android-architecture/SKILL.md
├── android-ui-engineering/SKILL.md
├── android-data-persistence/SKILL.md
├── android-background-work/SKILL.md
├── android-accessibility/SKILL.md
├── android-device-testing/SKILL.md
├── android-e2e-verification/SKILL.md
├── test-driven-development/SKILL.md
├── incremental-implementation/SKILL.md
├── code-review-and-quality/SKILL.md
├── debugging-and-error-recovery/SKILL.md
├── doubt-driven-development/SKILL.md
├── api-and-interface-design/SKILL.md
├── performance-optimization/SKILL.md
├── security-and-hardening/SKILL.md
├── observability-and-instrumentation/SKILL.md
├── ci-cd-and-automation/SKILL.md
├── deprecation-and-migration/SKILL.md
├── git-workflow-and-versioning/SKILL.md
├── shipping-and-launch/SKILL.md
├── code-simplification/SKILL.md
├── constraint-driven-development/SKILL.md
├── context-engineering/SKILL.md
├── documentation-and-adrs/SKILL.md
├── source-driven-development/SKILL.md
└── using-agent-skills/SKILL.md

SKILL.md Anatomy

Each skill follows this structure:

1. Overview — what and why
2. When to Use — trigger conditions and exclusions
3. Core Process — numbered steps with Kotlin code examples
4. Common Rationalizations — excuses agents use to skip steps + rebuttals
5. Red Flags — observable violations during review
6. Verification — exit checklist requiring tangible evidence

Target: each SKILL.md stays under 500 lines.

Agent Personas

Three reusable agent personas in agents/:

Orchestration: Personas and Skills

Three composable layers, each with a distinct job:

• Skills (skills/<name>/SKILL.md) — workflows with steps and exit criteria. The how. Mandatory steps when an intent matches.
• Personas (agents/<role>.md) — roles with a perspective and an output format. The who. See docs/agent-personas.md for the full catalogue and orchestration rules.
• Slash Commands — user-facing entry points (e.g. /spec, /build, /ship) that compose skills and personas.

Composition rule: The user — or a slash command acting on their behalf — is the orchestrator. Personas do not invoke other personas. A persona may invoke skills.

The endorsed multi-persona pattern is parallel fan-out with a merge step — used during shipping to run code-reviewer, security-auditor, and test-engineer concurrently on the same diff and synthesize their reports into a single go/no-go decision.

Command Mappings

Instructions map to development phases:

Reference Checklists

Detailed checklists in references/:

• testing-patterns.md — JUnit5, MockK, Espresso, Compose tests, MockWebServer
• security-checklist.md — OWASP Mobile, Network Security Config, cert pinning, secrets
• performance-checklist.md — Android Vitals, Baseline Profiles, Macrobenchmark, APK size
• accessibility-checklist.md — TalkBack, Accessibility Scanner, touch targets, contrast

Core Principles

1. Skills are workflows, not suggestions — follow steps in order, never skip verification
2. Anti-rationalizations are real — check the "Common Rationalizations" table before skipping steps
3. Evidence over assertions — "it looks right" is not verification
4. Assumption surfacing — state assumptions explicitly before implementing
5. Scope discipline — only modify what's requested