android-scaffold

android-scaffold

Wraps android create with a reproducible flow: list available templates, dry-run to preview, generate, and optionally chain into emulator + first deploy via the other skills in this repo.

Configuration

{
  "androidCli": {
    "defaultTemplate": "empty-activity-agp-9",
    "defaultProjectsDir": "/Users/me/AndroidStudioProjects"
  }
}

Field	Purpose
androidCli.defaultTemplate	Template to use when the user doesn't specify one.
androidCli.defaultProjectsDir	Parent directory for new projects. The skill creates <defaultProjectsDir>/<name> unless the user passes an explicit --output.

Workflow

android create list                                    # see real template names (they evolve)
   ↓
android create --dry-run --verbose <template>          # optional: preview what will be created
   ↓
android create --name=<Name> --output=<dir> <template> # actually create
   ↓ (optional chain)
android-emulator → android-deploy                       # boot an emulator and run the new app

Step-by-step

1. List templates first. Names change; never hardcode without checking.

   android create list
   

   Default landing template at the time of writing is empty-activity-agp-9. Confirm this still appears in the output before relying on it.

2. Pick a template.

   • If user specified one → use it.
   • Else → use androidCli.defaultTemplate from config.
   • Else → ask the user; show 3–5 most relevant options from create list.

3. (Optional) Dry-run for unfamiliar templates so the user can preview file layout before committing:

   android create --dry-run --verbose --output=/tmp/preview <template>
   

   Useful when comparing two templates side by side.

4. Create.

   android create \
     --name="<ProjectName>" \
     --output="<defaultProjectsDir>/<ProjectName>" \
     <template>
   

   • --output is mandatory. Don't omit it.
   • --name controls the project directory name displayed in Studio. If omitted, the output directory's basename is used.

5. Verify. After create:

   cd <output>
   ./gradlew help                # confirms the wrapper resolves
   

   Skip this if the user said "just scaffold, don't run anything".

6. (Optional) First deploy. If the user's intent is "make a new project and run it", chain to:

   • android-emulator to ensure a device is up
   • android-deploy to build and run

Operating rules

1. Always list templates first. Templates are versioned (e.g. empty-activity-agp-9 → future agp-10). Listing avoids stale assumptions.
2. Don't create silently. Show the resolved command and the target output path to the user before executing — scaffolding is irreversible-ish (deleting the output is fine, but the user wants to know where it landed).
3. Don't pre-create the output directory. android create errors if the directory already has files. Let it own creation.
4. Use --dry-run when uncertain. It's free and clarifies what the template emits.
5. Don't wedge in third-party templates. This skill only knows the official android create templates. For custom templates, use a different mechanism.
6. Don't chain to deploy by default. Many users just want the project on disk to open in Studio. Ask before booting an emulator.

Anti-patterns

• ❌ Hardcoding empty-activity-agp-9 without running android create list first — eventually the template name changes and the command fails.
• ❌ Omitting --output — android create requires it.
• ❌ Pre-creating the output directory with mkdir. android create writes into a directory it owns.
• ❌ Running android create inside an existing project root. Always go up one level (or use --output=../NewProject).
• ❌ Boot-and-deploying without asking — scaffold + deploy is two distinct user intents.
• ❌ Recommending a non-Compose template in 2026 unless the user explicitly asks for Views.

Error recovery

Error	Cause	Fix
template '<name>' not found	Stale or wrong template name	android create list, pick a real one
output directory exists and is not empty	Reusing a path	Pick a new output, or delete the existing dir if the user confirms
create succeeded but Gradle sync fails	AGP version newer than installed Gradle	cd <output> && ./gradlew wrapper --gradle-version=<latest>
Studio can't open the project	Missing local.properties with sdk.dir	Run android info and write the resolved path to <project>/local.properties