Android Project Generator Skill#

Purpose#

Ensure AI-generated Android projects compile successfully on the first attempt by providing:

1. Version compatibility knowledge — AGP/Gradle/JDK/Kotlin version matrices
2. Standardized configuration templates — Complete, working Gradle configurations
3. Environment detection — Adapt to local JDK/SDK versions
4. Post-generation validation — Verify compilation succeeds
5. APK build orchestration — Distinguish between scaffolding-only, build-failed, and compiled APK states
6. Native integration guidance — Detect native intent and scaffold JNI/NDK/CMake-compatible project configuration

Runtime & Safety Requirements#

Before using this skill on a production or sensitive machine, verify:

• Required binaries are present in PATH: python, java, and at least one of gradle/ gradlew.
• Android tooling is installed on disk for real build validation: Android SDK (platforms/build-tools/cmdline-tools/licenses), and optional NDK+CMake for native flows.
• Environment variables are correctly scoped: JAVA_HOME (recommended), ANDROID_HOME or ANDROID_SDK_ROOT, optional ANDROID_NDK_HOME or NDK_HOME for native workflows.
• Local command execution is acceptable in the current host policy.
• Device interactions ( adb install, adb shell am start) are allowed for connected devices/emulators.
• Build-time network access is acceptable (for Gradle wrapper/dependency resolution).

This skill runs local commands and may perform build/device operations; treat it as operational code, not documentation-only guidance. It does not request API keys, tokens, or cloud credentials by design.

Credentials#

This skill does not require cloud credentials, API keys, or tokens.

It does rely on local environment variables and installed binaries/tooling:

• Env vars inspected/used: JAVA_HOME, ANDROID_HOME/ ANDROID_SDK_ROOT, and for native projects ANDROID_NDK_HOME/ NDK_HOME.
• Binaries/tooling expected: java, gradle/ gradlew, Android SDK/NDK on disk, and optional adb for install/launch verification.

The scripts do not intentionally exfiltrate data, but they do run subprocesses that may:

• access network resources (for Gradle wrapper/dependency downloads)
• interact with attached devices/emulators ( adb)

Package Scope#

This repository is a skill package plus its own development test harness. Only the following paths are part of the skill:

• SKILL.md, README.md, LICENSE
• references/ — version matrix and configuration templates
• scripts/detect_env.py, scripts/project_validator.py, scripts/build_flow.py

tests/, cache/, and reports/ are development-only and are excluded from the release package (see .skillignore). All self-test tooling — test runner, report generator, report renderer, and the sitecustomize cache helper — lives under tests/.

The skill workflow never imports from or executes anything under tests/. If a distributed copy of this package contains tests/, that is a packaging error, not skill behaviour.

Tool Scope & Permission Boundaries#

The skill requests no tool allow-list beyond ordinary local execution. Its explicit boundaries are:

