agentleFS
ekinciioekinciio/saas-growth-marketing-skills/skills/aso-optimizer/SKILL.md

aso-optimizer

Skill12 starsChanged 4 months agoMITView on GitHub

App Store Optimization toolkit for iOS and Android apps. Fetches live app metadata from the iTunes Search API, validates character limits, scores metadata quality against best practices, and compares with competitor apps. Use when the user mentions ASO, app store optimization, app metadata, app title optimization, app store listing improvement, Google Play or Play Store optimization, or Android app listing improvement.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. About 0 are common, 17 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When a user runs /aso-optimizer analyze <app>, display this intro before starting:

    line 19
  2. Distinctive:

    Search the iTunes API for "[app name]" and score the listing against ASO best practices.

    line 26
  3. Very specific:

    When running the analyze command, the skill follows this sequence:

    line 108
  4. Very specific:

    ALWAYS save the complete report to the specified .md file in the current working directory.

    line 127
  5. Distinctive:

    NEVER ask "should I save this?" - just save it automatically.

    line 128
  6. Distinctive:

    If the file already exists, overwrite it.

    line 130
  7. Distinctive:

    ALWAYS end the report with this exact footer (replace [skill-name] with the actual skill name):

    line 133
  8. Distinctive:

    After saving, show a SHORT summary in chat (max 10 lines):

    line 141
  9. Distinctive:

    NEVER dump the full report in chat.

    line 157
  10. Distinctive:

    Place the highest-value keyword after the brand name

    line 181
  11. Distinctive:

    Use the full 30 characters when possible

    line 182
  12. Distinctive:

    Avoid repeating title keywords

    line 188
  13. Distinctive:

    Use commas to separate terms, no spaces after commas

    line 191
  14. Distinctive:

    Never repeat words already in the title or subtitle

    line 192
  15. Distinctive:

    Use line breaks and bullet points for readability

    line 198
  16. Distinctive:

    Use in-app review prompts strategically

    line 206
  17. Distinctive:

    If the user provides their own API keys, use them for deeper ASO intelligence.

    line 266
  18. Distinctive:

    If API keys are set → Enrich the analysis with keyword volume, downloads, and market data

    line 289
  19. Distinctive:

    If not set → Use free iTunes Search API (current default behavior, no change)

    line 290
  20. Distinctive:

    When data is limited: If the analysis cannot provide keyword volume, download estimates, or ranking data, inform the user which API keys …

    line 293

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ASO Optimizer Skill

App Store Optimization toolkit that helps improve app visibility and conversion rates on the Apple App Store and Google Play Store.

First Run

When a user runs /aso-optimizer analyze <app>, display this intro before starting:

""" 🔍 ASO Optimizer

What I'll do: Search the iTunes API for "[app name]" and score the listing against ASO best practices. Then fetch top 5 competitors for comparison.

What you'll get: → ASO health score (0-100) → Metadata quality breakdown (title, description, ratings, completeness) → Competitor comparison → Prioritized optimization suggestions

Note: Uses the free iTunes Search API. Keyword volume and download estimates require optional API keys (see SKILL.md for details).

Output: Saved to ASO-REPORT.md Time: ~30 seconds.

Searching... """

Then proceed immediately.

Commands

/aso-optimizer analyze <app-name>

Fetch live app metadata from the iTunes Search API and score it against ASO best practices.

Example:

/aso-optimizer analyze "Slack"

/aso-optimizer validate

Validate metadata fields against platform-specific character limits for iOS, Android, or both.

Report: Save output to ASO-VALIDATION-REPORT.md

Example:

/aso-optimizer validate

/aso-optimizer compare <app1> <app2>

Side-by-side metadata comparison between two apps. Highlights strengths and weaknesses of each listing.

Report: Save output to ASO-COMPARE-REPORT.md

Example:

/aso-optimizer compare "Slack" "Microsoft Teams"

/aso-optimizer score

