Android Compose MigrationSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: android-compose-migration
description: Migrate an Android XML View to Jetpack Compose following a structured 10-step workflow. Use when converting XML layouts to Compose, setting up Compose in an existing View-based project, or incrementally adopting Compose.
metadata:
  triggers:
    files:
    - 'layout/*.xml'
    - '**/*Fragment.kt'
    - '**/*Activity.kt'
    keywords:
    - migrate to compose
    - xml to compose
    - compose migration
    - ComposeView
    - AndroidView
    - interoperability
---
# XML to Jetpack Compose Migration

## **Priority: P1 (HIGH)**

Structured 10-step workflow for migrating XML layouts to Compose.

## Step 1: Identify the migration candidate

If the user specified a target XML layout, proceed to Step 2. Otherwise, pick the best candidate:
- Prefer leaf layouts (not deeply nested in other XMLs).
- Prefer layouts with few custom Views.
- Avoid layouts with complex RecyclerView adapters as a first migration.

## Step 2: Analyze the layout

Examine the XML structure: list all Views, data bindings, click listeners, style references, and custom Views needing `AndroidView` wrappers.

## Step 3: Create a plan

Generate a checklist of every View → Composable mapping. Present to user for approval.

## Step 4: Capture baseline UI

Ask the user for a screenshot, or take one via emulator for visual comparison.

## Step 5: Set up Compose dependencies

Check `build.gradle.kts` or `libs.versions.toml` for Compose BOM and compiler. If missing, add them. See [dependency setup](references/dependency-setup.md).

## Step 6: Set up Compose theming

If missing, initialize minimum required theme — map XML colors/styles to Compose. Do NOT migrate the entire theme.

## Step 7: Migrate the XML layout

Convert each View to its Compose equivalent. See [interop patterns](references/interop-patterns.md) for the View→Composable mapping table, ComposeView, and AndroidView usage. Include a `@Preview` for every new Composable.
Use `LazyColumn` or `LazyRow` for list-heavy screens instead of flattening them into one large static composable.

## Step 8: Replace usages

Use `ComposeView` to host Compose in Views, or `AndroidView` for Views in Compose. See [interop patterns](references/interop-patterns.md).

## Step 9: Validate

Compare baseline screenshot with Compose Preview. Focus on layout and styling. Iterate until visual parity.

## Step 10: Clean up

Delete the migrated XML file and legacy tests. Only remove code not referenced elsewhere.

## Verification

- [ ] Compose Preview renders correctly.
- [ ] Visual parity with original XML layout.
- [ ] `./gradlew build` succeeds.
- [ ] No broken references to deleted XML files.

## Anti-Patterns

- **No full theme migration**: Only migrate what the target layout needs.
- **No new View instances in AndroidView update**: Mutate existing, don't recreate.
- **No missing ViewCompositionStrategy**: Always set it on ComposeView to avoid leaks.

## References

- [Dependency Setup](references/dependency-setup.md)
- [Interop Patterns](references/interop-patterns.md)

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.