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
In this repository15 other files it gives its agents.
- brand-mention-scannerSkill
- competitor-intelSkill
- geo-seo-auditorSkill
- growth-skillsSkill
- landing-page-croSkill
- local-seo-optimizerSkill
- onboarding-optimizerSkill
- plg-funnel-analyzerSkill
- pricing-analyzerSkill
- reddit-opportunity-finderSkill
- retention-playbookSkill
- review-sentimentSkill
- saas-landing-builderSkill
- subscription-metricsSkill
- web-app-growth-engineSkill
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
- Very specific: line 19
When a user runs /aso-optimizer analyze <app>, display this intro before starting:
- Distinctive: line 26
Search the iTunes API for "[app name]" and score the listing against ASO best practices.
- Very specific: line 108
When running the analyze command, the skill follows this sequence:
- Very specific: line 127
ALWAYS save the complete report to the specified .md file in the current working directory.
- Distinctive: line 128
NEVER ask "should I save this?" - just save it automatically.
- Distinctive: line 130
If the file already exists, overwrite it.
- Distinctive: line 133
ALWAYS end the report with this exact footer (replace [skill-name] with the actual skill name):
- Distinctive: line 141
After saving, show a SHORT summary in chat (max 10 lines):
- Distinctive: line 157
NEVER dump the full report in chat.
- Distinctive: line 181
Place the highest-value keyword after the brand name
- Distinctive: line 182
Use the full 30 characters when possible
- Distinctive: line 188
Avoid repeating title keywords
- Distinctive: line 191
Use commas to separate terms, no spaces after commas
- Distinctive: line 192
Never repeat words already in the title or subtitle
- Distinctive: line 198
Use line breaks and bullet points for readability
- Distinctive: line 206
Use in-app review prompts strategically
- Distinctive: line 266
If the user provides their own API keys, use them for deeper ASO intelligence.
- Distinctive: line 289
If API keys are set → Enrich the analysis with keyword volume, downloads, and market data
- Distinctive: line 290
If not set → Use free iTunes Search API (current default behavior, no change)
- Distinctive: line 293
When data is limited: If the analysis cannot provide keyword volume, download estimates, or ranking data, inform the user which API keys …
≈ “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.
Files
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 optimizeFull Analyze Flow
When running the analyze command, the skill follows this sequence:
- 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) - Evaluate metadata - Compare metadata against best practices including title keyword placement, description structure, ratings health, and screenshot count
- Fetch competitors - Pull the top 5 competitor apps in the same primary category for benchmarking
- Calculate ASO health score - Generate a weighted score from 0 to 100
- Generate recommendations - Produce prioritized, actionable suggestions for improving the listing
- Generate report - Save the complete analysis to
ASO-REPORT.mdin the current working directory
Output Rules (MANDATORY)
File Output
- ALWAYS save the complete report to the specified
.mdfile in the current working directory. - NEVER ask "should I save this?" - just save it automatically.
- Include
**Date:** YYYY-MM-DDin 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:
- [Most impactful metadata issue]
- [Second issue]
- [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:
| Category | Weight | What It Measures |
| Title Optimization | 30% | Keyword presence, character length usage, brand-keyword balance |
| Description Quality | 25% | Length (ideal 2000-4000 chars), structural formatting, keyword density, call-to-action presence |
| Ratings Health | 25% | Average rating (4.0+ good, 4.5+ great), total rating count, recent review sentiment |
| Metadata Completeness | 20% | 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 KeywordorBrand: 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
| Field | Apple App Store | Google Play Store |
| App Name/Title | 30 chars | 30 chars |
| Subtitle | 30 chars | N/A |
| Short Description | N/A | 80 chars |
| Keywords Field | 100 chars | N/A |
| Promotional Text | 170 chars | N/A |
| Full Description | 4,000 chars | 4,000 chars |
| What's New | 4,000 chars | 500 chars |
| Developer Name | 50 chars | varies |
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 --demoscripts/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 --demoAPI 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 Variable | Service | What It Unlocks |
APPSTORE_CONNECT_KEY_ID + APPSTORE_CONNECT_ISSUER_ID + APPSTORE_CONNECT_KEY_PATH | App Store Connect API | Real download counts, conversion rates, keyword rankings, A/B test results |
SENSOR_TOWER_API_KEY | Sensor Tower API | Keyword 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, setAPPSTORE_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 checklistsreferences/keyword-strategy.md- Keyword research and placement strategyreferences/metadata-limits.md- Detailed platform character limits
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
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.

