# Aso Optimizer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-ekinciio-saas-growth-marketing-skills-aso-optimizer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ekinciio](https://agentstack.voostack.com/s/ekinciio)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ekinciio](https://github.com/ekinciio)
- **Source:** https://github.com/ekinciio/saas-growth-marketing-skills/tree/main/skills/aso-optimizer
- **Website:** https://x.com/ekinciio

## Install

```sh
agentstack add skill-ekinciio-saas-growth-marketing-skills-aso-optimizer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## First Run

When a user runs `/aso-optimizer analyze ` for the first time,
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.

# ASO Optimizer Skill

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

## Commands

### `/aso-optimizer analyze `

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  `

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=1`)
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

**Report:** Save output to `ASO-REPORT.md`
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.
- Follow the structure from `templates/report-template.md`.
- 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:

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

| 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). Returns pass/fail
status and remaining character counts per field.

### `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.

## 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 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 |
| `DATA_AI_API_KEY` | data.ai (App Annie) API | Market data, competitive downloads, revenue estimates, usage metrics |

**How to set up:**
```bash
# 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"

# data.ai (optional)
export DATA_AI_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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ekinciio](https://github.com/ekinciio)
- **Source:** [ekinciio/saas-growth-marketing-skills](https://github.com/ekinciio/saas-growth-marketing-skills)
- **License:** MIT
- **Homepage:** https://x.com/ekinciio

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ekinciio-saas-growth-marketing-skills-aso-optimizer
- Seller: https://agentstack.voostack.com/s/ekinciio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.