# Mobile App Builder

> >

- **Type:** Skill
- **Install:** `agentstack add skill-theultimateshyam-claude-skills-mobile-app-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [theultimateshyam](https://agentstack.voostack.com/s/theultimateshyam)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [theultimateshyam](https://github.com/theultimateshyam)
- **Source:** https://github.com/theultimateshyam/claude-skills/tree/main/mobile-app-builder

## Install

```sh
agentstack add skill-theultimateshyam-claude-skills-mobile-app-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Mobile App Builder

Build a production-grade Android app from existing web UI, design assets, or a spec document.
The skill orchestrates a multi-agent pipeline that plans, builds, reviews, and iterates until
the app meets quality gates across functionality, UI correctness, security, and bundle optimization.

## Before You Start

Resolve these two things before entering the pipeline. No phases run until both are answered.

### 1. What are we building from?

You need at least ONE of these from the user:

1. **Assets folder or repo path** - A local directory or git repo with the existing web app code, screenshots, or design files
2. **Google Drive link** - A shared folder with mockups, specs, or assets
3. **Spec file** - A product spec, PRD, or feature doc (markdown, PDF, Google Doc)
4. **Live URL** - A deployed web app to screenshot and reverse-engineer

If the user provides none of these, tell them:

> "To build the app, I need a starting point. Can you share any of these?
> - A folder or repo with the existing UI code or screenshots
> - A Google Drive link with design assets or specs
> - A spec document describing the app's screens and flows
> - A live URL I can inspect
>
> If you're starting from scratch with just an idea, I can help you draft a spec first
> (that's a separate workflow). Come back with that and we'll build from it."

Do not enter the pipeline without a valid input source.

### 2. What technology?

Ask the user:

- **Does this app also need to run on web or iOS in the future?**
  - Yes, or unsure -> **React Native** (Expo managed workflow, generates Android APK)
  - No, Android only -> **Kotlin** (Jetpack Compose, native Android)

Default to Kotlin for pure Android. Use React Native only if cross-platform is needed.

### 3. Understand the source

Once you have both answers, study the input thoroughly before entering Phase 1:

- If **repo/folder**: Read the file tree, identify screens/routes, component structure, state management, API calls, and navigation flow. Map every user-facing screen.
- If **Drive link**: Fetch and catalog all assets. Identify screens, flows, and design patterns.
- If **spec file**: Extract the screen inventory, user flows, data models, and integration points.
- If **live URL**: Take screenshots of every reachable screen. Map the navigation graph. Note interactive elements, forms, modals, and transitions.

Produce a **Source Audit**:
```
## Source Audit
- Screens found: [list each screen with a one-line description]
- Navigation flow: [how screens connect]
- Key components: [reusable UI pieces]
- Data/API dependencies: [what data each screen needs]
- Assets inventory: [icons, images, fonts, colors, branding]
- Gaps/ambiguities: [anything unclear, ask the user]
```

Present the Source Audit to the user for confirmation before entering Phase 1.

## Agent Roster

The pipeline uses five specialized agent roles. Read the corresponding reference file in
`references/` before spawning each agent.

| Role | Reference File | Responsibility |
|------|---------------|----------------|
| **Architect** | `references/architect.md` | Plans iterations, splits tasks, coordinates agents, maintains PLAN.md |
| **Builder** | `references/builder.md` | Implements a single task, commits code |
| **Inspector** | `references/inspector.md` | Reviews each commit against five quality dimensions |
| **QA Lead** | `references/qa-lead.md` | Full E2E validation of the complete app |
| **Guardian** | `references/guardian.md` | Security, code quality, bundle optimization, architecture review |

## Commit Message Convention

All commits across the entire pipeline follow this format:

```
(): 

```

**Types:** `feat`, `fix`, `refactor`, `style`, `chore`, `docs`, `test`
**Scope:** The screen name, module, or cross-cutting concern (e.g., `navigation`, `theme`, `auth-screen`, `home`)

Examples:
- `feat(home): add pull-to-refresh on feed list`
- `fix(navigation): prevent back press from exiting app on main tab`
- `refactor(theme): consolidate color tokens into single palette`
- `chore(deps): remove unused image-picker dependency`
- `style(profile): align avatar and username vertically`

Never include agent names, task IDs, or pipeline metadata in commit messages.
Commits should read like a normal human developer wrote them.

## Untracked Pipeline Files

These files live in the repo root but are **git-ignored**. They are working memory for the
pipeline, not part of the shipped app.

| File | Purpose |
|------|---------|
| `PLAN.md` | Central coordination doc: screen inventory, task registry, iteration log |
| `DECISIONS.md` | Log of autonomous decisions, spec deviations, and improvements made by agents |
| `BUILD_REPORT.md` | Final summary generated at the end of the pipeline |
| `.build-logs/` | Directory for per-agent logs collected during the run |

Add all four to `.gitignore` at project setup:
```
PLAN.md
DECISIONS.md
BUILD_REPORT.md
.build-logs/
```

## The Decisions Log

`DECISIONS.md` is one of the most important outputs of this pipeline. It captures every place
where agents exercised judgment beyond what the spec or source material explicitly specified.

Agents write to DECISIONS.md whenever they:
- **Deviate from spec**: "Spec says bottom nav has 4 tabs, but Settings only has 2 items so I merged it into Profile as a section instead"
- **Fill spec gaps**: "Spec didn't specify error states for the feed. Added a retry-with-illustration pattern consistent with the rest of the app"
- **Make UX improvements**: "Source app has a 3-step flow for editing profile. Consolidated to inline editing since mobile patterns favor it"
- **Choose between alternatives**: "Could use either ViewPager2 or HorizontalPager from Compose. Chose HorizontalPager because the project is Compose-first"
- **Add features not in spec**: "Added haptic feedback on pull-to-refresh since it's standard Android UX"

Format:
```markdown
# Decisions Log

## DECISION-001: 
- **Phase:** Build Loop / E2E / Hardening
- **Task:** TASK-XXX (if applicable)
- **What was specified:** 
- **What was done instead:** 
- **Reasoning:** 
- **Reversible:** Yes / No
- **Impact:** Low / Medium / High

## DECISION-002: ...
```

This file serves two purposes:
1. The human can review autonomous decisions after the build, understand the reasoning, and revert anything they disagree with
2. It becomes input for improving the spec or source material for future builds

## Phase 1: Project Setup

### Repository

Create a new **local** git repo. All pipeline work happens on a feature branch, never on `main`.
The user merges to `main` after reviewing the final output.

```bash
mkdir  && cd 
git init
```

For React Native (Expo):
```bash
npx create-expo-app@latest . --template blank-typescript
```

For Kotlin (Jetpack Compose): scaffold a standard Android project with Gradle, Material3, and
Compose Navigation.

Commit the scaffold to `main`, then immediately branch:
```bash
git add -A && git commit -m "chore(init): scaffold project"
git checkout -b build/agent-pipeline
```

All subsequent commits happen on `build/agent-pipeline`. The `main` branch stays clean with
only the initial scaffold until the user reviews and merges.

### Initialize Pipeline Files

Create `PLAN.md`, `DECISIONS.md`, `.build-logs/`, and add them all to `.gitignore`.

PLAN.md initial structure:

```markdown
# App Build Plan

## Source Audit

## Screen Inventory
| # | Screen | Priority | Status | Assigned To | Iteration |
|---|--------|----------|--------|-------------|-----------|
| 1 | ...    | P0       | TODO   | -           | -         |

## Iteration Log
### Iteration 1
- **Goal:** 
- **Tasks:** 
- **Status:** IN_PROGRESS / COMPLETE / BLOCKED

## Task Registry
### TASK-001: 
- **Screen:** 
- **Description:** 
- **Acceptance criteria:** 
- **Status:** TODO / IN_PROGRESS / REVIEW / DONE / REVERTED
- **Agent:** 
- **Commits:** 
- **Inspector notes:** 
```

## Phase 2: The Build Loop

This is the core orchestration engine. It runs iteratively until all quality gates pass.

### Human Tasks

The human can add tasks at any time, during any phase, in any form. They might say "also
add dark mode" or "the onboarding needs a skip button" or just "handle offline state."
This should never interrupt or pause anything that's already running.

How it works:
1. **Acknowledge** the human's input briefly and confirm understanding
2. **Append** new task entries to PLAN.md's Task Registry with status `TODO` and priority `P0-HUMAN`
3. The Architect picks these up on its next planning pass, like any other task in the backlog
4. **Note** in DECISIONS.md that these tasks came from the human (not derived from the spec)

No special ceremony. The pipeline keeps running. The Architect sees `P0-HUMAN` tasks in the
registry and schedules them into the current or next iteration based on scope and dependencies.
If the human's request conflicts with something already built, the Architect creates both a
task for the new work and a note in DECISIONS.md about the conflict.

### Role: Architect

Read `references/architect.md` before spawning. The Architect:

1. **Before every planning round**, reads `git diff` and `git log --oneline` to understand exactly what changed since the last iteration. This is mandatory, not optional. The Architect cannot plan without knowing the current state of the codebase.
2. Reads `PLAN.md` to cross-reference task status with actual commits
3. Breaks the current iteration goal into parallel tasks (max 4 concurrent)
4. Assigns tasks to Builder agents with clear scope boundaries
5. Updates `PLAN.md` after each iteration cycle

The Architect never writes app code directly. It only plans, coordinates, and updates the plan.

**Task assignment rules:**
- Each task maps to exactly one screen or one cross-cutting concern (navigation, theming, state)
- Tasks must have explicit file-level scope (which files to create or modify)
- Tasks must not overlap in files they touch (prevents merge conflicts)
- Priority order: navigation shell first, then P0-HUMAN, then P0, then P1, then polish

### Role: Builder Agents (Parallel)

Read `references/builder.md` before spawning. Spawn up to 4 Builders per iteration. Each:

1. Receives a single task from the Architect
2. Implements the task in the codebase
3. Logs any spec deviations or autonomous decisions to `DECISIONS.md`
4. Commits with a conventional message (see Commit Message Convention above)
5. Does NOT create log files or meta-commentary in the repo

### Role: Inspector

Read `references/inspector.md` before spawning. After Builders commit, the Inspector reviews
each commit across five dimensions:

1. **Task completion** - Does the commit deliver what the acceptance criteria specify?
2. **Build health** - Does the project compile without errors?
3. **Regression absence** - Do previously completed screens still work?
4. **UI correctness** - No broken layouts, overlapping views, hidden content, or untappable elements
5. **Flow integrity** - Navigation works, back button behaves, transitions are smooth

**Inspector verdict matrix:**

| Verdict | Action |
|---------|--------|
| PASS | Mark task DONE in PLAN.md |
| FAIL (fixable) | Add specific feedback, reassign to Builder |
| FAIL (broken) | `git revert `, mark REVERTED, reassign with notes |

### The Inner Loop

```
Architect reads git diff + git log (mandatory), then plans iteration N
    |
    v
Builders execute tasks in parallel (up to 4)
    |
    v
Each Builder commits
    |
    v
Inspector reviews each commit
    |
    +---> PASS -> mark DONE
    +---> FAIL -> revert or reassign, Builder retries (max 2 retries per task)
    |
    v
Architect reads git diff + git log (mandatory), picks up any new human tasks, plans iteration N+1
```

Repeat until the Architect determines all tasks for the current milestone are DONE.

## Phase 3: E2E Validation (QA Lead)

Read `references/qa-lead.md` before spawning. Once the Architect declares all iterations
complete, the QA Lead does a holistic walkthrough of the entire app.

The QA Lead checks:

1. **Screen coverage** - Every screen from the Source Audit exists and is reachable
2. **Flow completeness** - Every user flow works end-to-end
3. **Missing functionality** - Features present in the source but absent from the build
4. **State management** - Data persists across navigation, back-button works
5. **Visual parity** - Look and feel matches the source app

The QA Lead produces a **Gap Report** with new tasks added to PLAN.md. Control returns
to the Architect for another build loop if gaps exist.

**Exit condition:** Zero missing screens, zero broken flows, zero critical visual issues.

## Phase 4: Hardening (Guardian)

Read `references/guardian.md` before spawning. Only runs after Phase 3 passes.

The Guardian reviews four areas:

1. **Security** - No hardcoded secrets, HTTPS everywhere, secure storage for sensitive data, permissions match usage, input validation
2. **Code simplification** - Remove dead code, consolidate duplicates, simplify nesting, consistent naming
3. **APK bundle optimization** - Enable R8/Proguard, tree-shake deps, compress images (prefer WebP), target under 30MB
4. **Architecture** - Navigation follows Android conventions, state management is predictable, file structure follows community standards, accessibility basics covered

The Guardian creates tasks for failures and hands back to the Architect. All decisions
logged to DECISIONS.md.

**Exit condition:** All four areas report clean.

## Phase 5: APK Build

Once Phase 4 passes, build the release APK.

### React Native
```bash
cd android && ./gradlew assembleRelease
```
APK location: `android/app/build/outputs/apk/release/app-release.apk`

### Kotlin
```bash
./gradlew assembleRelease
```
APK location: `app/build/outputs/apk/release/app-release.apk`

If the build fails, create a fix task and return to the build loop.

## Phase 6: Build Report

After a successful APK build, generate `BUILD_REPORT.md` at the repo root. This is the
final deliverable alongside the APK itself.

### Report Structure

```markdown
# Build Report

## Summary
- **App name:** 
- **Technology:** React Native / Kotlin (Jetpack Compose)
- **Branch:** `build/agent-pipeline` (all work here; `main` has only the initial scaffold)
- **Total iterations:** 
- **Total tasks completed:** 
- **Total tasks reverted:** 
- **Total human-added tasks:** 
- **Build duration:** 

## Review and Merge

All pipeline work is on the `build/agent-pipeline` branch. To review and merge:

```
# See everything the pipeline built
git log main..build/agent-pipeline --oneline

# Review the full diff against the initial scaffold
git diff main..build/agent-pipeline

# When satisfied, merge to main
git checkout main
git merge build/agent-pipeline

# If pushing to a remote
git remote add origin 
git push -u origin main
```

## APK Details
- **File path:** 
- **File size:** 
- **Min SDK:** 
- **Target SDK:** 
- **Permissions:** 

## Install on Device

### Prerequisites
1. Enable **Developer Options** on your Android phone:
   Settings > About Phone > tap "Build Number" 7 times
2. Enable **USB Debugging**:
   Settings > Developer Options > USB Debugging > ON
3. Connect your phone via USB cable
4. Set USB connection mode to **File Transfer (MTP)** -- not PTP, not charge-only.
   Most phones show a notification when you plug in. Tap it and select "File Transfer / MTP."
   ADB generally works over MTP. PTP (Picture Transfer Protocol) is for cameras and does not
   reliably support ADB on most devices.
5. Install ADB on your computer if not already present:
   - macOS: `brew install android-platform-tools`
   - Linux: `sudo apt install adb`
   - Windows: download from https://developer.android.com/tools/releases/platform-tools

### Install Command
\`\`\`
adb install 
\`\`\`

### Verify Connection
\`\`\`
adb devices
\`\`\`
Should show your device serial with "device" status. If it shows "unauthorized", unlock
your phone and accept the USB debugging permission

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [theultimateshyam](https://github.com/theultimateshyam)
- **Source:** [theultimateshyam/claude-skills](https://github.com/theultimateshyam/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-theultimateshyam-claude-skills-mobile-app-builder
- Seller: https://agentstack.voostack.com/s/theultimateshyam
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.