---
name: appshot
description: Create production-ready App Store creative assets from real app captures, supplied images, app metadata, localization inputs, and experiment results. iOS and watchOS only. Use for local screenshot studios, App Store listings, WidgetKit/watch previews, locale matrices, validation, review approvals, packaging, publishing dry-runs, and analytics-informed variant iteration.
voice_triggers:
  - use appshot
  - appshot screenshots
  - app store screenshots
---

# appshot

App Store screenshots from real captures.

## Purpose

Use this skill to build a local creative automation workflow for mobile store assets. The default deliverable is a runnable Next.js review studio plus deterministic export, validation, packaging, and reporting artifacts. Keep the workflow local-first: capture or import real product UI, compose store-ready variants, review them on localhost, export only approved assets, and generate upload-ready folders or dry-run publishing plans.

This skill can scaffold local workflows, scripts, templates, validations, review artifacts, publishing helpers, and analytics importers. It should not operate hosted accounts, realtime collaboration, cloud queues, credential vaults, billing, public APIs, or scheduled ingestion.

## Preamble (run first)

Check for skill updates before starting the main workflow:

```bash
_UPD=$(skills/appshot/bin/appshot-update-check 2>/dev/null || ~/.codex/skills/appshot/bin/appshot-update-check 2>/dev/null || ~/.claude/skills/appshot/bin/appshot-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true
```

If output is `JUST_UPGRADED <old> <new>`, tell the user `Running appshot v<new> (just updated).` and continue.

If output is `UPGRADE_AVAILABLE <old> <new>`, ask whether to upgrade now:

- **Upgrade now**: run `skills/appshot/bin/appshot-upgrade` from this repo, or the matching installed helper path if this is a copied/global skill install. Continue the original workflow after the upgrade finishes.
- **Always keep me up to date**: run `appshot-config set auto_upgrade true`, then run `appshot-upgrade`. Future `UPGRADE_AVAILABLE` checks should auto-run the upgrade without asking.
- **Not now**: write a snooze record to `~/.appshot/update-snoozed` using `<new> <level> <epoch>`, where level escalates from 1 to 3 for the same version. Continue the current workflow.
- **Never ask again**: run `appshot-config set update_check false` and continue the current workflow.

When `appshot-config get auto_upgrade` returns `true`, skip the prompt and run `appshot-upgrade` automatically. If automatic upgrade fails, continue with the current installed version and tell the user to run the upgrade manually.

## Core Workflow

