The Shelf / App Store / App Store Keyword Engine
App Store Keyword Engine
Full ASO workflow: pull the real ranked apps, mine their tokens, rebuild your metadata.
The job: turn your agent into an ASO operator that works from the live App Store, not from vibes.
Most keyword advice fails the same way: somebody guesses what competitors target, stuffs a subtitle, and wonders why impressions never move. This skill makes the agent pull the actual top-ranked apps for every candidate keyword — iTunes Search API, iTunes Lookup, and the apps.apple.com subtitle scrape (with the anchoring trick that stops it grabbing a carousel app's subtitle by mistake, a trap we hit and documented). Then it tallies tokens across the top ten, builds a gap table, and rewrites your Name, Subtitle, and Keywords field character by character.
What's on the tag:
- The brand-defense check that runs before anything else — if your app doesn't rank #1 for its own name, everything downstream changes, and the skill diagnoses which of three root causes you've got.
- The intent-poisoning gate. The most expensive ASO mistake is a Name token that files your app in the wrong category's search results. One documented run caught a productivity app losing to six-figure-review journaling incumbents because of a single word in its Name. The gate catches it in minutes.
- Field-by-field build rules: singular-only keywords (Apple's stemming goes one direction), no token repeated across fields, keyword-first Name ordering for indies, the 250-char description front-load.
- A localization playbook for eight markets with the native head terms most foreign apps never ship — the German and Japanese category terms alone are why localized subtitles are the cheapest ranking win available.
- A rollout playbook that knows the sharp edges: which fields update live without review, and why creating a draft version without a build queued leaves you with a draft you can never delete. That one's from experience.
Who it's issued to: indie iOS developers and small studios whose listings are invisible in search, and anyone who wants quarterly ASO passes to be a one-prompt job instead of an afternoon of tab-juggling.
Why not a free directory download? Free skill files are pattern-matched boilerplate — nobody ran them. This workflow shipped real App Store listings, and every gotcha in it (the subtitle-scrape trap, the undeletable draft, the mid-review rename risk) was paid for on a live app. It's versioned and maintained; when Apple moves a limit or a surface, the skill gets updated and your locker gets the new copy.
Runs on free Apple endpoints. No ASO subscription required.
FIELD REPORT real output, not a promise
From a documented run of this workflow on a voice-notes app (Productivity category) that didn't rank in the top 20 for its own brand name. Excerpted and anonymized from the skill's own worked example — this is the Step 0 diagnosis, the Step 2.5 intent-poisoning gate, and the resulting gap-table actions, as produced.
Step 0 — Brand-defense check
Query: iTunes Search for the exact brand token, then the full live name. App absent from the top 20 on both.
Diagnosis (two root causes, combined):
- Velocity — 0 reviews, 11 days since launch. Apple's index weights install/review velocity; metadata cannot fix this directly. Path: post-accomplishment rating prompt + organic installs + time.
- Wrong-category framing in the Name — the live Name carried the token
Journal, filing the app into Health & Fitness / Lifestyle search results. The app is a Productivity app.
Step 2.5 — Intent-poisoning gate
| Search term | Top-3 category | App's category | Verdict |
|---|---|---|---|
voice journal |
Health & Fitness | Productivity | DROP |
ai journal |
Health & Fitness | Productivity | DROP |
audio diary |
Lifestyle / Health | Productivity | DROP |
voice memo ai |
Productivity | Productivity | KEEP |
ai voice notes |
Productivity | Productivity | KEEP |
ai note taker |
Productivity | Productivity | KEEP |
The journal/diary cluster — the terms the app was actually indexed for — resolves to a different category, where the top-3 results are journaling incumbents with six-figure review counts. No subtitle cleverness competes there. The Productivity-side terms are the right neighborhood.
Resulting actions
- Name: remove the
Journaltoken; rename the tagline portion to a category-matched head term ("AI Voice Note Taker" pattern) at the next binary bump — never mid-review. - Indexed package: keep all
journaltokens out of Name, Subtitle, and Keywords; rebuild around the three KEEP terms so cross-field combinations (voice+note+ai+memo) form the discoverable phrases. - Set expectations before deploy: because root cause #1 is velocity, the metadata fix is necessary but not sufficient — flagged to the owner before anything shipped rather than after.
That is the shape of every run: a live-data verdict table, an explicit action per token, and the honesty about what metadata can and cannot fix.
SERVICE RECORD living gear — updated as the factory learns
v1.0.0 — 2026-07-17
First issue. Ported from the factory's internal skill: sanitized for general use, methodology intact, field report captured from a real run.
Every update ships free to owners — your locker always serves the latest version.
QUESTIONS
Do I need a paid ASO tool?›
No. The whole workflow runs on free Apple endpoints — iTunes Search, iTunes Lookup, RSS charts, and the apps.apple.com page scrape. If you do run a paid tool, the skill tells you where its data slots in and which checks it still can't replace.
Does it push metadata to App Store Connect for me?›
The output is a complete paste-ready package plus a rollout plan. If your agent has your ASC API key, the skill documents the safe deploy order — including the gate that stops you from creating a draft version you can never delete.
Will this work outside finance/productivity apps?›
Yes. The workflow is category-agnostic; the finance examples are worked illustrations. The localization reference includes a generic per-locale procedure for any category.
What agents does it run on?›
Written for Claude Code, works in claude.ai Projects and Codex/AGENTS.md setups. It's plain markdown — any agent that reads instructions can follow it.