DimensionAllowedNot allowedReadsSKILL.md, references/, the target project directory, and the environment variables listed belowUnrelated files outside the target projectWritesOnly the generated project directory ( settings.gradle.kts, build.gradle.kts, app/**, wrapper files) and local.propertiesAny path outside the generated projectExecutesjava -version, gradle/ gradlew, adb (install/launch only)Arbitrary shells, package installs, credential or key accessNetworkGradle wrapper and dependency resolutionAny upload or exfiltration of local dataCredentialsNone required, none requestedAPI keys, tokens, cloud credentialsEnv vars readJAVA_HOME, ANDROID_HOME/ ANDROID_SDK_ROOT, ANDROID_NDK_HOME/ NDK_HOMEAnything else

All subprocess invocations use argument lists (never a shell string), so no caller-controlled input is interpolated into a command line.

If the host policy forbids local command execution or device interaction, stop after Phase 4 (file generation) and report the project as scaffolding_only.

When to Use This Skill#

Trigger this skill when:

• Creating a new Android project from scratch
• Generating Gradle configuration files ( build.gradle.kts, settings.gradle.kts)
• Setting up Android project structure
• Adding or planning C/C++ native code ( JNI, NDK, CMake, externalNativeBuild)
• User asks to "create an Android app" or "generate an Android project"
• Debugging Gradle version compatibility issues

Workflow#

Phase 1: Audit the Build Environment First#

If the project is meant to build on the current machine, do not generate files yet. Audit the environment first:

bash

python scripts/detect_env.py

Treat this phase as mandatory for local project generation because most "AI generated Android project won't compile" failures are environment mismatches, not template mistakes.

This outputs:

• JDK version → determines AGP version range
• JAVA_HOME configuration and version
• PATH java executable and version
• Gradle CLI JDK source ( JAVA_HOME vs PATH)
• Android SDK path and build-tools versions
• Installed Android platforms
• cmdline-tools / licenses readiness
• NDK version (if present)
• Recommended configuration for the detected environment
• Environment assessment with blocking issues and warnings

If ready_for_build is false:

• Explain the blocking issues clearly
• Prefer fixing the environment before generating a "build-ready" project
• If the user still wants files generated, say the project is scaffolding-only until the environment issues are fixed

If the environment status is degraded:

• Explain why the build is risky rather than blocked
• Most commonly this means JDK 17 exists but JAVA_HOME is missing, so Gradle is falling back to PATH
• Recommend aligning Android Studio, CLI Gradle, and project-level JDK configuration before claiming the build setup is stable

Phase 2: Select Configuration Profile#

Base the profile on audited environment data, not guesswork:

ProfileAGPGradleJDKUse Casestable8.7.08.917+Recommended for most projectslatest9.1.09.3.117+New features, Android 16+legacy7.4.27.511+Older environments

Default to "stable" profile only when the environment is ready for it.

Use this decision order:

1. If JDK 17+, platforms/android-35, and build-tools are present → use stable
2. If user explicitly wants Android 16 / newest APIs and the environment supports it → use latest
3. If JDK is 11-16 → use legacy
4. If the environment is incomplete → stop and surface what is missing before claiming the project is build-ready

Native 触发策略（ native_enabled）：

• 默认 native_enabled = false
• 如果提示词命中强信号（如 JNI、 NDK、 CMake、 externalNativeBuild、 C++、 native library、 原生模块）→ 自动切到 native_enabled = true
• 如果只命中弱信号（如 native、 底层、 性能优化）→ 先标记候选并二次确认，再决定是否开启
• 若用户显式指定（例如 native_enabled=true/false），显式配置优先于关键词推断

Additional JDK rules:

• Prefer a clearly configured JAVA_HOME over an accidental PATH java
• If JAVA_HOME and PATH java disagree, treat that as a reproducibility risk and explain it
• Prefer a project-level Gradle JDK setting for long-term consistency

Phase 3: Generate Project Structure#

Always create the complete file structure:

text

ProjectName/
├── settings.gradle.kts
├── build.gradle.kts
├── gradle.properties
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── app/
│   ├── build.gradle.kts
│   ├── src/
│   │   └── main/
│   │       ├── AndroidManifest.xml
│   │       ├── java/com/example/project/
│   │       │   └── MainActivity.kt
│   │       └── res/
│   │           ├── layout/
│   │           │   └── activity_main.xml
│   │           ├── values/
│   │           │   ├── strings.xml
│   │           │   └── themes.xml
│   │           └── mipmap-*/
│   │               ├── ic_launcher.png
│   │               └── ic_launcher_round.png
│   └── proguard-rules.pro
└── local.properties (create when sdk path is known and immediate CLI build is expected)

Important:

• Do not stop at "mostly complete"
• The generated project is not considered ready until wrapper files and validation are in place
• If SDK path is known and the goal is immediate command-line build, create local.properties with sdk.dir=... to reduce local environment ambiguity
• If the machine has JDK 17 but no stable project-level JDK selection, recommend GRADLE_LOCAL_JAVA_HOME or equivalent project-scoped JDK binding

Phase 4: Use Configuration Templates#

Load templates from references/config-templates.md:

• Use the "Golden Configuration: Stable" section for the "stable" profile
• Use the "China Mirror" variant for users in China (detected by locale or explicit request)
• Replace placeholders: MyApp, com.example.myapp, com.example.myapp.MainActivity
• Keep namespace, applicationId, source package path, and theme names aligned
• If generating a project that must build immediately, prefer the template path that includes local.properties

Phase 5: Make Gradle Wrapper Real, Not Placeholder#

Before reporting the project as buildable, ensure the wrapper is genuinely usable:

• Required files:
  • gradlew
  • gradlew.bat
  • gradle/wrapper/gradle-wrapper.properties
  • gradle/wrapper/gradle-wrapper.jar
• A gradle-wrapper.properties file alone is not enough
• Placeholder scripts are not acceptable for a claimed "first build succeeds" result

Use one of these approaches:

1. Copy wrapper files from a known-good template project
2. Generate them with gradle wrapper --gradle-version <target-version> if Gradle is installed
3. If neither is possible, explicitly say wrapper generation is incomplete and do not claim the project is ready for assembleDebug

You can use scripts/project_validator.py logic as the acceptance bar:

• invalid package name => block
• missing wrapper jar => block
• placeholder wrapper scripts => block

Phase 6: Validate Compilation with a Real Build Loop#

After generating all files, MUST run:

bash

./gradlew assembleDebug

If compilation fails:

1. Read the error message carefully
2. Check version compatibility in references/version-matrix.md
3. Check whether the failure is really caused by environment readiness, wrapper incompleteness, or template/config mismatch
4. Fix one root cause at a time and retry
5. Do not report success until assembleDebug passes with the generated project

If the wrapper is unavailable or the environment is missing mandatory SDK components:

• Do not present the project as "verified buildable"
• Say exactly which prerequisite prevented real verification

Phase 7: Confirm APK Output and Runtime Readiness#

After assembleDebug, verify that the debug APK really exists:

text

app/build/outputs/apk/debug/app-debug.apk

Use scripts/build_flow.py concepts as the final status model:

• scaffolding_only
  • Files were generated
  • Build was not attempted because the environment was blocked
• build_failed
  • Gradle ran, but assembleDebug failed or no APK was produced
• compiled
  • assembleDebug succeeded and the debug APK exists

If a device or emulator is available, continue one more step:

• install the debug APK
• launch the main activity
• only then classify the project as runnable

Additional final states:

• install_failed
  • APK exists
  • installation to device/emulator failed
• launch_failed
  • APK installed
  • main activity launch failed
• runnable
  • APK built
  • APK installed
  • main activity launched successfully

Only the compiled state should be described as:

• environment normal
• project buildable
• APK produced

Only the runnable state should be described as:

• environment normal
• project buildable
• app installable
• app launch verified on device or emulator

Reference Files#

Version Compatibility Matrix#

See references/version-matrix.md for:

• AGP 9.x / 8.x / 7.x version requirements
• Kotlin compatibility with AGP
• Gradle Wrapper configuration

Key rules:

• AGP 8.0+ requires JDK 17 (non-negotiable)
• AGP 9.x requires Gradle 9.1+
• Always check the matrix when in doubt

Configuration Templates#

See references/config-templates.md for:

• Complete settings.gradle.kts template
• Project-level and module-level build.gradle.kts
• gradle.properties defaults
• gradle-wrapper.properties format
• Minimal MainActivity.kt and AndroidManifest.xml
• China mirror configuration

Environment Detection Script#

scripts/detect_env.py provides:

• JDK version detection (parses java -version output)
• Android SDK path discovery (ANDROID_HOME, ANDROID_SDK_ROOT, common paths)
• Build-tools version listing
• NDK version detection
• Recommended configuration based on detected JDK

Run this script to adapt the generated project to the user's actual environment.

Critical Rules#

1. Never skip the validation step — Always run ./gradlew assembleDebug
2. JDK 17 is mandatory for AGP 8.x+ — Do not generate AGP 8.x config if JDK < 17
3. Use Kotlin DSL (.kts) — Groovy DSL is legacy, prefer build.gradle.kts
4. Set correct namespace — AGP 8.0+ requires namespace in build.gradle, not manifest
5. A real wrapper is mandatory for build claims — Do not rely on placeholder scripts
6. Create local.properties when immediate local CLI build is required and sdk path is known
7. Prefer explicit JDK selection — Align JAVA_HOME, Android Studio Gradle JDK, and project-level Gradle JDK settings
8. Use Java toolchains — Declare the required Java toolchain instead of relying only on machine defaults
9. Use Version Catalog for complex projects — Consider gradle/libs.versions.toml for larger projects

Common Mistakes to Avoid#

MistakeFixMissing namespace in app/build.gradle.ktsAdd namespace = "com.example.myapp" in android {} blockWrong JDK version for AGP 8.xUse AGP 7.x if JDK < 17, or instruct user to install JDK 17Inconsistent AGP/Gradle versionsCheck version-matrix.md, use recommended pairsMissing or fake Gradle Wrapper filesAlways include gradlew, gradlew.bat, gradle-wrapper.properties, and gradle-wrapper.jarWrong compileSdk for AGP versionAGP 8.7+ requires compileSdk = 35, AGP 9.x requires compileSdk = 36Missing SDK platform or build-toolsCheck environment audit before generation; install missing SDK components firstBuild verified only in theoryDo not claim success without a real assembleDebug runJAVA_HOME missing but PATH java existsTreat as degraded, not fully stable; recommend explicit JDK configurationJAVA_HOME and PATH java point to different JDKsExplain that Gradle CLI will prefer JAVA_HOME, which can differ from shell expectationsassembleDebug succeeded but no APK foundTreat as build verification failure until app-debug.apk is confirmedAPK exists but install failsTreat as install_failed; do not claim the app is runnableInstall succeeds but launch failsTreat as launch_failed; do not claim runtime verification passed

Example Usage#

User: "Create a new Android project called TodoApp"

AI Response:

1. Load this skill
2. Run detect_env.py (if possible)
3. Check the environment assessment and confirm it is ready for a stable build
4. Select "stable" profile (AGP 8.7.0, Gradle 8.9)
5. Generate complete project structure from templates
6. Replace placeholders: MyApp → TodoApp, com.example.myapp → com.example.todoapp
7. Ensure real wrapper files exist, not placeholders
8. Run ./gradlew assembleDebug
9. Confirm app/build/outputs/apk/debug/app-debug.apk exists
10. If a device or emulator is available, install the APK and launch the main activity
11. Report compiled only if build + APK verification pass
12. Report runnable only if build + install + launch all pass

---

This skill transforms Android project generation from a guessing game into an audited, verifiable build process.