Agent skills

---
name: ingest
description: >-
  Process unprocessed items from an intake inbox into reference notes, projects,
  a task tracker, or a calendar. Classifies each item as task, idea, reference,
  reminder, or noise; enriches with research; routes clear items and sends
  ambiguous ones to a clarification queue. Idempotent with stable processing ids.
  Use when the user says ingest, /ingest, process raw, or triage raw.
---

# Ingest

Turn provisional capture into enriched, routed knowledge and tasks. This is not filing: add context, connect to what you already know, research externally when useful, then route.

**Triggers:** `/ingest`, `ingest`, `process raw`, `triage raw`

## Suggested layers

Adapt names to the vault. The pattern matters more than the labels.

| Layer | Role |
|-------|------|
| Intake inbox | Unprocessed capture (lists, dumps, short notes) |
| Digesting | Interpretation and research in progress |
| Clarifications | Uncertain items awaiting a user choice |
| Processed log | Append-only audit trail of where items went |
| Destinations | Reference notes, project notes, task tracker, calendar |
| State | Idempotency ledger and failure records (local, gitignored) |

## Hard rules

1. **Enrich, don't transcribe** - outputs must be more useful than the raw line.
2. **Task tracker for action** - backlog, tries, and follow-ups belong in the tracker with context, not as a raw paste.
3. **Calendar only on explicit ask** - event only when raw names a date, reminder, or deadline. Never infer.
4. **No aggressive guessing** - ambiguity goes to clarification, not forced routing.
5. **Idempotent** - content-hash before create; never duplicate issues or notes.
6. **Safe failure** - leave intake intact (or keep digest stub), log failure, do not half-delete.
7. **Remove from intake only on success** - routed, clarified, or ignored with reason.
8. **Clear intake files after success** - leave capture files blank; no processed summaries in intake.
9. **Log to the processed audit trail** - append each run's routing table there.

## Steps

### 1. Discover

Scan intake. Skip digesting, the processed log, and already-processed items. One item per list line, `---` block, short note, or URL-only line.

Variants: `/ingest` all; `/ingest [file]` one file; `/ingest retry` failures; `/ingest resolve` after clarification answer.

### 2. Claim

Hash source + content. Skip if completed or clarifying (unless resolving). Write a digest stub; leave the raw line until completion.

```markdown
---
ingest_id: <hash>
source: intake/path
status: digesting
captured: YYYY-MM-DD
---

# Short title

## Raw capture
> verbatim raw text

## Classification
- Type: task | idea | reference | reminder | noise
- Project: (required for task/idea)

## Light score
*(task and idea only)*

| Size | Urgency | Class | Confidence |
|------|---------|-------|------------|

## Interpretation
## Research
## Planned outputs
```

### 3. Classify and lightly score

| Type | Primary destination |
|------|---------------------|
| Reference | Notes - not the task tracker |
| Idea | Ideas list; tracker only if Quick win or explicit "do it" |
| Task | Task tracker issue |
| Reminder | Calendar (explicit date only) |
| Noise | Ignore with reason |

Prefer task/idea over reference when the line implies ship, fix, investigate, or try.

**Light score** (task/idea): size, urgency, class - **Quick win**, **Strategic**, **Maintenance**, or **Distraction**. Relative priority only; no expected-value scorecard unless the user's system already defines one. Ambiguous home or Distraction vs Quick win that changes routing -> clarification. Search vault and tracker first.

### 4. Research

Always: related notes and open tracker issues. When useful: fetch URLs; look up people or tools. Cite in the stub.

### 5. Route or clarify

| Type | Destination |
|------|-------------|
| Reference | Notes only |
| Idea | Ideas list (+ tracker if Quick win / explicit action) |
| Task | Tracker issue (verb + object; context + `ingest_id`) |
| Reminder | Calendar only if date explicit |
| Clarification | Ambiguous home or material routing fork |
| Ignore | Duplicate or noise - log reason |

Clarification: move stub, ask short MCQ, create no destinations until resolved. Then create outputs, record, append processed log, delete clarification stub.

### 6. Complete

Create notes and issues (search first); calendar only when asked. Record destinations, remove from intake, append processed log, clear empty capture files, clean resolved clarifications.

