Store listing text

The name, subtitle and keyword field decide which searches the app can appear in. The description decides nothing in search on iOS; it is read by the few people who open the page and scroll, and by the App Review team. Write each field for the job it actually does.

Paths are relative to this skill's folder unless they start with store/ (the app's own launch folder).

What you deliver

store/copy/<locale>.json for each locale:

{
  "name": "Brand: Descriptive Phrase",
  "subtitle": "Second phrase, new words",
  "keywords": "single,words,no,spaces,after,commas",
  "promotionalText": "…",
  "description": "…",
  "whatsNew": "…"
}

and a clean run of node scripts/check-copy.mjs store/copy (add --first-version for an app's first release, which has no release notes).

Start from the research

Read store/research/aso-report.md (from aso-research). It names the phrase to own, the keyword list per storefront, the category and the locales. If it does not exist, run that skill first. The rules behind every choice below are in ../aso-research/references/aso-knowledge-base.md; read the sections on fields and on cross-localization before writing.

Who decides what

The name, subtitle and keyword field of every locale come from the research report, already approved by the owner in the proposal message. Copy them in as they are. They are the app's identity and only change with a new version, so do not reopen them here; if one turns out not to work (over a limit, reads badly beside the description), raise it with the owner as a change to the proposal. If the report is missing a locale that is now wanted, do that country's research the way aso-research describes, and get the same approval.

Everything else in the listing is yours to write.

The English master

Write en-US first. The rules for the three approved fields are repeated here because you will be checking them, and writing them when a locale is added later:

• Name (30). Brand, then the strongest phrase exactly as people type it: Brand: Shared Grocery List. An exact phrase in the name is the heaviest ranking signal there is, and a new app with no ratings can reach page one on it. Check how the store treats the brand word alone (store-research.mjs rank us "<brand>"): if search rewrites it to a bigger brand, say so to the owner; the descriptive half of the name is then what gets the app found.
• Subtitle (30). A second phrase made of words not in the name. It is shown under the name on the search card, so it must read as a sentence fragment a person understands, not a keyword pile.
• Keywords (100). Words separated by commas with no spaces after them. Apple's field reference says 100 bytes, which would make accented and non-Latin letters cost more; in practice a 100-character field with accents has been accepted. Write to 100 characters and shorten if App Store Connect refuses. Never repeat a word from the name, the subtitle or the category: Apple counts repeats and plurals as duplicates, and by every vendor's observation words combine across the three fields into phrases. No competitor names or trademarks: Apple forbids it (2.3.7), may strip them, and rejects listings for it. To be found on a rival's name, that is what Apple Ads is for. Skip "app", "free" and filler words.
• Promotional text (170). The only field that can change without a new version. Use it for the plain pitch now and for news later.
• Description (4000). First two lines carry the pitch (the rest sits behind "more"). Then short sections with a capitalised heading each, one per benefit, in the order of the screenshots. End with the pricing truth and the legal links.
• Release notes. What changed, as a user would say it, most important first. Real notes for real features; "bug fixes and improvements" only when that is all there is.

Rules that are not negotiable

• Every claim is true today. For each feature sentence, find the feature in the current code. Text advertising a feature that was removed is a 2.3 rejection waiting to happen.
• "Free" is a claim. An app with a paywall is "free to start" or "free with optional Pro", never "free". Keep even that out of the name and subtitle, where reviewers treat it as a pricing word; the promotional text and description can carry it.
• Subscriptions need two links in the description (or the EULA field): Terms of Use and Privacy Policy. If the app uses Apple's standard licence, the terms link is https://www.apple.com/legal/internet-services/itunes/dev/stdeula/. Their absence is one of the most common subscription rejections.
• No awards, rankings, user counts or testimonials that cannot be verified. Do not invent them and do not accept invented ones.
• No mention of other platforms, no prices that will differ by country, no "new" or "sale".
• Name the languages the app supports in the last lines of the description; it helps conversion in non-English stores.

Localize

Localizing is two different jobs:

1. Keywords, name and subtitle are researched, not translated. People in Germany do not search for the German translation of the English keyword; they search what Germans type. That research is in the report; take the three fields from it.
2. Description, promo text and release notes are translated for meaning and tone, keeping the structure.

Run one subagent per locale, in parallel, each writing only its own file and looping on the checker. When the app itself is being translated in the same launch, that comes first for each language (app-localization), so the listing can use the app's words. Give each agent:

• the English master and the research report's section for that storefront, including the approved name, subtitle and keywords;
• the app's own translation file for that language, so the listing uses the same words as the app's buttons;
• the limits, and the instruction to keep the same paragraphs, the same bullets and the same links;
• the claim rules above;
• "there is no native speaker on the team: you are the check. List any line you are unsure of."

Locale choices that are worth more than they look:

• Spanish (Mexico) counts in the US store, along with eight other locales Apple lists for it, and observers find their keyword fields are searched there. It is the usual second keyword field for the US. It is also shown to Spanish-speaking users in the US, so it must be a real Spanish listing, not English keywords in a Spanish slot. Keep each target phrase inside one locale; words are not known to combine across two.
• en-GB applies in almost every store outside the US, Canada and Japan; give it British vocabulary ("shopping list", not "grocery list") rather than a copy of en-US.
• The table, and how sure each row is, is section 4 of the knowledge base. That a store's extra locales are searched is industry observation, not Apple's statement; say so if asked.
• A locale that already exists and that you are not optimising still needs its description and release notes refreshed, or it will advertise the old version. List it under textOnlyLocales in store/asc.json.

Check

node scripts/check-copy.mjs store/copy [--first-version] [--subscription] [--category "lifestyle,productivity"]
                                       [--rivals "planta,picturethis"] [--text-only ar-SA]

Pass --subscription when the app sells one, the chosen categories, and the competitors' names from the research. It fails on anything over a limit, missing fields, keyword waste (spaces, duplicates, plurals, words already in the name, subtitle or category), competitor names, pricing words or ranking claims in the name or subtitle, other platforms, prices in the text, missing legal links for a subscription app, and translations whose links, paragraph count or bullet count drifted from the base. Fix every failure; read the notes and act on the ones that matter.

It ends by listing the description's section headings as feature claims to tick off. Do that now: find each one in the current code. A claim you cannot find is removed from every locale, or the launch stops until the feature exists. Do not ship the text with a note that it was not verified.

Then read each file once as a person. The checker cannot see a subtitle that is within limits and says nothing, or one that is two keywords glued together. For languages nobody on the team reads, have the translating agent explain each headline choice back in English and judge that.

Hand over

Entering the text into App Store Connect is the app-store-connect skill: asc.mjs info (names, subtitles, categories) and asc.mjs text (the rest). Name, subtitle, keywords and category go live only when a new version is approved; promotional text goes live the moment it is saved.