asc-aso-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

asc ASO audit

asc ASO 审核

Run a two-phase ASO audit: offline checks against local metadata files, then keyword gap analysis via Astro MCP.

执行两阶段ASO审核：针对本地元数据文件的离线检查，以及通过Astro MCP进行的关键词缺口分析。

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).

已通过

asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"

将元数据拉取到本地标准文件中。

如果元数据来自
```
asc migrate export
```
或
```
asc localizations download
```
，请先将其标准化为
```
./metadata
```
的标准目录结构，再运行此skill。
若要进行Astro缺口分析：应用需在Astro MCP中被追踪（可选——即使没有也可运行离线检查）。

Before You Start

开始之前

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.

阅读
```
references/aso_rules.md
```
，了解各项检查所遵循的规则。
找到
```
metadata/version/
```
下的最新版本目录（语义化版本号最高的那个）。所有版本级字段均使用此目录中的内容。
除非用户另行指定，否则主区域设置为
```
en-US
```
。

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.

应用信息字段（
```
subtitle
```
）：
```
metadata/app-info/{locale}.json
```

版本字段（

keywords

、

description

、

whatsNew

）：

metadata/version/{latest-version}/{locale}.json

应用名称：导出的元数据中可能不存在。如果应用信息JSON中缺少
```
name
```
字段，请通过
```
asc apps info list
```
获取或询问用户。不要将其标记为字段缺失错误。

Phase 1: Offline Checks

第一阶段：离线检查

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

对本地元数据目录运行以下5项检查。无需网络调用。

1. Keyword Waste

1. 关键词浪费

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:

Read

metadata/app-info/{locale}.json

for

subtitle

(and

name

if present)

Read

metadata/version/{latest-version}/{locale}.json

for

keywords

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.
Split keywords by comma, trim whitespace, lowercase
Report intersection (including fuzzy matches from prefix stripping)

对

subtitle

字段（以及可用的

name

字段）进行分词。标记同时出现在

keywords

字段中的任何分词——该关键词已被索引，会浪费关键词额度。

Severity: ⚠️ Warning
Example:  "quran"同时出现在副标题和关键词中——从关键词中移除可节省6个字符

检查方法：

读取

metadata/app-info/{locale}.json

中的

subtitle

（以及存在的

name

）

读取

metadata/version/{latest-version}/{locale}.json

中的

keywords

对副标题（+名称）进行分词：
- 拉丁/西里尔字母脚本：按空格拆分，去除首尾标点，转为小写
- 中文/日文/韩文：按
```
、
```
```
，
```
```
,
```
  拆分或逐个遍历字符——每个字符或字符组为一个分词。空格分词不适用于CJK语言。
- 阿拉伯语：按空格拆分，同时生成去除前缀的变体（移除ال前缀），因为Apple可能会对定冠词进行标准化。例如，副标题中的"القرآن"应标记关键词中的"القرآن"和"قرآن"。
将关键词按逗号拆分，去除空格，转为小写
报告交集（包括前缀去除后的模糊匹配）

2. Underutilized Fields

2. 字段利用率不足

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

标记使用量低于建议最小值的字段：

字段	最低要求	上限	理由
Keywords	90字符	100	使用率达90%+可最大化索引效果
Subtitle	20字符	30	建议使用率达65%+

Severity: ⚠️ Warning
Example:  关键词长度为62/100字符（62%）——有38个字符的索引机会未被利用

3. Missing Fields

3. 字段缺失

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

标记为空或缺失的必填字段：

subtitle

、

keywords

、

description

、

whatsNew

。

注意：

name

可能不在导出内容中——仅当应用信息JSON明确包含

name

键且值为空时才标记错误。

Severity: ❌ Error
Example:  en-US区域设置的副标题为空

4. Bad Keyword Separators

4. 关键词分隔符错误

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

检查

keywords

字段的格式问题：

逗号后有空格（
```
quran, recitation
```
）
使用分号而非逗号（
```
quran;recitation
```
）
使用竖线而非逗号（
```
quran|recitation
```
）

Severity: ❌ Error
Example:  关键词中逗号后有空格——浪费3个字符

5. Cross-Locale Keyword Gaps

5. 跨区域设置关键词缺口

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

How to check:

Load keywords for all locales
Compare each non-primary locale against the primary
Flag exact matches (case-insensitive)

比较所有可用区域设置的

keywords

字段。标记与主区域设置（默认

en-US

）关键词完全相同的区域设置——这通常意味着未进行本地化。

Severity: ⚠️ Warning
Example:  ar区域设置的关键词与en-US完全相同——可能未针对阿拉伯市场本地化

检查方法：

加载所有区域设置的关键词
将每个非主区域设置与主区域设置进行比较
标记完全匹配的项（不区分大小写）

6. Description Keyword Coverage