```markdown
## YYYY-MM-DD - `To do.md`

3 items · 2 processed · 1 clarification

| Item | Type | Class | Result | Destinations |
|------|------|-------|--------|--------------|
| refresh landing copy | task | Quick win | done | tracker #142 · projects/site |
| new market experiment | idea | Strategic | clarifying | clarifications/<id> |
| article bookmark | reference | - | done | notes/topics/... |
```

On failure: mark stub failed; keep intake or stub; `/ingest retry` picks up failed hashes only.

## Do not

- Treat intake as lasting source of truth downstream
- Create calendar events without explicit date language
- File actionable tasks or ideas as reference-only
- Create tracker issues for pure references
- Leave processed summaries in intake
- Process digesting or the processed log as intake
- Skip idempotency on retry
- Auto-run every chat - only on trigger or schedule

## Related skills

- [vault-janitor](../vault-janitor/SKILL.md) - weekly hygiene
- [mine](../mine/SKILL.md) - landscape insights
- [prospect](../prospect/SKILL.md) - CI Accept/Reject gate

---
name: vault-janitor
description: >-
  Weekly and monthly vault hygiene for personal knowledge bases. Indexes notes,
  flags duplicates, stale projects, and archive candidates, writes a janitor
  report, and executes only explicitly approved moves. Use when the user says
  vault janitor, weekly review, compress vault, archive candidates, or
  /vault-janitor.
---

# Vault Janitor

Memory consolidation for a knowledge vault. The vault should get cleaner over time, not noisier.

## Hard rules

1. **Never delete** notes. Archive to a graveyard folder with an `archived_reason`.
2. **Never move or merge** without explicit user approval in the same session (for example `approve 1,3,5`).
3. **Read an index first**: do not scan the entire vault. Prefer a machine-built index plus targeted file reads.
4. **Protect link hubs**: notes with many inbound links are not archive candidates unless the user insists.
5. **Draft writes** go in a report or staging folder unless the user approves direct writes.

## Suggested vault layers

| Layer | Typical path |
|-------|--------------|
| Inbox | a capture folder for unfiled notes |
| Working memory | active projects / efforts |
| Long-term memory | reference / atlas notes |
| Graveyard | archived notes with reason metadata |
| Reports | dated janitor reports |

Adapt names to the vault you are cleaning. The pattern matters more than the folder labels.

## Step 1: Index

Build or refresh an index of titles, paths, frontmatter status, link counts, and hygiene flags. Review flags before deep reads.

## Step 2: Weekly mode (default)

1. Refresh the index.
2. Inspect flags and a small set of candidates only.
3. For semantic checks, read titles plus short excerpts for:
   - near-duplicate title clusters
   - meeting or log notes ready to compress
   - projects whose status no longer matches activity
4. Write a dated report with numbered suggested actions and an approval checklist.
5. Stop. Wait for approval before mutating files.

### Report sections (required)

```markdown
## Summary counts
## Duplicate / merge candidates (with survivor)
## Stale / abandoned projects
## Decisions that supersede older notes
## Compression candidates
## Archive candidates (orphan / unreferenced / expired)
## Inbox triage
## Suggested actions
## Approval checklist
```

## Step 3: Monthly compression

Run the weekly pass, then:

- Pick a few topic clusters from recent activity.
- Draft enduring reference notes that supersede scattered sources.
- Refresh one-paragraph current-state summaries on active project pages.

## Step 4: Execute approvals

When the user approves numbered actions:

1. Execute only the listed actions.
2. On archive: move to graveyard, set status and reason, update any index lists.
3. On merge: consolidate into the survivor, link superseded sources, archive leftovers.
4. Re-index after mutations and summarise what changed.

## Quality bar

Propose specific, evidenced actions. Prefer compression and clearer retrieval over collecting more notes. Leave link hubs alone unless asked.

---
name: mine
description: >-
  Explores a knowledge vault with a single thematic lens, synthesises up to 9
  candidate insights, and shows the top 3 by priority (gaps, contradictions,
  opportunities, stale notes). Read-only by default. Use when the user says
  mine, /mine, vault insights, or find gaps.
---

# Mine