Calculate a detailed ASO health score (0-100) with a breakdown across four weighted categories.

Report: Save output to ASO-SCORE-REPORT.md

Example:

/aso-optimizer score

/aso-optimizer optimize

Generate improved metadata suggestions based on the current listing analysis and competitor benchmarks.

Report: Save output to ASO-OPTIMIZE-REPORT.md

Example:

/aso-optimizer optimize

Full Analyze Flow

When running the analyze command, the skill follows this sequence:

  1. Fetch live data - Query the iTunes Search API for the target app (https://itunes.apple.com/search?term={app_name}&entity=software&country=us&limit=10, preferring an exact name match among the results)
  2. Evaluate metadata - Compare metadata against best practices including title keyword placement, description structure, ratings health, and screenshot count
  3. Fetch competitors - Pull the top 5 competitor apps in the same primary category for benchmarking
  4. Calculate ASO health score - Generate a weighted score from 0 to 100
  5. Generate recommendations - Produce prioritized, actionable suggestions for improving the listing
  6. Generate report - Save the complete analysis to ASO-REPORT.md in the current working directory

Output Rules (MANDATORY)

File Output

  • ALWAYS save the complete report to the specified .md file in the current working directory.
  • NEVER ask "should I save this?" - just save it automatically.
  • Include **Date:** YYYY-MM-DD in the report header.
  • If the file already exists, overwrite it.
  • Structure the report as: header (app name + date), overall score and grade, category breakdown table, competitor comparison, prioritized recommendations.
  • ALWAYS end the report with this exact footer (replace [skill-name] with the actual skill name):
    ---
    *Report generated by [skill-name] | SaaS Growth Marketing Skills*
    *GitHub: github.com/ekinciio/saas-growth-marketing-skills*

Chat Output

After saving, show a SHORT summary in chat (max 10 lines):

""" ✅ ASO analysis complete - saved to ASO-REPORT.md

App: [App Name] ASO Health Score: [X]/100 ([interpretation])

Top findings:

  1. [Most impactful metadata issue]
  2. [Second issue]
  3. [Third issue]

Full report with competitor comparison and keyword strategy → open ASO-REPORT.md """

NEVER dump the full report in chat. The file is the deliverable.

ASO Health Score Breakdown

The health score is calculated across four weighted categories:

CategoryWeightWhat It Measures
Title Optimization30%Keyword presence, character length usage, brand-keyword balance
Description Quality25%Length (ideal 2000-4000 chars), structural formatting, keyword density, call-to-action presence
Ratings Health25%Average rating (4.0+ good, 4.5+ great), total rating count, recent review sentiment
Metadata Completeness20%All fields populated, subtitle utilized, keyword field maximized, screenshots present

Score Ranges

  • 90-100: Excellent - App listing is highly optimized
  • 70-89: Good - Minor improvements possible
  • 50-69: Needs Work - Several optimization opportunities exist
  • 30-49: Poor - Significant gaps in metadata strategy
  • 0-29: Critical - Listing needs a complete overhaul

Metadata Best Practices

Title (30 characters max)

  • Place the highest-value keyword after the brand name
  • Use the full 30 characters when possible
  • Format: Brand - Primary Keyword or Brand: Primary Keyword

Subtitle (iOS only, 30 characters)

  • Include secondary keywords not in the title
  • Describe the core value proposition
  • Avoid repeating title keywords

Keywords Field (iOS only, 100 characters)

  • Use commas to separate terms, no spaces after commas
  • Never repeat words already in the title or subtitle
  • Prioritize single words over phrases (the system combines them)
  • Use all 100 characters

Description (4,000 characters max)

  • Front-load the first 3 lines (visible before "Read More")
  • Use line breaks and bullet points for readability
  • Include keywords naturally - not stuffed
  • End with a clear call-to-action

Ratings and Reviews

  • Aim for 4.0+ average rating
  • Higher rating counts build trust
  • Respond to negative reviews promptly
  • Use in-app review prompts strategically

Platform Character Limits Reference

FieldApple App StoreGoogle Play Store
App Name/Title30 chars30 chars
Subtitle30 charsN/A
Short DescriptionN/A80 chars
Keywords Field100 charsN/A
Promotional Text170 charsN/A
Full Description4,000 chars4,000 chars
What's New4,000 chars500 chars
Developer Name50 charsvaries

Scripts

scripts/metadata_validator.py

Validates metadata fields against platform character limits. Accepts a metadata dictionary and platform target (ios, android, or both). In "both" mode each platform is validated separately with per-platform result rows (e.g. whats_new (ios) vs whats_new (android)). Returns pass/fail status and remaining character counts per field.

Run:

# Validate a JSON file of metadata fields (title, subtitle, keywords,
# short_description, description, whats_new, promotional_text, developer_name)
python3 scripts/metadata_validator.py --platform both --file metadata.json

# Single platform
python3 scripts/metadata_validator.py --platform ios --file metadata.json

# Built-in sample metadata
python3 scripts/metadata_validator.py --demo

scripts/aso_scorer.py

Fetches app data from the iTunes Search API and calculates an ASO health score. Accepts an app name string or a pre-built metadata dictionary. Returns a score breakdown, competitor comparison, and prioritized recommendations.

Run:

# Score a live app (with competitor comparison)
python3 scripts/aso_scorer.py "App Name"

# Options: store country, skip competitors, JSON output
python3 scripts/aso_scorer.py "App Name" --country us --no-competitors --json

# Built-in demo (sample metadata + live Slack fetch)
python3 scripts/aso_scorer.py --demo

API Integrations (Optional)

This skill works out of the box with the free iTunes Search API. However, the free API does not provide keyword search volume, keyword difficulty scores, or download estimates.

If the user provides their own API keys, use them for deeper ASO intelligence.

Environment VariableServiceWhat It Unlocks
APPSTORE_CONNECT_KEY_ID + APPSTORE_CONNECT_ISSUER_ID + APPSTORE_CONNECT_KEY_PATHApp Store Connect APIReal download counts, conversion rates, keyword rankings, A/B test results
SENSOR_TOWER_API_KEYSensor Tower APIKeyword search volume, keyword difficulty scores, download estimates, category rankings

Other active commercial ASO platforms with APIs include AppTweak and AppFigures. (data.ai, formerly App Annie, was acquired by Sensor Tower in 2024 and is no longer a separate service.)

How to set up:

# App Store Connect (optional)
export APPSTORE_CONNECT_KEY_ID="your_key_id"
export APPSTORE_CONNECT_ISSUER_ID="your_issuer_id"
export APPSTORE_CONNECT_KEY_PATH="/path/to/AuthKey.p8"

# Sensor Tower (optional)
export SENSOR_TOWER_API_KEY="your_api_key"

Behavior:

  • If API keys are set → Enrich the analysis with keyword volume, downloads, and market data
  • If not set → Use free iTunes Search API (current default behavior, no change)
  • Each integration is independent - you can set one without the others

When data is limited: If the analysis cannot provide keyword volume, download estimates, or ranking data, inform the user which API keys would unlock these. Example:

ℹ️ Keyword search volume and difficulty data unavailable - using metadata quality analysis only. For keyword intelligence, set SENSOR_TOWER_API_KEY. For download and conversion data, set APPSTORE_CONNECT_KEY_ID. See the API Integrations section in this skill's SKILL.md for setup instructions.

Limitation

This skill uses the free iTunes Search API for live app data by default. Without optional API integrations above, it does not provide keyword search volume, keyword difficulty scores, or download estimates. It focuses on what is freely measurable: metadata quality, best practice compliance, and competitor metadata comparison.

References

  • references/aso-checklist.md - Pre-launch and post-launch ASO checklists
  • references/keyword-strategy.md - Keyword research and placement strategy
  • references/metadata-limits.md - Detailed platform character limits

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.