--- name: screenshot-optimization description: Plan an app Product's App Store screenshot set — per-slot message, caption copy, order, device sizes — plus A/B hypotheses to run as a Product Page Optimization test. Use for "what should my screenshots show", "screenshot captions", "redesign my screenshots", "screenshot A/B test", "brief my designer", "did the new screenshots work". For the autoplay video use app-preview-video; for the icon use app-icon-optimization. metadata: version: 1.0.0 --- # Screenshot Optimization Turn the Product's positioning into the screenshots that convert a product page visitor into a download. Output is one `listing` Proposal per screenshot set you change, which a designer or the User produces, uploads in App Store Connect and marks done the day it goes live, plus a **brief** with the design direction, the competitor audit and the **A/B hypotheses** the User runs as a Product Page Optimization test. Judge every screenshot, the Product's and the competitors', from the picture itself with `view_image`. ## Gather 1. `read_context` — positioning, ICP, the three benefits that matter most, voice, brand colors, competitors. 2. `connector_asc_screenshots` when the ASC Connector exists — the Product's screenshot and preview sets per localization and display type, in slot order. Look at every slot of the primary locale's sets with `view_image`: the screen shown, the caption burned into it, the layout. Without the Connector, the public screenshots come from iTunes, as below. 3. The public screenshots, through `fetch_url` on iTunes: Lookup (`https://itunes.apple.com/lookup?id=&country=`) for the Product when `read_product_state` gives its App Store Surface's `appId`, Search (`https://itunes.apple.com/search?term=&entity=software&country=&limit=1`) by name otherwise and for each competitor named in the Foundation doc. Each result's `screenshotUrls` and `ipadScreenshotUrls` come in slot order: look at each competitor's first three with `view_image` for the competitor audit. No read returns a competitor's previews: mark them unknown. 4. `connector_asc_analytics` when the ASC Connector exists — page conversion per source (search, browse, referrer), read as `pageDownloads` ÷ `pageViews`, 30 days plus trend: the baseline the new set must beat. Without it, say the baseline is unknown and name it as the first number to read after the test starts. 5. `app_store_reviews` — the words users use for the outcome, and one quotable line for the social-proof slot. ## Plan the set A visitor decides in 3–6 seconds; the first three slots show in search results before any tap and carry most of the decision. The slot roles, effective first-slot patterns, caption and layout rules are in [`references/slot-framework.md`](references/slot-framework.md) — read it before assigning slots. Device sizes, counts and file rules are in [`references/device-sizes.md`](references/device-sizes.md) — read it when writing the Apply section or when the sets show a device without screenshots. Assign the slots in this order: 1. **Slot 1, the hook** — the benefit headline plus the screen that proves it. The caption answers "what does this do for me". 2. **Slots 2–3, core value** — the two next benefits from the Foundation doc, each on its own screen. 3. **Slots 4–7, feature showcase** — one feature per slot, formula `benefit headline + feature UI + supporting detail`. 4. **Slots 8–9, trust and differentiation** — rating, review quote, press, awards; the angle competitors leave open per the audit. 5. **Slot 10, close** — recap or the offer ("Start your free trial"). Caption copy: 4–6 words, benefit over feature name, one idea per slot, zero words repeated from slot to slot, in the Product's voice. Every caption is a claim the screen behind it shows. What neither the reads nor the pictures tell you — a screen the app may lack, the state a screen can be captured in, the audience a slot speaks to — is an assumption: state it as one in the brief and plan on it. ## A/B hypotheses Write three hypotheses, one variable each, ranked by expected lift: first-slot message (benefit vs social proof vs problem statement), caption style (benefit vs feature), layout (full-bleed vs framed device vs split). Each hypothesis states the variant, the reason drawn from the audit or the reviews, the metric (product page conversion), and the read-out rule: Product Page Optimization takes up to three treatments against the default, runs up to 90 days, and a treatment needs at least a week and Apple's confidence indicator before it is declared. ## Output: one Proposal per set, and the brief Each screenshot set you change is one `propose` with `appStoreField: "screenshots"`. Its `content` names the display type and locale, then one block per slot: ``` Slot N — [role] Caption: "[copy]" (words: N) Screen: [which app screen, which state loaded] Layout: [portrait/landscape, framed/full-bleed, caption position] Eye lands on: [the one element] ``` Its `why` names what the new set should move and the baseline it must beat. The brief, saved with `save_output`, carries the reasoning: - **Assumptions** — each one, and the slot it bears on. - **Design brief** — palette from the Foundation doc, type recommendation, background style, device frame choice, the caption copy for every slot in one list the designer pastes. - **Competitor audit** — table: screenshot count, preview yes/no, first-slot type, caption style, design quality (1–10, from the pictures), angle claimed — Product vs each competitor — and the angle left open. - **A/B hypotheses** — the three above, ready to enter as PPO treatments. - **Apply** — App Store Connect → the version → App Previews and Screenshots per device; screenshots ship with a version, PPO treatments do not need one. Done when every changed set has its Proposal, every slot in it has a caption within the word rule and a named screen, the first three slots read as a complete pitch on their own, the audit scores every competitor from the Foundation doc from its pictures, and the brief names the baseline conversion or states that it was unavailable. ## Read-out: did the change work A screenshot change is judged on the reports that follow it. When you write a report, read out every screenshot change the User applied and every product page optimization experiment, before planning the next set: 1. `read_proposals` with `category: ["listing"]` — the screenshot Proposals in state `done`, known by their slot plan; `doneAt` is the day the set went live. 2. `connector_asc_product_pages` — each experiment's `startDate` and `endDate`. Apple's API returns no experiment result, so an experiment is read like a change, from its dates; while it runs, its treatments get only `trafficProportion` of the traffic, so a shift is diluted by that share. 3. `read_outputs` with `kind: "report"` — the earlier reports: which changes already have a verdict, and which were left pending. 4. `connector_asc_analytics` with `from` and `to`, once for the window before the day and once for the window from it — in `execute_typescript`, product page conversion per source type, `pageDownloads:` ÷ `pageViews:`, and overall. Choose the two windows, and decide whether the change is readable yet; until it is, its read-out is pending. Apple's reports run a day or two late, so the Series may stop short of today. Write the read-out into the report you save with `save_output`: the change and its day, both windows, and per source the page views, the page downloads, the conversion before and after and the change in points; then the verdict, or the day the change becomes readable. The next Run finds a pending read-out through `read_outputs` and takes it up. Done when every screenshot Proposal marked done and every experiment without a verdict in an earlier report has, in this report, a verdict or the day it becomes readable. ## Related Skills - `app-preview-video` — the autoplay video that occupies the first slot when present. - `app-icon-optimization` — the icon shown beside the first three screenshots in search. - `custom-product-pages` — screenshot variants per audience or campaign. - `localization` — translated captions per storefront.