Reflective vault exploration: find actionable or clarifying insights, not summaries. Read-only by default: propose changes; edit only when the user asks to act.

## Step 0: Pick the lens (required, state upfront)

Before searching, choose **one** focus:

| Source | Examples |
|--------|----------|
| User names it | "retention", "capacity", "partner risk" |
| Active project | highest-priority active effort |
| Reference notes | methodology, operating principles |
| Session context | open task tracker item, at-risk weekly budget |

If the user gives no lens, propose one from vault state and state it in the output header.

**Lens (one line)**: always the first line of the report.

## Search strategy

Search broadly; read narrowly.

1. Hub / map-of-content notes first.
2. Lens-targeted reads: project parent, decisions, recent weekly notes.
3. Keyword or semantic search across reference, projects, and calendar layers.
4. Optional: a vault index for stale projects, open-task drift, and hygiene flags when the lens fits.
5. Task tracker signals when the lens touches execution: active, overdue, waiting.

Read titles, frontmatter, decisions, and gaps: not every note verbatim.

## Insight types

Tag every insight with exactly one:

| Tag | Meaning |
|-----|---------|
| `observation` | Pattern or fact worth naming |
| `gap` | Missing doc, decision, link, or owner |
| `opportunity` | Positive change: experiment, link, distill, quest |
| `contradiction` | Two notes conflict; needs resolution |
| `stale` | Outdated vs newer source; refresh or archive candidate |

Insights must be specific: cite evidence, not generic advice.

## Priority filter (default: show top 3)

Synthesise up to **9** candidates, then rank and output only the **top 3** unless the user asks for more.

Rank by leverage on the stated lens: highest first:

1. Blocks active execution
2. Contradiction or gap on the critical path
3. Opportunity with a real time box
4. Stale note the lens actually depends on
5. Observation with no immediate action
6. Parked work only if nothing sharper exists

## Output format

```markdown
**Lens:** [one line]

1. **[type]**: [insight in one or two sentences]
   - **Evidence:** [paths or links]
   - **Action:** [optional one line (propose only)]

2. **[type]**: …

3. **[type]**: …

**If you act on one thing:** [single highest-leverage recommendation]
```

## Quality bar

**Good:** a concrete mismatch between a stated weekly win and a playbook last updated before a known change.

**Bad:** "You have a lot of notes about this topic."

## Do not

- Exceed 9 candidates in synthesis (or show more than 3 in default mode without a deep request)
- Run without stating the lens
- Output generic summaries
- Edit the vault unless the user asks to act on an insight

---
name: prospect
description: >-
  Discover a NEW continuous-improvement opportunity from vault and execution
  signals, form a testable hypothesis, gather evidence, then recommend Accept or
  Reject. Unlike mine (many insights, no decision), prospect ends in one A/R
  gate. Use /prospect for discovery; /prospect [item] to review an existing try.
---

# Prospect

**Discover → hypothesise → evidence → Accept/Reject.**

Search for improvement signals the way mine does, but synthesise **one new** continuous-improvement proposition and end with an Accept/Reject gate.

**Read-only default:** do not edit the vault or task tracker until the user replies **A** or **R**.

## Two modes

| Mode | Input | Behaviour |
|------|-------|-----------|
| **Discover** *(default)* | `/prospect` or `/prospect [lens]` | Find friction → novel proposition → hypothesis → A/R |
| **Review** | `/prospect [item]` | Assess an existing spark: adopt or skip |

## Discover mode

### Step 0: Lens

State one focus before searching (same sources as mine).

### Step 1: Discovery

Look for signals, not backlog items already queued:

| Signal type | What to look for |
|-------------|------------------|
| `friction` | Manual repeat steps, tool switches, duplicate tracking |
| `drift` | Vault says X, tracker or scorecard says Y |
| `waste` | Hours in the wrong bucket, stale active projects, abandoned tries |
| `missing loop` | Outcome with no measurement, decision with no review cadence |
| `automation gap` | A repeated chat pattern that could become a skill, script, or reminder |

**Hard rule:** the proposition must be novel relative to current state: not already an open try, not the obvious next quest on the project page.

Briefly note 2–3 runners-up so the search is visible.

### Step 2: Proposition