6. 描述关键词覆盖率

Check whether keywords appear naturally in the

description

field. While Apple does not index descriptions for search, users who see their search terms reflected in the description are more likely to download — this improves conversion rate, which indirectly boosts rankings.

Severity: 💡 Info
Example:  3 of 16 keywords not found in description: namaz, tarteel, adhan

How to check:

Load
```
keywords
```
and
```
description
```
for each locale
For each keyword, check if it appears as a substring in the description (case-insensitive)
Account for inflected forms: Arabic root matches, verb conjugations (e.g., "memorizar" ≈ "memorices"), and case declensions (e.g., Russian "сура" ≈ "суры")
Report missing keywords per locale — recommend weaving them naturally into existing sentences
Do NOT flag: Latin-script keywords in non-Latin descriptions (e.g., "quran" in Cyrillic text) — these target separate search paths

检查关键词是否自然出现在

description

字段中。虽然Apple不会将描述用于搜索索引，但看到搜索词出现在描述中的用户更有可能下载应用——这会提高转化率，间接提升排名。

Severity: 💡 Info
Example:  16个关键词中有3个未在描述中找到：namaz, tarteel, adhan

检查方法：

加载每个区域设置的
```
keywords
```
和
```
description
```
对每个关键词，检查其是否作为子字符串出现在描述中（不区分大小写）
考虑词形变化：阿拉伯语词根匹配、动词变位（如"memorizar"≈"memorices"）以及格变化（如俄语"сура"≈"суры"）
报告每个区域设置中缺失的关键词——建议将其自然融入现有句子
无需标记：非拉丁描述中的拉丁关键词（如西里尔文本中的"quran"）——这些针对不同的搜索路径

Phase 2: Astro MCP Keyword Gap Analysis

第二阶段：Astro MCP关键词缺口分析

If Astro MCP is available and the app is tracked, run keyword gap analysis. Run this per store/locale, not just for the US store — keyword popularity varies dramatically across markets.

如果Astro MCP可用且应用已被追踪，运行关键词缺口分析。请针对每个商店/区域设置运行，而不仅仅是美国商店——不同市场的关键词受欢迎程度差异极大。

Steps

步骤

Get current keywords: Call
```
get_app_keywords
```
with the app ID to retrieve tracked keywords and their current rankings.
Ensure multi-store tracking: For each locale with a corresponding App Store territory (e.g.,
```
ar-SA
```
→ Saudi Arabia,
```
fr-FR
```
→ France,
```
tr
```
→ Turkey), use
```
add_keywords
```
to add keyword tracking in that store. Without this,
```
search_rankings
```
returns empty for non-US stores.
Extract competitor keywords: Call
```
extract_competitors_keywords
```
with 3-5 top competitor app IDs to find keyword gaps. This is the highest-value Astro tool — it reveals keywords competitors rank for that you don't. Run this per store when possible.
Get suggestions: Call
```
get_keyword_suggestions
```
with the app ID for additional recommendations based on category analysis.
Check current rankings: Call
```
search_rankings
```
to see where the app currently ranks for tracked keywords in each store.
Diff against metadata: Compare suggested and competitor keywords against the tokens present in
```
subtitle
```
,
```
name
```
(if available), and
```
keywords
```
fields from the local metadata.
Surface gaps: Report all gaps ranked by popularity score (highest first). Include the source (competitor analysis vs. suggestion).

获取当前关键词：调用
```
get_app_keywords
```
并传入应用ID，获取已追踪的关键词及其当前排名。
确保多商店追踪：对于每个有对应App Store地区的区域设置（如
```
ar-SA
```
→沙特阿拉伯、
```
fr-FR
```
→法国、
```
tr
```
→土耳其），使用
```
add_keywords
```
在该商店中添加关键词追踪。如果不这样做，非美国商店的
```
search_rankings
```
将返回空值。
提取竞品关键词：调用
```
extract_competitors_keywords
```
并传入3-5个顶级竞品应用ID，找出关键词缺口。这是Astro最有价值的工具——它能揭示竞品排名但你的应用未覆盖的关键词。尽可能针对每个商店运行此操作。
获取建议：调用
```
get_keyword_suggestions
```
并传入应用ID，基于品类分析获取额外推荐。
检查当前排名：调用
```
search_rankings
```
查看应用在各商店中已追踪关键词的当前排名。
与元数据对比：将建议的关键词和竞品关键词与本地元数据中
```
subtitle
```
、
```
name
```
（若可用）和
```
keywords
```
字段中的分词进行对比。
呈现缺口：按受欢迎度得分从高到低报告所有缺口。注明来源（竞品分析或建议）。

Cross-Field Combo Strategy

跨字段组合策略

When recommending keyword additions, consider how single words combine across indexed fields (title + subtitle + keywords). For example:

