К основному содержанию
скилл CX Codex

capacitor-android-dex-optimization — скилл для Claude Code

Скилл capacitor-android-dex-optimization для Claude Code настраивает R8 в Android-приложении на Capacitor. Запускается при ошибке оптимизации DEX в Play Console, сбое приложения после включения минификации или ошибке сборки R8.

MIT 189 установок ★ 56 обновлён 2026-10-20

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add capawesome-team/skills --skill capacitor-android-dex-optimization -a claude-code
Открыть на GitHub

Что делает capacitor-android-dex-optimization

Скилл помогает включить R8 в релизной сборке Capacitor-приложения и настроить правила ProGuard. Он меняет параметры в android/app/build.gradle, добавляет правила для аннотаций Capacitor и плагинов, разбирает ошибки Missing class и описывает проверку подписанного APK через logcat, mapping.txt и r8.json.

Для работы нужны приложение на Capacitor 6, 7 или 8 с каталогом android/, Android Gradle Plugin 8.0 или новее, подходящий версии Capacitor JDK и adb. Проверка на устройстве требует подключённого устройства или эмулятора. Скилл не предназначен для iOS, сжатия ресурсов, проектов плагинов Capacitor и обновления версии Capacitor.

Какие задачи решает

  • включить R8 в релизной сборке Android-приложения на Capacitor
  • устранить сбой при запуске после включения минификации
  • разобрать ошибку сборки R8 Missing class
  • проверить оптимизацию DEX в подписанном APK

Примеры запросов агенту

  • Настрой R8 в моём Android-приложении на Capacitor для проверки DEX в Play Console.
  • Разбери сбой при запуске после включения minifyEnabled.
  • Устрани ошибку Missing class в релизной сборке R8.

Как установить capacitor-android-dex-optimization

1Через Skills CLI (Vercel)

npx skills add capawesome-team/skills --skill capacitor-android-dex-optimization -a claude-code

2Вручную: положить файлы

~/.claude/skills/capacitor-android-dex-optimization/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/capacitor-android-dex-optimization/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о capacitor-android-dex-optimization

Как установить capacitor-android-dex-optimization в Claude Code?

Выполни npx skills add capawesome-team/skills --skill capacitor-android-dex-optimization -a claude-code. Файл скилла находится в ~/.claude/skills/capacitor-android-dex-optimization/SKILL.md.

Что делает capacitor-android-dex-optimization?

Помогает включить R8 и добавить правила ProGuard для Android-приложения на Capacitor. Также описывает разбор ошибок сборки и проверку релизного APK.

Что нужно для работы capacitor-android-dex-optimization?

Нужны приложение на Capacitor 6, 7 или 8 с каталогом android/, Android Gradle Plugin 8.0 или новее, JDK для используемой версии Capacitor и adb. Для проверки на устройстве требуется подключённое устройство или эмулятор.

Исходный текст

SKILL.md · MIT
---
name: capacitor-android-dex-optimization
description: "Guides the agent through enabling R8 in a Capacitor Android app so that it meets the Google Play DEX code optimization requirement (at least 25% obfuscation, optimization and shrinking from February 2027 for apps with more than 10 MB of DEX code). Covers `minifyEnabled true` with `proguard-android-optimize.txt` in `android/app/build.gradle`, the `-keep @interface com.getcapacitor.** { *; }` rule that prevents the startup crash in R8 full mode, per-plugin keep rules, resolving R8 'Missing class' build errors via `missing_rules.txt`, building a signed release APK with the debug keystore, and verifying with logcat, `mapping.txt` and the `r8.json` file inside the app bundle. Use when Play Console reports a DEX code optimization finding, when a Capacitor app crashes on startup after enabling `minifyEnabled`, or when R8 fails the release build. Do not use for iOS, resource shrinking, Capacitor plugin projects, Capacitor version upgrades, or non-Capacitor mobile frameworks."
license: MIT
compatibility: "Requires a Capacitor 6, 7 or 8 app with an `android/` platform, Android Gradle Plugin 8.0 or newer, a JDK matching the Capacitor version, and `adb` for on-device verification."
metadata:
  author: capawesome-team
  source: https://github.com/capawesome-team/skills/tree/main/skills/capacitor-android-dex-optimization
---

# Capacitor Android: DEX Code Optimization