One line: verb + object + intended improvement. Tag the home project.

### Step 3: Hypothesis

> **If we accept**, we expect [measurable outcome] because [mechanism], within [time/cost bound].

> **If we reject**, we avoid [cost] and keep [status quo alternative].

Must be falsifiable and time-boxed.

### Step 4: Evidence

| Supports Accept | Supports Reject |
|-----------------|-----------------|
| cites | cites |

### Step 5: Certainty + A/R

| Score | Meaning |
|-------|---------|
| **High (75–100%)** | Strong, bounded, fits the week; no material contradictions |
| **Medium (40–74%)** | Worth a time-boxed try, or one missing fact |
| **Low (0–39%)** | Weak signal, duplicates existing work, or cost exceeds upside |

## Output format

```markdown
**Lens:** [one line]

**Proposition:** [new CI opportunity: one line]
*Novelty:* [why this is not already queued]

**Runners-up:** [1–3 one-liners]

## Hypothesis
[Accept case / Reject case]

## Evidence
| Supports Accept | Supports Reject |
|-----------------|-----------------|
| … | … |

**Gaps:** …

## Certainty
**[High | Medium | Low] (~N%)**: …

## Recommendation
**[Accept | Reject]**: …

### Options
- **(A)ccept**: create a bounded try with hypothesis and due date
- **(R)eject**: discard; log a one-line reason unless asked to write it down
```

## On Accept / Reject

- **Accept:** create one bounded try issue (or equivalent) plus a short vault stub with the hypothesis and due date.
- **Reject (Discover):** no vault write by default.
- **Reject (Review):** close the existing try and note the reason.

## vs mine

| | **mine** | **prospect** |
|---|----------|--------------|
| Output | Up to 9 insights, show top 3 | **One** novel proposition |
| Decision | None | **Accept / Reject** gate |
| Use when | Landscape scan | One improvement bet with a commit decision |

## Do not

- Default Discover mode to existing try backlog
- Exceed one proposition per run
- Auto-accept or auto-reject without **A** / **R**

---
name: android-release-notes
description: >-
  Generate Google Play Console release notes: gather user-facing changes,
  draft en-US within the 500-character limit, translate every listing locale
  your Play Console requires, output paste-ready locale XML. Use when the user
  asks for Android release notes, Play Store what's new, localised store listing
  updates, or Play Console upload copy. Do not improvise markdown-only notes;
  follow this skill.
---

# Android release notes (Play Console)

Produce **Google Play release notes** for the current build: one XML block per required listing locale, ready to paste into Play Console.

**This skill is mandatory** when the user requests Android / Play Store release notes. Do not write ad-hoc changelog markdown instead of Play XML.

## Suggested layers

Adapt names to your repo. The pattern matters more than the labels.

| Layer | Role |
|-------|------|
| Version source | Where `versionName` / `versionCode` (or equivalent) live |
| Change baseline | Git range or release train that defines "what's new" |
| Locale list | The locales your Play Console listing actually requires |
| Output artifact | Saved XML next to the release binary (version folder) |

## Default workflow

Agents **must** follow this order:

1. **Read this skill** — do not skip to freeform markdown.
2. Read version identifiers from your project's version source (for example `app/build.gradle`, `build.gradle.kts`, or a version file you maintain).
3. Gather commits / shipped changes since the baseline for this release train. Override the baseline when the default is wrong.
4. If the conversation includes **uncommitted or unreleased work** that will ship in this build, include it in en-US even if it is not yet in git.
5. Draft **en-US** release notes (≤500 characters): user-facing, 2–4 short lines. Do **not** paste commit subjects verbatim. No emoji (Play plain text).
6. **Human quality gate (recommended):** pause for a light English review before translating. Bad en-US fans out to every market.
7. Translate approved en-US into every other required listing locale (maintain a locale table in your repo; keep regional pairs distinct where needed).
8. **Save** XML beside the release artifacts (for example `release/<version>/release-notes.xml`).
9. **Deliver** the full XML in the chat response for copy-paste into Play Console (API upload is optional and separate).
10. Validate every required locale is present and each block is ≤500 characters.

## Trigger phrases

