App Store metadata (YAML source of truth)

All App Store Connect metadata for this app is declared in sectioned YAML under ./metadata/. Treat these files as the authoritative pre-population — App Store Connect is a downstream projection of this directory, never the reverse.

Why this exists

Populating App Store Connect manually on every release leaks state, wastes time, and loses locale parity. This skill replaces guessing with a versioned, reviewable pre-population:

• Every ASC field has a canonical home — one YAML file per ASC section.
• Every file tracks its own _status — so we know what's synced, what's drafted, and what diverged.
• Every push command is documented — the skill maps each section to the asc subcommand that pushes it, or flags it as manual_only when no API exists.

This skill never stores app-specific copy inline; it points at the files. Copy lives in ./metadata/, and any research should live in project-local references.

When to use

Invoke on any of these triggers:

• Creating or editing App Store copy, subtitle, keywords, description, promo text, or What's New
• Preparing a new version for submission (asc release, asc submit)
• Auditing whether ASC is in sync with the repo
• Adding a locale or an IAP/subscription
• Changing pricing, category, age rating, review info, or privacy declarations
• Before asc metadata push — verify the YAML passes schema checks
• After asc metadata pull — reconcile drift into the YAML

Directory layout

metadata/
├── app.yaml                       # app identity (name, bundle, sku, primary locale, platforms, content rights)
├── version.yaml                   # current version info (versionString, copyright, releaseType, releaseDate)
├── categories.yaml                # primary + secondary category
├── age-rating.yaml                # age rating declarations
├── content-rights.yaml            # third-party content declaration
├── encryption.yaml                # export compliance (ITSAppUsesNonExemptEncryption + exemptions)
├── privacy.yaml                   # App Privacy (data categories × purposes × linkage × tracking)
├── pricing.yaml                   # price point + territory availability
├── review-info.yaml               # review contact + demo account + reviewer notes
├── testflight.yaml                # beta license, feedback email, beta description, review contact
├── screenshots.yaml               # per-device-class manifests, paths to PNG/MP4 assets
├── locales/
│   ├── en-US.yaml                 # per-locale copy: subtitle, description, keywords, promo, whatsNew, URLs
│   └── <other-locales>.yaml
├── iap/
│   └── <product-id>.yaml          # one file per IAP: type, price, review screenshot, localizations
├── subscriptions/
│   └── <group-ref-name>.yaml      # one file per subscription group, with its subscriptions nested
├── status.yaml                    # auto-generated rollup (do not edit by hand)
└── README.md                      # link back to this skill

Before you edit anything

1. Read reference/apple-requirements.md to confirm the field exists, is required, and stays inside its character limit.
2. Read reference/sections.md to confirm the correct YAML file + asc push command.
3. Read reference/status.md to understand the _status block you'll be updating.
4. If copy is user-facing, also load the content-composer skill — banned phrases and voice rules apply.

Before you push

1. asc auth doctor — authentication is live (uses the cookie session stored by apple-developer-auth).
2. Run asc metadata validate --dir ./metadata for the sections asc natively supports (app info + version localizations).
3. For sections asc does not cover (privacy, age rating, review info, IAP, subscriptions, screenshots, TestFlight), confirm the section's _status.state is ready and follow the section-specific push command documented in reference/sections.md.
4. After each push, update _status.last_synced and flip _status.state to synced.

Status model — short form

Each section YAML begins with:

_status:
  state: draft            # missing | draft | ready | synced | diverged | asc_only | manual_only | not_applicable
  last_synced: null       # ISO-8601 UTC timestamp of last successful push
  last_source: local      # local | asc
  asc_id: null            # ASC resource ID, once known
  notes: ""               # human explanation when state != synced

Full state machine + transitions: reference/status.md.

Workflow entry points

Full recipes live in reference/workflow.md.

Do not

• Do not edit the ASC web UI first. If someone else does, run asc metadata pull and reconcile — do not overwrite the YAML silently.
• Do not delete sections without an entry in the PR description explaining what they were replaced by.
• Do not inline copy into SKILL.md or code. Copy lives in metadata/locales/.
• Do not push a section whose _status.state is draft or missing. Flip to ready first.
• Do not hand-edit status.yaml — it is regenerated from the _status block in each section file.

Related skills

• asc-metadata-sync — wraps the asc metadata pull/push commands (Phase 1: app-info + version localizations only)
• asc-aso-audit — Phase-1 offline ASO audit on the same ./metadata/ tree
• asc-whats-new-writer — writes whatsNew into metadata/locales/*.yaml
• asc-localize-metadata — fans en-US copy out to other locales
• asc-release-flow — the submit sequence after metadata is ready
• app-store-preflight — final preflight against this directory
• content-composer — enforced on every copy field