Enable R8 in a Capacitor Android app and add the keep rules a Capacitor app needs so that the release build passes the Google Play DEX code optimization requirement without crashing at startup.

The Android project that `npx cap add android` generates sets `minifyEnabled false`, so R8 never runs and Google Play measures close to 0% obfuscation, optimization and shrinking. From February 2027, Google Play requires at least 25% in each category for apps with more than 10 MB of DEX code. Play reads the numbers from the `r8.json` file inside the app bundle for apps built with AGP 8.10 or newer.

## Prerequisites

| Requirement | Version |
| ----------- | ------- |
| Capacitor   | 6+      |
| Android Gradle Plugin | 8.0+ (8.10+ for the `r8.json` check in Step 6) |
| JDK         | 17 for Capacitor 6 and 7, 21 for Capacitor 8 |
| `adb`       | installed, with a device or emulator connected for Step 5 |

The project must be a Capacitor **app** (not a plugin) with an existing `android/` directory.

## Agent Behavior

- **Inspect before editing.** Read the current Gradle and ProGuard configuration first (Step 1). Never overwrite existing rules in `android/app/proguard-rules.pro`; append to them.
- **Keep rules narrow.** Never add `-keep class com.getcapacitor.** { *; }` or `-dontobfuscate`. Broad rules block the optimization that Google Play measures. `@capacitor/android` already ships consumer rules for plugin classes and their annotated methods.
- **Only release builds run R8.** Debug builds never show whether the rules are complete. Every verification step uses a signed release build.
- **Read `missing_rules.txt` before pasting it.** A `-dontwarn` rule is correct only for a class a plugin probes for at runtime (Step 4).

## Procedures

### Step 1: Analyze the Project

1. Verify the project is a Capacitor **app**: `package.json` lists `@capacitor/android` in `dependencies` and the `android/` directory exists. If `android/` is missing, abort and inform the user.
2. Read the `@capacitor/core` version from `package.json`. Record the major version.
3. Read the AGP version from `android/build.gradle`:

   ```groovy
   classpath 'com.android.tools.build:gradle:8.13.2'
   ```

   If the major version is below 8, abort and direct the user to the `capacitor-app-upgrades` skill first. Record whether the version is 8.10 or newer (this decides whether Step 6 applies).

4. Read the `release` build type in `android/app/build.gradle`. Record the values of `minifyEnabled`, `shrinkResources` (if present) and the `proguardFiles` line.
5. Read `android/app/proguard-rules.pro` and record every existing rule.
6. Read `android/gradle.properties` and record whether `android.enableR8.fullMode` is set. If it is set to `false`, inform the user that the keep rule in Step 3 makes this setting unnecessary and offer to remove it, because full mode produces higher optimization numbers.
7. Inventory the installed Capacitor plugins from `package.json` `dependencies`. Match these prefixes:

   - `@capacitor/*`
   - `@capawesome/*` and `@capawesome-team/*`
   - `@capacitor-community/*`
   - `@capacitor-firebase/*`
   - `@capacitor-mlkit/*`
   - `@revenuecat/*`
   - Any other package with `"capacitor"` in its `package.json` `keywords` array

   Record each plugin's package name. Step 3 uses this list.

### Step 2: Enable R8

In `android/app/build.gradle`, update the `release` build type. Replace `minifyEnabled false` with `minifyEnabled true` and replace `proguard-android.txt` with `proguard-android-optimize.txt`:

```diff
 android {
     buildTypes {
         release {
-            minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            minifyEnabled true
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
 }
```

`proguard-android.txt` contains `-dontoptimize`, which blocks most of what R8 could do, and AGP 9 no longer accepts that file by default. Do not add `shrinkResources true`. The Play metrics measure DEX code, and resource shrinking breaks resources that are referenced by name from JavaScript or `capacitor.config.ts` (for example the `smallIcon` of the Push Notifications plugin).

### Step 3: Add Keep Rules