- "make the Android release notes"
- "generate release notes" / "write release notes" (Android / Play context)
- "Play Store what's new" / "Play Console release notes"
- "localised store listing" / "translate release notes"
- Preparing or uploading an Android release

## Do not

- Replace Play XML with informal markdown changelogs as the ship artifact
- Output only en-US when the listing has multiple locales
- Use emoji, markdown, or HTML inside locale blocks
- Paste raw git commit subjects into Play notes
- Include the version number in the note text (Play shows version separately)
- Publish secret paths, credentials, or private product internals into a public skill fork

## Required output format

```xml
<en-US>
...
</en-US>
<ar>
...
</ar>
```

Include **every** locale your Play Console listing requires. Max **500 characters** per block.

## Writing guidelines

- Lead with the most noticeable user benefit.
- Group related fixes ("Stability improvements and crash fixes" not eight separate crash lines).
- Drop internal-only work (refactors, CI, build tooling) unless it affects users.
- Keep regional variants appropriately distinct (for example `es-419` vs `es-ES`, `pt-BR` vs `pt-PT`, `en-US` vs `en-GB`).
- Translate from **en-US**, not from raw git messages.

### Commit hint → user-facing (examples)

| Commit hint | User-facing line |
|-------------|------------------|
| crash fixes | Stability improvements and crash fixes |
| offline assets | More content available offline |
| fix dismiss on upgrade screen | Fixed an issue with the upgrade screen |

### Example en-US

```
Stability improvements and crash fixes.
More content now works offline.
Upgrade and ad flows behave more reliably.
```

## Locale list

Do not hardcode another app's locale set. Maintain a small table or JSON file in **your** repo listing Play locale codes your console requires, and update it when Play adds or removes listing languages.

Treat unpublished or partially localised in-app languages the same as full ones for **store notes**: if Play lists the locale, emit a block.

## Quality check

- [ ] All required locale blocks present
- [ ] Each block ≤ 500 characters
- [ ] en-US reviewed before translation fan-out
- [ ] No emoji / markdown / HTML in blocks
- [ ] Version in the binary matches the notes you are uploading
- [ ] XML saved with the release artifacts

## Optional second pass

For languages you cannot read, a **second model** can surface translation queries only (odd calques, broken placeholders, missing benefit). It does not replace the English gate or your Accept before paste.

## Further reading

- Play Console release notes limits and paste flow (current Google documentation)
- Pair with an iOS What's New skill when you ship the same version on both stores

---
name: ios-whats-new-release-notes
description: >-
  Write consumer-friendly App Store Connect "What's New in This Version" copy
  in every required store locale. Use when the user asks for What's New text,
  iOS release notes, App Store Connect copy, or help filling localised release
  fields. Prefer this skill over engineering changelogs for store paste.
---

# What's New release notes (App Store Connect)

Write **consumer-friendly** App Store Connect "What's New in This Version" copy for an iOS app. Output is ready to paste into App Store Connect or for a browser agent to fill when the console is open.

## When to use

- User asks for "What's New", iOS release notes, or version notes for a ship
- User is on App Store Connect localization dropdown
- User wants notes translated into store locales, not engineering changelog language

## Suggested layers

| Layer | Role |
|-------|------|
| Change source | Git log, PR, or ship summary |
| English draft | Canonical U.S. English (or your primary store language) |
| Locale table | Exact App Store Connect header strings for your app |
| Output file | `version-notes-{version}.md` (or equivalent) for paste / Chrome fill |

## Workflow

1. **Gather the real changes** — read `git log`, a PR description, or ask the user. Separate user-visible benefits from internal work.
2. **Draft English (U.S.) first** — 2–4 short sentences or 2–3 bullets. Benefit-led, plain language.
3. **Human quality gate (recommended):** light English review before localisation. The English is the product of the quality gate; everything else is a fan-out.
4. **Localize every required locale** — maintain a locale table with **exact** App Store Connect header strings for your app.
5. Write `version-notes-{version}.md` (or your chosen artifact name) using the output template below.
6. **Offer Chrome fill** — if the user wants automation, output locales in fill order and use exact ASC labels.

## Voice and rules

**Do:**

