aso-analysis
ASO performance for an app or collection — current tracked-keyword positions and category rank, keyword opportunities with competitor context, an interactive add-keyword loop (the only write path), and honest metadata suggestions. Emits a structured findings.json plus a self-contained HTML report. Trigger on "ASO report", "keyword rankings", "keyword opportunities", "how do we rank for <keyword>", "suggest keywords to add".
How do I install this agent skill?
npx skills add https://github.com/appfollow/appfollow-ai-toolkit --skill aso-analysisIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill performs App Store Optimization (ASO) analysis and provides keyword suggestions. It includes a user-confirmed write path for updating tracked keywords. A low-severity risk of indirect prompt injection exists as the skill processes external app metadata and user-provided text to generate reports.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
aso-analysis
Read using-appfollow first (session, write ritual, error codes).
Inputs
- scope: app, whole collection, or a user-chosen subset of apps from one collection (e.g. "just
these 3 apps from my <collection>"). For a subset: resolve the collection via
list_collections, list its apps vialist_apps, then gather ASO data for only the chosen apps — emitscope.type: "collection_subset"withcollection_nameset andapps= the chosen subset (not the full collection). Spanning multiple collections in one report is not supported yet (deferred). - countries: default 1 primary.
- devices: App Store →
iphone,ipad; Google Play →android. - keyword seeds (optional).
Default depth
Estimate ≈ A×C×D×[S×P×12 (list_keywords) + S×12 (get_rankings)] + A×C×[K_seed×12 (suggestions) + K_serp×12 (search)] + A(as)×12 (search_ads) + A×12 (aso report, optional). Default = deep:
S=1 (today only — the report is a current snapshot), max K_serp=10. A single app/country/device at
deep with one keyword page and 10 seed suggestions ≈ 288 cr on the App Store (276 cr on
Google Play, which has no Search Ads read), ASO report included. quick/standard only on explicit
user request (degrade K_serp 10→5).
Current snapshot only (no trend section)
The report is a current snapshot: buckets TOP3 / TOP10 / TOP30 / TOP100 / UNRANKED, effectiveness
tiers, competitor gaps and today's category rank. Read list_keywords and get_rankings for today
only (no date). The template's category rank section takes each app's current rank from
get_rankings (category, feed type, position, row date) and nothing over time; the HTML/method
footer states plainly that trend-over-time is unavailable pending a historical endpoint. Never
re-read today's data under a past-date label.
Add-keyword loop (the ONLY write path)
- Propose a table of ≤15 candidate keywords; the user explicitly selects (never auto-add).
edit_keywordsREPLACES the tracked keyword set for(apps_id, country, device)— any keyword not in the CSV is dropped. Never send only the new candidates.- Per
(country, device): read the current set withlist_keywords({ext_id, country, device})withoutdate(today), paging until exhausted. Read it fresh before each preview, even if an earlier read exists: after anyedit_keywordson the same(apps_id, country, device)the old read is stale and would drop what that edit added. Current set = every tracked keyword in the response, ranked AND unranked (no_pos) — dropping the unranked ones deletes them on REPLACE. Any page fails → stop, no write. - CSV = current set ∪ selected (dedupe, case-insensitive).
edit_keywords_preview({country, device, keywords CSV, apps_id})— always passapps_idexplicitly (omitting it defaults to the account's first collection — a wrong-collection hazard). A size refusal (VALIDATION_ERRORnaming a byte limit) → stop and tell the user. Never split the set across calls (each call replaces the set; only the last chunk would survive) and never trim current keywords to fit unless the user names which to drop (then list them as dropped). - Show what the call replaces: collection, current keywords kept (count), added list, dropped = none.
list_keywordsreads byext_idand does not say which collection it read. Checklist_collections+list_apps: if the app sits in more than one collection, the current set may belong to another collection — do not claim dropped = none; say so, and write only on the user's explicit acceptance (otherwise stop). Get approval. - Before
edit_keywords, re-readlist_keywordsas in step 3 (no upstream revision check exists). If the set changed since step 3, go back to step 4 (rebuild, re-preview, re-approve). Thenedit_keywordswith verbatim args + the token. OnCONFIRMATION_REQUIRED→ re-preview. edit_keywordsis a Keywords-Edit action (not Advanced-gated), so this works on Keywords-Edit plans. Positions appear next parse cycle; offer an optional live SERP spot-check of ≤3 keywords. Applied batches → findingsstatus:"applied".
Metadata optimization — honest read ladder (suggestions only; no metadata write exists)
Most-reliable last:
- Own SERP card via
aso_search_results(title / subtitle / genre; no description) — unverified. - User paste — the only reliable current-metadata source today. The App Store keyword field is developer-private: always pasted or skipped.
Output per field: CURRENT → SUGGESTED + keywords gained/lost + rationale + localization risk + "apply in App Store Connect / Play Console."
Keyword effectiveness tiers (print the real definitions verbatim in the footer)
Tier every tracked keyword by the real list_keywords.effectiveness field only — WORTH IT
(effectiveness > 20) vs SKIP (effectiveness <= 20); sort by effectiveness descending within
each tier. effectiveness (0–100) is AppFollow's Keyword Effectiveness Index weighing popularity
against competition; above 20 is worth putting in the app title/subtitle (see the support article
below).
Show popularity and difficulty as informational context columns only — they never drive the
tier:
- Popularity (0–100): search-traffic score. Scale is exponential/non-linear; AppFollow doesn't recommend keywords scoring below ~20.
- Difficulty (0–100): how hard the keyword is to rank Top-10 for. Higher = tougher.
There is no public composite formula. Effectiveness, popularity, and difficulty are
AppFollow-computed values surfaced as-is from list_keywords — state this plainly in the report.
Link the reader to the support article for what each score means:
https://support.appfollow.io/hc/en-us/articles/360020831817-Keyword-Tracking.
list_keywords.score (usually null, an undocumented secondary "AF score") is shown as a secondary
display value only and never feeds the tier. Every finding carries expected_impact{metric, direction, magnitude, confidence, basis:"effectiveness-v1"} and reproducible
evidence[]{source:"mcp:<tool>", args, observed, at}.
Optional tools
aso_featured_apps is optional and outside the depth estimate above: call it only when the user asks for
featured placements. It needs ext_id plus either country or both from and to, and costs 12 cr per
started 14 days of the window, at least 12 (the using-appfollow skill's references/costs.md); country
alone reads the default 30-day window, 36 cr.
get_aso_report_app_store / get_aso_report_gdc_google_play are optional. On any error from these
tools, mark the section "n/a".
Emit
Produce aso-analysis-<scope>-<date>.html (fill references/report-template.html) + findings.json
(appfollow.toolkit.findings/v1, report_type:"aso"). The findings.json must conform to the
using-appfollow skill's references/findings.schema.json before it is written. Deliver by what the
host can do: if it can write files, write them and state the paths; if it renders HTML artifacts,
publish the HTML report as one; otherwise give the Markdown report in the reply (or in the host's
document surface, when it has one); whenever findings.json was not written to a file, include it in a
fenced json block. Tell the user their own connected agent can file the findings into their tracker.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/appfollow/appfollow-ai-toolkit/aso-analysis">View aso-analysis on skillZs</a>