Adding "namaz" to keywords when "vakti" is already present enables matching the search "namaz vakti" (66 popularity)
Adding "holy" to keywords when "Quran" is in the subtitle enables matching "holy quran" (58 popularity)

Flag high-value combos in recommendations.

在推荐添加关键词时，考虑单个词如何在索引字段（标题+副标题+关键词）中组合。例如：

当
```
vakti
```
已存在时，将"namaz"添加到关键词中，可匹配搜索词"namaz vakti"（受欢迎度66）
当副标题中已有"Quran"时，将"holy"添加到关键词中，可匹配搜索词"holy quran"（受欢迎度58）

在推荐中标记高价值组合。

Skip Conditions

跳过条件

Astro MCP not connected → skip with note: "Connect Astro MCP for keyword gap analysis"
App not tracked in Astro → skip with note: "Add app to Astro with
```
mcp__astro__add_app
```
for gap analysis"
Store not tracked for a locale → add tracking with
```
add_keywords
```
before querying

未连接Astro MCP→跳过并提示："连接Astro MCP以进行关键词缺口分析"
应用未在Astro中被追踪→跳过并提示："使用
```
mcp__astro__add_app
```
将应用添加到Astro以进行缺口分析"
区域设置对应的商店未被追踪→先使用
```
add_keywords
```
添加追踪，再查询

Output Format

输出格式

Present results as a single audit report. The report covers only the latest version directory.

undefined

将结果整理为一份审核报告。报告仅涵盖最新版本目录。

undefined

ASO Audit Report

ASO审核报告

App: [name] | Primary Locale: [locale] Metadata source: [path including version number]

应用： [名称] | 主区域设置： [区域设置] 元数据来源： [包含版本号的路径]

Field Utilization

字段利用率

Field	Value	Length	Limit	Usage
Name	...	X	30	X%
Subtitle	...	X	30	X%
Keywords	...	X	100	X%
Promotional Text	...	X	170	X%
Description	(first 50 chars)...	X	4000	X%

字段	值	长度	上限	使用率
名称	...	X	30	X%
副标题	...	X	30	X%
关键词	...	X	100	X%
推广文本	...	X	170	X%
描述	(前50个字符)...	X	4000	X%

Offline Checks

离线检查

#	Check	Severity	Field	Locale	Detail
1	Keyword waste	⚠️	keywords	en-US	"quran" duplicated in subtitle

Summary: X errors, Y warnings across Z locales

#	检查项	严重程度	字段	区域设置	详情
1	关键词浪费	⚠️	keywords	en-US	"quran"在副标题中重复出现

摘要： 共X个错误，Y个警告，涉及Z个区域设置

Keyword Gap Analysis (Astro MCP)

关键词缺口分析（Astro MCP）

Keyword	Popularity	In Metadata?	Suggested Action
quran recitation	72	❌	Add to keywords

关键词	受欢迎度	是否在元数据中？	建议操作
quran recitation	72	❌	添加到关键词

Recommendations

建议

[Highest priority action — errors first]
[Next priority — keyword waste]
[Utilization improvements]
[Keyword gap opportunities]

undefined

[最高优先级操作——先处理错误]
[次优先级——关键词浪费问题]
[利用率提升]
[关键词缺口机会]

undefined

Notes

注意事项

Offline checks work without any network access — they read local files only.
Astro gap analysis is additive — the audit is useful even without it.
Run this skill after
```
asc metadata pull
```
to ensure canonical metadata files are current.

For keyword-only follow-up after the audit, prefer the canonical keyword workflow:

asc metadata keywords diff --app "APP_ID" --version "1.2.3" --dir "./metadata"

asc metadata keywords apply --app "APP_ID" --version "1.2.3" --dir "./metadata" --confirm

asc metadata keywords sync --app "APP_ID" --version "1.2.3" --dir "./metadata" --input "./keywords.csv"

when importing external keyword research

After making changes, re-run the audit to verify fixes.
The Field Utilization table includes promotional text for completeness, but no check validates its content (it is not indexed by Apple).

离线检查无需网络访问——仅读取本地文件。
Astro缺口分析是附加功能——即使没有它，审核也有价值。
需在执行
```
asc metadata pull
```
后运行此skill，以确保标准元数据文件是最新的。

审核后若仅需处理关键词，建议使用标准关键词工作流：

asc metadata keywords diff --app "APP_ID" --version "1.2.3" --dir "./metadata"

asc metadata keywords apply --app "APP_ID" --version "1.2.3" --dir "./metadata" --confirm

导入外部关键词研究时使用

asc metadata keywords sync --app "APP_ID" --version "1.2.3" --dir "./metadata" --input "./keywords.csv"

修改后重新运行审核，验证修复效果。
字段利用率表格包含推广文本以保证完整性，但没有检查会验证其内容（Apple不会对其进行索引）。