- Lead with what users feel or get ("Faster load", "Now in your language", "Smoother browsing")
- Keep each locale short when possible (ASC allows 4000 characters; target roughly ≤350 for readability)
- Use natural, idiomatic phrasing per language — not word-for-word calques from English
- If a single market uses a different public brand name, use that name in **that locale only**

**Do not:**

- Use engineering terms: iOS (as jargon), localization, locale, L10n, bundle, cache, API, feed, catalogue, strings, UI, dSYM, CocoaPods, refactor
- List internal market counts or ISO codes as the story
- Name programming languages or file types
- Copy identical text for regional Spanish/Portuguese pairs when a natural regional tweak is easy

## Turning technical changes into user copy

| Technical change | Consumer-friendly angle |
|------------------|-------------------------|
| Added languages / markets | "The app is now available in more languages, including …" |
| Region-specific content | "More picks tailored to your region" |
| Locale resolution / mapping | Omit — users do not see this |
| Playback / caching | "Content loads faster and plays more reliably" |
| Crash fix on navigation | "Fixed a crash when switching between sections" |

If a release is **only** localisation, focus on languages and regional content — not implementation.

## Output template

```markdown
# What's New in This Version - {version}

Copy each block into the matching App Store Connect field.

---

**English (U.S.)**
\`\`\`
{copy}
\`\`\`

**English (U.K.)**
\`\`\`
{copy}
\`\`\`

…repeat for every required locale…
```

- Header labels must match App Store Connect **exactly** (including punctuation and parentheses).
- One fenced block per locale — easy copy-paste and Chrome targeting.

## Locale list

Do not hardcode another app's ASC set. Maintain a table in **your** repo:

- **Core** locales always present for this app
- **Extended** locales only when enabled in App Store Connect for the version

## Chrome fill

When the user wants notes entered in App Store Connect via browser:

1. Confirm they are on **App Store Connect → Apps → [App] → iOS App → Version → What's New**.
2. Work top to bottom through the localization dropdown using your locale table.
3. For each locale: select → focus What's New → paste fenced content (no fences) → save before switching.
4. Use a browser automation MCP only if available and ASC is open; otherwise deliver the markdown file for manual paste.

## Quality check

- [ ] English reads like an App Store listing, not a commit message
- [ ] No banned engineering terms in any locale
- [ ] Market-specific brand names only where required
- [ ] Every required locale present with matching header spelling
- [ ] No locale exceeds 4000 characters
- [ ] Notes file written for the version

## Optional second pass

For languages you cannot read, a **second model** can surface translation queries only. It does not replace the English gate or your Accept before paste into ASC.

## Pairing

When the same version ships on Google Play, run the Android Play release-notes skill for Play XML, then reuse the approved English benefit story for iOS What's New (rewritten for ASC voice and locale headers).

---
name: android-play-store-screenshots
description: >-
  Capture Google Play Console screenshots on fixed AVDs across phone and tablet
  size classes and UI languages, drive one product storyboard, post-process for
  Play size rules, and stage versioned PNGs for upload. Use when the user needs
  Play Store screenshots, localised store shots, phone / 7-inch / 10-inch
  listing media, or a repeatable capture matrix. Prefer this skill over ad-hoc
  emulator screenshots.
---

# Play Store screenshots (Android)

Produce **Google Play Console listing screenshots** for an Android app: fixed AVDs for phone and tablet slots, one scripted product storyboard, optional multi-language fan-out, and versioned PNG folders ready to paste into Play Console. **This skill never uploads to Play Console.**

## When to use

- User asks for Play Store screenshots, Play Console media, or listing screenshots
- Phone, 7" tablet, and/or 10" tablet slots need a full set
- Localised screenshots for every language the listing uses
- Replacing hand-captured emulator shots with a repeatable matrix

## Suggested layers

Adapt names to your repo. The pattern matters more than the labels.

| Layer | Role |
|-------|------|
| Staged APK / AAB artifact | Release binary from your RC pipeline (or an explicit path) |
| Device matrix | Deterministic AVD names for phone, 7" tablet, 10" tablet |
| Language matrix | Device / app locale per run (`--lang` / `--langs` or equivalent) |
| Storyboard | One scripted flow (UIAutomator, Maestro, Espresso, or equivalent) identical on every form factor |
| Output | `release/<version>/play-store-screenshots/<lang>/{phone,tablet-7,tablet-10}/` + README checklist |