1. If the Capacitor version recorded in Step 1 is below 8.6.0, append the Capacitor annotation rule to `android/app/proguard-rules.pro`. Skip this if the file already contains the exact rule or if the app is on Capacitor 8.6.0 or newer, which ships the rule in its consumer rules:

   ```diff
   +# Capacitor annotations: required below Capacitor 8.6.0 in R8 full mode (ionic-team/capacitor#8589)
   +-keep @interface com.getcapacitor.** { *; }
   ```

   R8 full mode (the default since AGP 8.0) strips annotations from classes that are not explicitly kept. Before Capacitor 8.6.0, `@capacitor/android` kept the classes annotated with `@CapacitorPlugin` but not the annotation types themselves. Without the rule, the build passes and the app crashes on startup with a `NullPointerException` in `com.getcapacitor.Plugin.getPermissionStates` the first time a plugin checks its permissions. The rule covers `@CapacitorPlugin`, `@Permission`, `@PermissionCallback`, `@ActivityCallback`, `@PluginMethod` and the legacy `@NativePlugin`.

2. For each plugin recorded in Step 1, look up its ProGuard rules and append them to `android/app/proguard-rules.pro` if they are missing:

   - Read the plugin's README in `node_modules/<package>/README.md` and search for a `Proguard`, `ProGuard` or `R8` section.
   - For Capawesome, Capacitor Firebase, Capacitor MLKit and RevenueCat plugins, the `capacitor-plugins` skill ships a reference file per plugin in its `references/` directory with the same section.

   Most plugins ship no rules of their own because the Capacitor consumer rules cover them. A plugin documents a rule only when it relies on reflection or serialization. Example for the Capawesome SQLite plugin:

   ```diff
   +# Capawesome plugins that rely on reflection
   +-keep class io.capawesome.capacitorjs.plugins.** { *; }
   ```

3. Do not add rules for `com.getcapacitor.**` classes, `@JavascriptInterface` methods, Firebase or Play Services. `@capacitor/android` declares its own consumer rules that keep every class annotated with `@CapacitorPlugin` together with its `@PluginMethod`, `@PermissionCallback` and `@ActivityCallback` methods. AGP's default rules keep `@JavascriptInterface` methods, and the large SDKs ship consumer rules of their own.

### Step 4: Build a Signed Release APK

Debug builds never run R8, and a release build has to be signed to install. Sign the local release build with the Android debug keystore through the properties that Android Studio injects into Gradle. This does not change `build.gradle`:

```bash
cd android
./gradlew assembleRelease \
  -Pandroid.injected.signing.store.file=$HOME/.android/debug.keystore \
  -Pandroid.injected.signing.store.password=android \
  -Pandroid.injected.signing.key.alias=androiddebugkey \
  -Pandroid.injected.signing.key.password=android
```

If `$HOME/.android/debug.keystore` does not exist, run any debug build once (`./gradlew assembleDebug`) to create it, then retry.

If the build fails with `Missing class` errors, R8 writes a ready-to-paste file to `android/app/build/outputs/mapping/release/missing_rules.txt`. Read each entry and decide per class:

| Case | Action |
| ---- | ------ |
| The plugin compiles against the library as `compileOnly` and probes for it at runtime with `Class.forName` (optional backend) | Add the `-dontwarn` rule to `android/app/proguard-rules.pro`. |
| The plugin calls the class unconditionally | Do **not** add `-dontwarn`. Add the missing dependency to `android/app/build.gradle` instead, or the app throws `NoClassDefFoundError` at runtime. |

Known optional backends:

```diff
+# Optional SQLite backends that the Capawesome SQLite plugin probes for at runtime
+-dontwarn io.requery.android.database.**
+-dontwarn net.zetetic.database.**
```

The Capawesome SQLite plugin compiles against both SQLCipher (`net.zetetic.database.**`) and requery's `sqlite-android` (`io.requery.android.database.**`) and bundles only the one selected in `android/variables.gradle`, so both `-dontwarn` lines are correct for that plugin.

Rebuild after every rule change until `assembleRelease` succeeds.

### Step 5: Verify on a Device

1. Confirm a device or emulator is connected with `adb devices`. If none is connected, hand the following checks to the user with the exact commands.
2. Install the release APK:

   ```bash
   adb install -r app/build/outputs/apk/release/app-release.apk
   ```

3. Clear logcat, launch the app, and watch for the failure signatures while it starts:

   ```bash
   adb logcat -c
   adb logcat | grep -E 'FATAL EXCEPTION|ClassNotFoundException|NoSuchMethodException|NullPointerException'
   ```

   The annotation crash from Step 3 appears within the first second. Afterwards, ask the user to run every flow that requests a permission or waits for another activity (camera, file picker, settings screen, sign-in) and watch logcat during each one.

