asc-aso-audit

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha c079831542f6 · 22 Oct 2026Report an issue or request a re-scan

• Publisherrorkai GitHub organizationOwner of the repository this skill is read from
• Source folderrorkai/app-store-connect-cli-skills/skills/asc-aso-auditThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictc079831542f6A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Run an offline ASO audit on canonical App Store metadata under `./metadata` and surface keyword gaps using Astro MCP. Use after pulling metadata with `asc metadata pull`.

---
name: asc-aso-audit
description: Run an offline ASO audit on canonical App Store metadata under `./metadata` and surface keyword gaps using Astro MCP. Use after pulling metadata with `asc metadata pull`.
---

# asc ASO audit

Run a two-phase ASO audit: offline checks against local metadata files, then keyword gap analysis via Astro MCP.
When available, include Apple-generated app tags as a discoverability signal.

## Preconditions

- Metadata pulled locally into canonical files via `asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"`.
- If metadata came from `asc migrate export` or `asc localizations download`, normalize it into the canonical `./metadata` layout before running this skill.
- For Astro gap analysis: app tracked in Astro MCP (optional — offline checks run without it).
- For Apple-generated discoverability tags: `asc app-tags list --app "APP_ID" --output json` works when the API returns tags for the app.

## Before You Start

1. Read `references/aso_rules.md` to understand the rules each check enforces.
2. Identify the **latest version directory** under `metadata/version/` (highest semantic version number). Use this for all version-level fields.
3. The **primary locale** is `en-US` unless the user specifies otherwise.

## Metadata File Paths

- **App-info fields** (`subtitle`): `metadata/app-info/{locale}.json`
- **Version fields** (`keywords`, `description`, `whatsNew`): `metadata/version/{latest-version}/{locale}.json`
- **App name**: May not be present in exported metadata. If `name` is missing from the app-info JSON, fetch it via `asc apps info list` or ask the user. Do not flag it as a missing-field error.

## Phase 1: Offline Checks

Run these 5 checks against the local metadata directory. No network calls required.

### 1. Keyword Waste

Tokenize the `subtitle` field (and `name` if available). Flag any token that also appears in the `keywords` field — it is already indexed and wastes keyword budget.

```
Severity: ⚠️ Warning
Example:  "quran" appears in subtitle AND keywords — remove from keywords to free 6 characters
```

How to check:
1. Read `metadata/app-info/{locale}.json` for `subtitle` (and `name` if present)
2. Read `metadata/version/{latest-version}/{locale}.json` for `keywords`
3. Tokenize subtitle (+ name):
   - **Latin/Cyrillic scripts:** split by whitespace, strip leading/trailing punctuation, lowercase
   - **Chinese/Japanese/Korean:** split by `、` `,` `,` or iterate characters — each character or character-group is a token. Whitespace tokenization does not work for CJK.
   - **Arabic:** split by whitespace, then also generate prefix-stripped variants (remove ال prefix) since Apple likely normalizes definite articles. For example, "القرآن" in subtitle should flag both "القرآن" and "قرآن" in keywords.
4. Split keywords by comma, trim whitespace, lowercase
5. Report intersection (including fuzzy matches from prefix stripping)

### Optional: App Tag Alignment

App tags are Apple-generated labels that can appear in search results and product pages. They are not editable ASO metadata, but they are useful evidence for whether Apple's classification matches the intended positioning.

```bash
asc app-tags list --app "APP_ID" --output json
asc app-tags view --app "APP_ID" --id "TAG_ID" --output json
```

Use tags as context only:
- If visible tags reinforce the subtitle/keyword strategy, note the alignment.
- If tags point to an unintended category or use case, recommend metadata/category changes that may improve future classification.
- Do not promise that changing metadata will immediately change Apple-generated tags.

### Optional: Official Apple Search Plan

When both App Store Connect and Apple Ads credentials are configured, use the
experimental, read-only plan to join the selected metadata with official paid
search evidence:

```bash
asc optimize search plan \
  --app "APP_ID" \
  --version "1.2.3" \
  --ad-account "AD_ACCOUNT_ID" \
  --country "US" \
  --genre "PRODUCTIVITY_UTILITIES" \
  --locale "en-US" \
  --out-dir ".asc/optimization/1.2.3" \
  --output markdown
```

- Authenticate App Store Connect with `asc auth` and Apple Ads separately with
  `asc ads auth login`; the two credential sets are independent.
- Treat the generated CSV and JSON files as review artifacts. The command does
  not apply metadata, exact keywords, or negative keywords, and partial Apple
  Ads source failures stay visible in the report.
- Keep Apple's popularity, app-specific paid reach, paid search outcomes, and
  metadata coverage distinct. Do not infer organic rank or keyword difficulty
  from this plan.

### 2. Underutilized Fields

Flag fields using less than their recommended minimum:

| Field | Minimum | Limit | Rationale |
|-------|---------|-------|-----------|
| Keywords | 90 chars | 100 | 90%+ usage maximizes indexing |
| Subtitle | 20 chars | 30 | 65%+ usage recommended |

```
Severity: ⚠️ Warning
Example:  keywords is 62/100 characters (62%) — 38 characters of indexing opportunity unused
```

### 3. Missing Fields

Flag empty or missing required fields: `subtitle`, `keywords`, `description`, `whatsNew`.

Note: `name` may not be in the export — only flag it if the app-info JSON explicitly contains a `name` key with an empty value.

```
Severity: ❌ Error
Example:  subtitle is empty for locale en-US
```

### 4. Bad Keyword Separators

Check the `keywords` field for formatting issues:
- Spaces after commas (`quran, recitation`)
- Semicolons instead of commas (`quran;recitation`)
- Pipes instead of commas (`quran|recitation`)

```
Severity: ❌ Error
Example:  keywords contain spaces after commas — wastes 3 characters
```

### 5. Cross-Locale Keyword Gaps

Compare `keywords` fields across all available locales. Flag locales where keywords are identical to the primary locale (`en-US` by default) — this usually means they were not localized.

```
Severity: ⚠️ Warning
Example:  ar keywords identical to en-US — likely not localized for Arabic market
``

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/rorkai/app-store-connect-cli-skills
git -C app-store-connect-cli-skills checkout c079831542f6

Works in

1. 2026-10-22
   ✓SAFE B 89 / 100

   first audit · source c079831542f6

Questions about asc-aso-audit

• github.com/rorkai/app-store-connect-cli-skills/tree/main/skills/ — the audited source at commit c079831542f6 and every finding aboveObserved · 22 Oct 2026

Spotted something wrong? Report a correction · Methodology