## Agent contract (mandatory)

1. **Call the project capture script** (or create one that follows this skill). Do not invent a parallel ad-hoc recipe or swap AVD names casually.
2. Prefer a staged release APK. Do not rely on "whatever emulator is already open."
3. After a run, read the generated README checklist and surface pass/fail sizes + paths.
4. Fail the gate when a required Play slot is empty or fails size rules. Do not tell the user to upload an incomplete set.
5. **Never** auto-upload screenshots to Play Console from this skill.

## Default workflow

1. Resolve version and staged APK (or accept an explicit path).
2. Boot the fixed AVD set for the slots you need (phone; 7" and 10" when those listing wells are used).
3. For each language: set device locale (and app language if separate), install, dismiss consent / system / IME overlays, run the storyboard, capture screenshots.
4. Post-process to flat RGB PNG. Apply Play's phone aspect rule when needed (longest side ≤ 2× shortest).
5. Write per-language and index README checklists under the versioned output folder.
6. Tell the human where to upload in Play Console (Store presence → Main store listing → Graphics → Phone / 7" / 10" wells for each language).

## Device matrix (Play slots)

| Slot | Typical AVD class | Notes |
|------|-------------------|--------|
| Phone | Modern phone AVD (for example Pixel-class) | Portrait; crop if height exceeds 2× width |
| 7" tablet | 7-inch tablet AVD | Portrait and landscape when the listing uses both |
| 10" tablet | 10-inch tablet AVD | Portrait and landscape when the listing uses both |