4. Open `android/app/build/outputs/mapping/release/mapping.txt` and confirm that the plugin classes recorded in Step 1 still appear under their original names. Search for the plugin's Android package, for example `io.capawesome.capacitorjs.plugins`. A renamed plugin class means a keep rule is missing. Tell the user to archive `mapping.txt` with every release, since production stack traces need it.

### Step 6: Read the Play Numbers Before Uploading

Skip this step if the AGP version recorded in Step 1 is below 8.10: older versions do not write `r8.json`, and Play computes the numbers itself.

Build the app bundle with the same signing properties as Step 4 and read the R8 metadata from it:

```bash
./gradlew bundleRelease \
  -Pandroid.injected.signing.store.file=$HOME/.android/debug.keystore \
  -Pandroid.injected.signing.store.password=android \
  -Pandroid.injected.signing.key.alias=androiddebugkey \
  -Pandroid.injected.signing.key.password=android
unzip -p app/build/outputs/bundle/release/app-release.aab BUNDLE-METADATA/com.android.tools/r8.json
```

The file reports the obfuscation, optimization and shrinking percentages that Play Console shows in the app bundle explorer for that upload. Each must be at least 25%. If a value is below 25%, search `android/app/proguard-rules.pro` for broad rules (`-keep class **`, `-dontobfuscate`, `-dontoptimize`, `-dontshrink`) and narrow them.

### Step 7: Report

Summarize for the user:

1. The changes to `android/app/build.gradle` and `android/app/proguard-rules.pro`.
2. Any `-dontwarn` rule added and why it is safe, and any missing dependency that was added instead.
3. The three percentages from `r8.json` (if Step 6 ran).
4. That `mapping.txt` must be archived per release. An Android App Bundle embeds it in `BUNDLE-METADATA/`, so Play deobfuscates crash and ANR reports on its own. Only APK uploads need a manual upload in Play Console. The Firebase Crashlytics Gradle plugin uploads it automatically.
5. That the release build is now a standing test target: rerun Step 5 before every upload and check `missing_rules.txt` again whenever a plugin is added.

## Error Handling

