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:

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:

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:

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:

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:

./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:

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

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.