Official graphics guidance: [Add preview assets to showcase your app](https://support.google.com/googleplay/android-developer/answer/9866151).

Boot AVDs **with audio** when a "playing" frame matters. Create missing AVDs once; keep names deterministic across machines.

## Languages

Maintain a language table in **your** repo mapping store codes → device locale (and any app-specific language override). Pass one language or a batch. Prefer a search/query string that returns content in that catalogue when the storyboard includes search.

## Storyboard design choices

- **Deterministic devices**, not whatever is already running
- **One scripted story**, identical across form factors
- **Overlay dismissal** before every shot (consent, system dialogs, IME)
- **Audio / playback** when a "playing" frame matters
- **Seeded state** when a later shot needs favourites or onboarding already done
- **Versioned artifacts + checklist** next to the release folder
- **Partial re-run modes** when only one slot or shot failed

## What not to copy from App Store pipelines

- Exact ASC native resolutions as the success criterion — Play cares about slot type and aspect rules
- A single iPad 13" class — Play uses separate phone / 7" / 10" wells
- Assuming Simulator language APIs — use AVD locale / `adb` locale helpers for Android

## After the run

1. Quote language(s), which slots are OK / FAIL, and exact paths.
2. Point the human to Play Console graphics wells for each language.
3. Keep ownership of review: layout breakage per locale and which shots earn a place on the listing still need a human.

## Do not

- Upload to Play Console from the skill
- Soft-pass an empty required tablet slot
- Hardcode another app's package name, resource IDs, or private product storyboard into a public fork
- Publish credentials, absolute home paths, or private release internals

## Related

- Pair with an App Store screenshots skill for iOS so both stores share the same product narrative
- Pair with Android release notes when the same ship also needs localised store copy

---
name: ios-app-store-screenshots
description: >-
  Capture App Store Connect screenshots on fixed Simulators across device size
  classes and UI languages, drive one product storyboard, verify ASC pixel
  sizes, and stage versioned PNGs for upload. Use when the user needs App Store
  screenshots, localised store shots, iPad 13-inch screenshots, ASC media, or
  "Unable to Add for Review" screenshot gaps. Prefer this skill over ad-hoc
  Simulator screenshots.
---

# App Store screenshots (iOS)

Produce **App Store Connect listing screenshots** for an iOS (or iPad-capable) app: fixed Simulator devices, one scripted product storyboard, optional multi-language fan-out, and versioned PNG folders ready for Media Manager. **This skill never uploads to App Store Connect.**

## When to use

- User asks for App Store screenshots, ASC media, or listing screenshots
- iPad 13" class is missing and Add for Review is blocked
- Localised screenshots for every store language the listing uses
- Replacing hand-captured Simulator shots with a repeatable matrix

## Suggested layers

Adapt names to your repo. The pattern matters more than the labels.

| Layer | Role |
|-------|------|
| Staged `.app` | Release binary from your RC pipeline (or an explicit `--app` path) |
| Device matrix | Deterministic Simulator names for each ASC size class |
| Language matrix | `--lang` / `--langs` → Simulator `AppleLanguages` + `AppleLocale` |
| Storyboard | One scripted flow (Maestro, XCUITest, or equivalent) identical on every form factor |
| Output | `release/<version>/app-store-screenshots/<lang>/{iphone,ipad}/` + README checklist |

## Agent contract (mandatory)

1. **Call the project capture script** (or create one that follows this skill). Do not invent a parallel ad-hoc recipe or swap device names casually.
2. Prefer a staged Release `.app`. Do not rely on "whatever Simulator is already open."
3. After a run, read the generated README checklist and surface pass/fail sizes + paths.
4. If the app supports iPad and the 13" set is missing → **fail the gate**. Do not tell the user to upload an incomplete set.
5. **Never** auto-upload screenshots to App Store Connect from this skill.

## Default workflow

1. Resolve version and staged `.app` (or accept an explicit app path).
2. Boot the fixed Simulator set for the slots you need (iPhone size class; iPad 13" when dual-family).
3. For each language: set Simulator language + region, uninstall/reinstall so UI strings pick up, dismiss overlays, run the storyboard, post-process to flat RGB PNG.
4. Verify each file matches an accepted ASC portrait size for that slot.
5. Write per-language and index README checklists under the versioned output folder.
6. Tell the human where to upload in App Store Connect (Media Manager → matching localization → iPhone + 13" iPad wells).

## Device matrix (ASC slots)

| Slot | Typical Simulator | Accepted portrait px (examples) |
|------|-------------------|----------------------------------|
| iPhone (largest class) | iPhone 16 Pro Max class | 1320×2868, 1290×2796, or 1260×2736 |
| iPad 13" | iPad Pro 13-inch (M4) class | 2064×2752 or 2048×2732 |

Official sizes: [Upload app previews and screenshots](https://developer.apple.com/help/app-store-connect/manage-app-information/upload-app-previews-and-screenshots).

iPhone is usually portrait-only for listing. iPad portrait is required when iPad is supported; landscape is optional.

## Languages

Maintain a language table in **your** repo mapping store codes → Simulator `AppleLanguages` / `AppleLocale` (and any app-specific i18n key aliases). Pass one language (`--lang`) or a batch (`--langs`). Prefer a search/query string that returns content in that catalogue when the storyboard includes search.

## Storyboard design choices

- **Deterministic devices**, not whatever is already running
- **One scripted story**, identical across form factors
- **Overlay dismissal** before every shot (ATT, StoreKit, onboarding, offline popups)
- **Audio / playback** when a "playing" frame matters
- **Versioned artifacts + checklist** next to the release folder
- **Partial re-run modes** when only one slot or shot failed

## What not to copy from Play Store pipelines

- Play's **longest ≤ 2× shortest** crop — ASC wants **native device resolutions**
- Separate 7"/10" tablet slots — ASC is iPhone + **one** iPad size class (13" when iPad is supported)
- UIAutomator text scraping — prefer accessibility IDs / Maestro `testID`s

## After the run

1. Quote language(s), which slots are OK / FAIL, and exact paths.
2. Point the human to App Store Connect → Previews and Screenshots for each localization.
3. Keep ownership of review: layout breakage per locale and which shots earn a place on the listing still need a human.

## Do not

- Upload to ASC from the skill
- Soft-pass a missing iPad 13" set when iPad is supported
- Hardcode another app's bundle ID, Maestro IDs, or private product storyboard into a public fork
- Publish credentials, absolute home paths, or private release internals

## Related

- Pair with a Play Store screenshots skill for Android so both stores share the same product narrative
- Pair with iOS What's New release notes when the same ship also needs localised store copy