- **App crashes on startup with `NullPointerException` at `com.getcapacitor.Plugin.getPermissionStates`**: The app is on Capacitor below 8.6.0 and the `-keep @interface com.getcapacitor.** { *; }` rule is missing from `android/app/proguard-rules.pro`. Add it (Step 3) and rebuild, or upgrade to Capacitor 8.6.0, which ships the rule (ionic-team/capacitor#8646).
- **Build fails with `Missing class <name>`**: Follow the `missing_rules.txt` decision table in Step 4.
- **Build fails because `proguard-android.txt` is not supported (AGP 9)**: Replace it with `proguard-android-optimize.txt` as in Step 2.
- **A plugin method is not found at runtime (`NoSuchMethodException`) or a plugin class is renamed in `mapping.txt`**: Add the plugin's documented keep rule from its README (Step 3, item 2). If the README has none, add `-keep class <plugin Android package>.** { *; }` for that plugin only and report it to the user as a candidate for an upstream fix.
- **`adb install` fails with `INSTALL_PARSE_FAILED_NO_CERTIFICATES`**: The release APK is unsigned. Rerun `assembleRelease` with the four `-Pandroid.injected.signing.*` properties from Step 4.
- **Permission checks return an empty result on Capacitor 8.5.2 or 8.5.3 without crashing**: Capacitor 8.5.2 added a null check in `getPermissionStates()` that hides the crash but returns an empty permission map, and `requestPermissions()` still throws. The keep rule from Step 3 is still required on those versions.
- **Resources missing at runtime after enabling `shrinkResources`**: Resources referenced by name from JavaScript or `capacitor.config.ts` are invisible to the resource shrinker. List them in `android/app/src/main/res/raw/keep.xml` with `tools:keep`, or remove `shrinkResources true`.

## Limitations

- The skill verifies a local release build signed with the debug keystore. The Play Console numbers are only final for the bundle that is uploaded.
- Setting `android.enableR8.fullMode=false` in `android/gradle.properties` also avoids the startup crash, but it lowers the optimization across the whole app and all its dependencies. The keep rule is the cheaper fix.
- Capacitor 8.6.0 ships the annotation keep rule and a rule for `@ActivityCallback` and `@PermissionCallback` methods on non-public base classes in its consumer rules. On 8.6.0 or newer, an existing `-keep @interface com.getcapacitor.** { *; }` line in the app is redundant but harmless. Leave it in place.

## Related Skills

- **`capacitor-app-development`** — General Android troubleshooting and app configuration.
- **`capacitor-plugins`** — Per-plugin reference files, including the ProGuard rules a plugin documents.
- **`capacitor-app-upgrades`** — Upgrade Capacitor and AGP to a version this skill supports.
- **`capawesome-cloud`** — Capawesome Cloud runs the Gradle build as is, so a project with `minifyEnabled true` produces the minified app bundle with the mapping file embedded.

© capawesome-team · MIT · capawesome-team/skills

Похожие скиллы

Все скиллы по теме «Мобильная разработка» →
r8-analyzer Google LLC Скилл r8-analyzer находит избыточные и слишком широкие keep-правила R8 в Android-проектах. Помогает уменьшить размер приложения и вычистить конфигурацию ProGuard. CX Codex +1 3 900установок rev-dex-dumper P4nda0s Скилл rev-dex-dumper для Claude Code выгружает DEX-файлы из памяти Android через ADB. Помогает распаковывать приложения и анализировать обфусцированный код. CX Codex +1 2 000установок capacitor-app-store Cap-go Скилл capacitor-app-store для Claude Code готовит приложение на Capacitor к публикации в App Store и Google Play. Настраивает версии сборок, проверяет требования сторов и устраняет ошибки загрузки пакетов. CX Codex +1 1 300установок capacitor-app-upgrade-v4-to-v5 Cap-go Скилл capacitor-app-upgrade-v4-to-v5 для Claude Code и Codex переводит приложения с Capacitor 4 на 5. Обновляет конфиги Android и iOS по официальному чеклисту миграции. CX Codex +1 692установок kotlin-multiplatform vitorpamplona Скилл для работы с Kotlin Multiplatform и Gradle в репозитории Amethyst: подсказывает, в какой модуль положить код, и ловит сборку на типовых граблях. CX Codex +1 1 600установок okx-dex-market okx Скилл okx-dex-market версии 4.6.6 для чтения данных DEX: котировки, пулы ликвидности, сигналы китов, трейдерские балансы и проверка снайперов в мемкоинах. CX Codex +1 21 700установок

Из того же набора32

Весь набор →
ionic-appflow-migration Скилл ionic-appflow-migration проводит агента через переезд проекта с Ionic Appflow на Capawesome Cloud: импорт организации одной командой и замена Live Update SDK в приложении. CX Codex +1 1 200установок capacitor-vue Скилл capacitor-vue помогает внедрять нативные плагины Capacitor в проекты на Vue 3, Quasar и Nuxt с помощью Composition API и реактивных композаблов. CX Codex +1 1 200установок capacitor-platforms Скилл capacitor-platforms для Claude Code проведёт агента через добавление и настройку десктопных платформ Capawesome для Capacitor — Electron и Tauri. Собирает веб-приложение под macOS, Windows и Linux. CX Codex +1 1 100установок capgo-cloud-migration Скилл capgo-cloud-migration ведёт агента через перенос Capacitor-проекта с Capgo на Capawesome Cloud: находит следы Capgo и меняет плагин, конфиг, каналы и CI/CD. CX Codex +1 972установок capawesome-mcp Проводит агента через подключение к размещённому Capawesome MCP-серверу: поиск документации и управление Capawesome Cloud через API. CX Codex +1 965установок capacitor-mcp Настраивает подключение ИИ-агента к публичному MCP-серверу Capacitor от Capawesome. Помогает искать официальную документацию и плагины под нужную версию фреймворка. CX Codex +1 905установок ionic-framework-mcp Настраивает подключение к бесплатному MCP-серверу Ionic Framework с документацией по v8 и v9, примерами для Angular, React и Vue. CX Codex +1 899установок skill-creator Скилл skill-creator помогает спроектировать папку нового скилла, написать SKILL.md и проверить метаданные. Используйте его для инструкций агенту, а не для обычной документации. CX Codex +1 147установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой