# Asc ASO audit Human Guide

## What This Is For
Run an offline ASO audit on canonical App Store metadata under ./metadata and surface keyword gaps using Astro MCP. It gives the agent a clearer input/output frame for asc ASO audit: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Asc ASO audit agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for asc ASO audit.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Asc ASO audit guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- 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.
- Read `references/aso_rules.md` to understand the rules each check enforces.
- Identify the **latest version directory** under `metadata/version/` (highest semantic version number). Use this for all version-level fields.
- The **primary locale** is `en-US` unless the user specifies otherwise.
- **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.
- Read `metadata/app-info/{locale}.json` for `subtitle` (and `name` if present)
- Read `metadata/version/{latest-version}/{locale}.json` for `keywords`

## Decision Points And Nuance
The original skill emphasizes: Preconditions, Before You Start, Metadata File Paths, Phase 1: Offline Checks, Keyword Waste, Optional: App Tag Alignment, Optional: Official Apple Search Plan, Underutilized Fields, Missing Fields, Bad Keyword Separators.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- **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.
- Run these 5 checks against the local metadata directory. No network calls required.
- Do not promise that changing metadata will immediately change Apple-generated tags.
- metadata coverage distinct. Do not infer organic rank or keyword difficulty
- Flag empty or missing required fields: `subtitle`, `keywords`, `description`, `whatsNew`.
- Do NOT flag: Latin-script keywords in non-Latin descriptions (e.g., "quran" in Cyrillic text) — these target separate search paths
- **Summary:** X errors, Y warnings across Z locales
- **Do not duplicate words already in title or subtitle.** Apple indexes all three fields together; repeating a word wastes keyword budget.

## Copy-And-Paste Prompt
```text
Use the Asc ASO audit human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the rorkai/app-store-connect-cli-skills skill entry for `asc-aso-audit`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# 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