**Standalone-mode preamble.** If the user already has the standalone server
running (they ran `appshot` themselves, the wizard at `:4173/wizard`
is on screen, or they're driving the review studio directly), your job is to
*help inside that session* — answer questions, edit configs, suggest copy.
Do not re-scaffold or restart their server. The agent recipe below is for
sessions where the user has delegated the whole flow to you.

The unified entry point is the `appshot` CLI at
`skills/appshot/bin/appshot` (it's also reachable as
`~/.codex/skills/appshot/bin/appshot` or
`~/.claude/skills/appshot/bin/appshot` in installed-skill
contexts). All subcommands accept `--json` so you can parse responses
without scraping prose.

1. **Scaffold.** Translate the brief into `snapshot.config.json` and copy
   the studio template into the user's app root:

   ```bash
   appshot init --brief "<brief>" --app-root <app-root> --json
   ```

   `init` delegates the brief → config translation to
   `assets/next-template/lib/brief-to-config.ts` — a deterministic,
   schema-aware library. Do not hand-write `snapshot.config.json` from
   scratch; let `init` do it, then edit only the fields the brief leaves
   ambiguous. For supplied-image mode (no Xcode project), drop the
   `--app-root` flag and pass `--out <dir>`.

2. **Capture (optional).** When an Xcode project is available, populate
   `public/captures/` from the Simulator:

   ```bash
   appshot discover --app-root <app-root> --json
   appshot capture --kind ios --app-root <app-root> --project <studio-dir> --json
   # Repeat with --kind widgets / --kind watch as the brief calls for.
   ```

   For supplied-image flows, copy the user's PNGs into
   `<studio-dir>/public/captures/` instead. Read
   `references/marketing-scenes.md` for native marketing, widget mock, and
   watch scene authoring detail.

3. **Hand off to the user.** Start the studio and point them at the URL:

   ```bash
   appshot start --project <studio-dir> &
   ```

   Tell the user to open `http://127.0.0.1:4173/`, pick variants, and
   confirm selections inside the review studio. The studio's
   `POST /api/selection` already runs `export:selected →
   validate:assets → package:assets`, so finalising is the user's click,
   not a chore you need to drive.

4. **Wrap up.** When the user reports the selection is saved, tell them
   the final zip is at `<studio-dir>/dist/app-store-assets.zip`. If they
   ask for publishing dry-runs or analytics summaries, run
   `npm run publish:plan:apple` or `npm run analytics:import` from the
   studio dir — those still ship as npm scripts on the studio (see the
   demo block below).

For slides tagged `layout: "appscreen-3d"`, run
`scripts/plan_appscreen_variants.py prompt` and `apply` to author the
per-slide `appscreenParams` after step 1. Schema:
`references/appscreen-params.md`.

The pre-CLI Python-by-Python recipe (calling each script in sequence by
hand) is preserved at `references/agent-fallback.md` for the rare case
the CLI is missing or broken — but `appshot` is the canonical
entry now, and reaching for the fallback should be a deliberate
choice.

## Reference Map

Load only the reference needed for the current task:

- Apple screenshot dimensions and upload rules: `references/apple-specs.md`
- Widget, watch, and complication preview guidance: `references/widget-guidelines.md`
- Template schema and layout DSL: `references/template-dsl.md`
- Copy, ASO order, and quick localization guidance: `references/copy-localization.md`
- Full localization workflow, glossary, RTL, and completeness checks: `references/localization-workflow.md`
- Native scene scaffolding and route prefixes: `references/marketing-scenes.md`
- Validation checklist currently shipped with the skill: `references/validation.md`
- Expanded compliance validation rules and warning taxonomy: `references/compliance-validation.md`
- Local review studio states, comments, approvals, and selected-only export: `references/review-workflow.md`
- Publishing dry-runs, folder layouts, and credential boundaries: `references/publishing.md`
- Analytics imports, experiment summaries, and next-variant recommendations: `references/analytics-import.md`
- Baseline Next.js screenshot workflow lessons: `references/parthjadhav-app-store-screenshots.md`
- 3D device mockup parameters (vendored YUZU-Hub/appscreen): `references/appscreen-params.md`
- Pre-CLI Python-by-Python recipe (fallback only, kept for audit): `references/agent-fallback.md`

When current store compliance matters, verify live Apple documentation before asserting exact requirements.

## Design Rules

- Lead with the strongest user outcome, then core workflow, differentiators, trust proof, and ecosystem surfaces.
- Each slide sells one idea. Split copy that tries to sell two benefits.
- Vary the deck rhythm across screenshot fill, framed device, panoramic, feature graphic, badge or callout, before-after, widget, and watch layouts.
- Store screenshots are ads grounded in real UI, not documentation panels.
- Keep headlines large, readable after downscaling, benefit-led, and concrete.
- Avoid dense feature lists, unsupported claims, price or ranking claims, and store badges unless the target store explicitly allows them.
- For RTL locales, set locale direction, mirror ordering where appropriate, and align text naturally.
- Landscape screenshots should use a clear caption and one primary product surface; avoid crowded side-by-side device layouts.

## Output Defaults

- Apple defaults are iPhone and iPad screenshot sets plus optional WidgetKit/watch previews. Read `references/apple-specs.md` and `references/widget-guidelines.md`.
- Custom outputs may define exact width, height, format, naming, and package path when a campaign or press kit needs a nonstandard target.
- Supported final formats should remain explicit per output. Prefer PNG for lossless UI, JPEG when store constraints or file size call for it, and WebP only for custom surfaces that accept it.

## Bundled Resources

- `bin/appshot`: **Unified CLI entry point.** Subcommands: `init`,
  `discover`, `capture`, `start`, `export`, `doctor`, `upgrade`,
  `config`. Use this in preference to invoking the Python/npm scripts
  directly — it composes them with one set of conventions across the
  standalone, Claude, and Codex flows.
- `assets/next-template/`: Next.js + Tailwind renderer and local review studio.
  Boots into a first-run wizard at `/wizard` when launched with
  `APPSHOT_MODE=bootstrap` (the CLI does this automatically when no
  project resolves).
- `assets/next-template/lib/brief-to-config.ts`: Canonical brief → starter
  config library. Both `appshot init` and the wizard call it; do not
  duplicate this logic in agent prompts.
- `VERSION`: current installed skill version for update checks.
- `bin/appshot-update-check`: Compares the local skill version to the canonical GitHub version with cache, snooze, and opt-out handling.
- `bin/appshot-config`: Reads and writes updater preferences in `~/.appshot/config.json`.
- `bin/appshot-upgrade`: Updates git checkouts or copied skill installs from the canonical repository.
- `scripts/scaffold.py`: Copies the renderer template and creates starter config from a brief.
- `scripts/discover_xcode.py`: Detects Xcode projects, schemes, bundle IDs, simulator runtimes, widgets, previews, and Watch targets.
- `scripts/profile_project.py`: Writes `snapshot.project.json` from Xcode metadata and Swift source scanning.
- `scripts/plan_routes.py`: Writes `snapshot.routes.json` with route IDs, confidence, strategies, source files, and output paths.
- `scripts/install_harness.py`: Adds an idempotent native snapshot harness and scene scaffolds.
- `scripts/capture_simulator.py`: Captures iPhone/iPad app UI, marketing scenes, and widget mocks in Simulator.
- `scripts/capture_widgets.py`: Crops widget mock captures to widget bounds when possible.
- `scripts/capture_watch.py`: Captures watch routes from paired watch simulators.
- `scripts/validate_assets.py`: Validates exported PNG/JPG dimensions, opacity, and nonblank pixels.
- `scripts/package_exports.py`: Creates packaged export archives.
- `scripts/plan_appscreen_variants.py`: Emits the prompt + per-slide briefs the calling agent feeds to a model, then merges the model-authored `appscreenParams` back into `snapshot.config.json`.
- `scripts/sync_appscreen.py`: Refreshes the vendored YUZU-Hub/appscreen tree from upstream while preserving the one-file fork delta.
- `assets/next-template/public/vendor/appscreen/`: Vendored MIT-licensed fork of [YUZU-Hub/appscreen](https://github.com/YUZU-Hub/appscreen), driven headlessly by the studio for 3D iPhone mockup variants. The vendored renderer ships additional device profiles upstream, but only `device3D: "iphone"` is exposed by this skill. See `assets/next-template/public/vendor/appscreen/UPSTREAM.md`.

## Demo (KeyTimes)

When the user asks to "run the appshot demo" or similar, scaffold a
studio against the bundled `examples/keytimes/` content. Supplied-image
mode only — the demo never touches an Xcode project.

1. Read `examples/keytimes/KeyTimes.md` for the brief and per-slide intent.
2. Scaffold via the CLI:
   ```bash
   appshot init \
     --brief "Screenshots for KeyTimes. $(sed -n '3p' examples/keytimes/KeyTimes.md)" \
     --out demo-studio --force --json
   ```
3. Replace the generated starter with the curated demo config and drop in
   the demo captures:
   ```bash
   cp examples/keytimes/snapshot.config.json demo-studio/snapshot.config.json
   mkdir -p demo-studio/public/captures
   cp examples/keytimes/captures/*.png demo-studio/public/captures/
   ```
4. Start the studio (installs deps on first run, then opens at
   `http://127.0.0.1:4173/`):
   ```bash
   appshot start --project demo-studio
   ```
5. After the user picks variants in the studio, the studio's
   `POST /api/selection` runs export/validate/package automatically. The
   final zip lands at `demo-studio/dist/app-store-assets.zip`.

## Agent Notes

- Prefer `snapshot.project.json`, `snapshot.routes.json`, and `snapshot.selection.json` over rediscovering or reselecting work.
- Treat `npm run dev:review` as the human approval checkpoint for final assets. `npm run export:selected` requires a saved review selection; use `APPSHOT_ALLOW_DEFAULT_SELECTION=1` only for explicitly requested draft automation.
- Prefer config, template, capture route, and locale edits over one-off image generation.
- Ask before shipping final assets when every source image is placeholder-only.
- Keep credentials local and ignored. Publishing helpers may plan and dry-run uploads, but real uploads require user-owned local environment variables or credential files.
- Do not copy proprietary templates, branding, copy, or assets from commercial screenshot tools.