apple-app-store-aso

A Claude Code skill for Apple App Store metadata. Drafts it, validates it, won't make it up.

App Store Optimization advice on the open web is mostly recycled, half of it stale, and a good chunk of it written to sell a tracking tool. This skill is the opposite shape: a small set of rules Claude can apply, a current-as-of-2026 playbook, and a validator that fails loudly when you go over a character limit.

---

What this does

When you're preparing or revising an App Store Connect listing, this skill:

• Asks the few questions it needs (app purpose, top differentiators, target locale, existing copy if any), then drafts metadata for any field you ask for
• Always shows character counts inline as (X/LIMIT) — no guessing what's left in the keyword field
• Runs the validator on its own output before showing it to you, and revises any field that fails
• Surfaces the high-leverage things most ASO write-ups skip: the June 2025 algorithm shift to screenshot caption OCR indexing, that the description hasn't been indexed since iOS 11, that the keywords field wastes one character per comma-space you accidentally type

A taste of the playbook the skill draws from:

• Title carries highest ranking weight; subtitle is the second indexed field, not a tagline
• Keywords are comma-separated no spaces — every space is a wasted character of your 100
• Description isn't indexed for search; it's pure conversion copy (first 3 lines visible before "more")
• "Bug fixes and performance improvements" is a measurable conversion killer
• Trademarked competitor names in keywords → rejection under Apple Guideline 5.2.5
• Each locale has its own 100-character keyword budget; literal translation leaves traffic on the table

The full ruleset and the workflow are in SKILL.md. The current limits and best practices the skill cites live in references/.

---

What this is not

• Not a Google Play optimizer (out of scope on purpose)
• Not a keyword tracker or rank checker
• Not a screenshot generator
• Not a guarantee of anything — ASO is correlational at best, and the most rigorous study any consultant will quote was probably written before the algorithm changed last quarter

If you want claims about 10× downloads or guaranteed top-10 rankings, this skill is not for you.

---

Install

For Claude Code

git clone https://github.com/marcotini/apple-app-store-aso.git ~/.claude/skills/apple-app-store-aso

The skill auto-activates when you talk about App Store metadata, ASO, App Store Connect, keyword research for iOS, screenshot captions, or release notes for an Apple-platform app. You can also trigger it manually: "use apple-app-store-aso" or "help me with App Store metadata."

For Claude.ai (web/mobile)

Copy the contents of SKILL.md into a new Style at claude.ai → Settings → Styles. Reference files in references/ can be pasted into a Project alongside the Style for richer drafts.

---

Validator standalone

The character-limit validator works without the skill, for CI checks or quick spot-checks:

python3 scripts/validate_metadata.py \
  --app-name "Focus — Pomodoro Timer" \
  --subtitle "Deep work made easy" \
  --keywords "pomodoro,focus,timer,productivity,study" \
  --promotional-text "Spring sale: 50% off Pro." \
  --description "..." \
  --whats-new "..."

Exit code is 0 if every field passes, 1 if any fail (over limit, or spaces after commas in keywords). Pass no flags to run in interactive mode.

---

Repo layout

SKILL.md                  — skill definition, workflow, output format
references/
  apple-limits.md         — canonical App Store Connect character limits
  aso-playbook.md         — 2025–2026 ASO best practices
scripts/
  validate_metadata.py    — character-limit validator
CHANGELOG.md
CLAUDE.md                 — context for sessions working on this repo
LICENSE

---

License

MIT. See LICENSE. There's a non-binding note in the LICENSE asking that public derivatives keep the references current with whatever Apple is actually doing — stale ASO advice does real harm to small developers acting on it.

Contributing

PRs welcome. The two highest-value contributions are:

1. Updates to references/apple-limits.md whenever Apple changes a limit (App Store Connect UI is the source of truth; cross-reference Apple Developer documentation)
2. Updates to references/aso-playbook.md after each algorithm shift, with the date and a short note on what changed

New failure modes in SKILL.md based on real App Store rejections or real misses also welcome.