Competitor research
Identify the top 5-10 rivals outranking a single app on its own core keywords. Use when the user asks for competitor research, "找竞品" / "找对手" / "跑竞争对手分析", or invokes this competitor-research skill.From its SKILL.md
npx -y skills add fengyiqicoder/AppMate --skill competitor-researchAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
11.9 KB, as published. Nobody here has run it
Competitor Research Workflow
Single authoritative reference. Re-read before every run. Pure-SERP approach: zero RAG, zero AppMate semantic search. The script holds all the data-layer logic; Claude does keyword tokenization and a single batched LLM relevance pass.
Step 0 — Prerequisites
Run before anything else:
python3 scripts/appmate_config.py check
If exit code ≠ 0, STOP. Tell the user AppMate credentials are not configured, show the precheck output verbatim, and direct them to the appmate-setup skill. Do not invoke any other step of this skill.
One-line summary
Single app → script writes phase_a (raw metadata + primary_genre_id) → LLM tokenizes keywords → script fetches iTunes Search top-200 per token, collects rivals outranking self, aggregates, scores, hard-filters by genre+density, writes phase_b → LLM does batched relevance pass on name + description[:200] → script writes final JSON, Claude renders the markdown in the user's conversation language, pastes back into conversation.
Difference from existing skills
competitor-research (this skill) | feature-ideation / growth-strategy | |
|---|---|---|
| Role | produces the competitive signal | consumes it |
| Signal | iTunes Search SERP overlap, strict outrank | reuses this skill's data/competitors_<slug>.json (auto-chains this skill when the file is missing) |
| Output role | the deliverable itself | transient input evidence in their phase_a JSONs |
| Persistence | data/competitors_<slug>.json (cached, reused) | not cached |
Input / Output / Trigger
| Item | Content |
|---|---|
| Trigger | user says "find competitors for <app>" / "跑 <app> 的竞品" / invokes this skill for <app> |
| Input | data/apps_full.json + data/sales_cache.json |
| Output | data/phase_a_competitors_<slug>.json, data/phase_b_competitors_<slug>.json, data/competitors_<slug>.json, data/competitors_<slug>.md + Claude pastes the full markdown back into the conversation |
| User intervention | 2 (trigger + LLM tokenize&filter, both in the same Claude turn) |
Workflow (3 stages)
Stage 1 — Script: phase_a
python3 scripts/competitor_research.py analyze "<app>"
App argument: App Store ID / bundle ID / SKU / fuzzy name. Resolves via the same find_app used by other skills.
Writes data/phase_a_competitors_<slug>.json. If credentials are missing or app is not found, exits 2 with a clear message — do not proceed.
Stage 2 — Claude: tokenize keywords
Read data/phase_a_competitors_<slug>.json. Look at raw.title, raw.subtitle, raw.keywords for the main-market locale.
Tokenization rules (identical to aso-daily-report Step 2):
- Cut real ASO words using semantic understanding of the source-locale text (Chinese, Japanese, Korean, etc.).
- Recognize compound words (
桌面便签,云便签). - Reject CJK runs ≥ 6 characters (almost always invalid mashed runs).
- Recognize brand variants, typos, and English-Chinese fusions.
- De-duplicate case-insensitively.
Output a comma-separated token list and pass it to the script:
python3 scripts/competitor_research.py rank "Sticky Note Pro" --tokens "便签,桌面便签,sticky note,memo"
This writes data/phase_b_competitors_<slug>.json with up to 25 candidates that survived the genre + density hard filters.
Stage 3 — Claude: batched relevance filter + render
Read data/phase_b_competitors_<slug>.json. For each candidate, look at name, description_short, and outranked_keywords[:3].
One batched judgement call. For ALL candidates in one pass, decide for each:
keep: true+ a one-sentence reason (in the user's conversation language) explaining why the rival's target users overlap with the app'skeep: false+ a one-sentence reason (in the user's conversation language) explaining why they do not
Example reasons (when the user is writing Chinese):
- keep:
「XX便签」描述同样主打桌面快速记事,目标用户重叠 - drop:
描述显示是情绪打卡 app,跟便签场景不重叠
Compose the final JSON data/competitors_<slug>.json:
{
"app": "...",
"app_id": "...",
"bundle_id": "...",
"market": "CN",
"primary_genre_id": 6007,
"generated_at": "...",
"tokens": ["..."],
"self_ranks": {"...": ...},
"filtered": [
{... full candidate fields from phase_b ...,
"relevance_keep": true,
"relevance_reason": "..."}
],
"dropped_by_relevance": [
{"itunes_id": "...", "name": "...", "threat_score": ...,
"drop_reason": "..."}
]
}
filtered is sorted by threat_score desc, truncated to 10. dropped_by_relevance is diagnostic only — never rendered in markdown.
If fewer than 3 candidates pass relevance, the markdown shows an evidence-thin warning at the top.
Markdown report template (v1 — follow exactly)
Rendered in the same language the user has been using in this conversation. Default to English; if the user has been writing in Chinese / Japanese / Spanish / etc., translate the template headers, labels and prose accordingly. App Store metadata strings (title / subtitle / keywords / competitor app names) must remain in the App Store's source locale (e.g. zh-Hans names stay zh-Hans) — only the surrounding explanation follows the user's conversation language.
The template below is written with English placeholders. Substitute the equivalent words in the user's conversation language when rendering.
# 🎯 <App name> · Top competitors worth studying
> ⚠️ <evidence-thin warning — only when kept < 3>
**Main market**: <flag> <country> · **30-day downloads**: <N> · **Core keywords searched**: <X>
---
## 1. <Rival name> · ★<rating> (<review_count> reviews)
Outranks you on **<outrank_count> keywords**, on average **<round avg_rank_diff> places** higher
| Keyword | You | Them | Lead | Popularity |
|---|:-:|:-:|:-:|:-:|
| `<kw1>` | <#N or unranked> | **#<n>** | <diff> | <pop> <🔥 if ≥50> |
| `<kw2>` | ... | ... | ... | ... |
| `<kw3>` | ... | ... | ... | ... |
> **Why this one**: <relevance_reason — one sentence in the user's conversation language>
---
## 2. <Rival name> · ...
... (5–10 rivals total, top 3 keywords each) ...
---
**Top <N>**: #X / #Y / #Z — <one-sentence summary of each top rival's core threat>
Want a deeper look at one rival's keyword layout? Tell me the number and I can pull their metadata via the `aso-optimize` skill for side-by-side comparison.
Empty-state template (when len(filtered) == 0)
When the LLM relevance pass keeps zero candidates, do NOT render the per-rival ## blocks. Instead, render exactly this (translate headers/labels into the user's conversation language):
# 🎯 <App name> · Top competitors worth studying
> ⚠️ No qualifying rivals · this app has no same-category rivals on its own keyword SERPs that meet the `MIN_OUTRANK_COUNT = 3` threshold.
**Main market**: <flag> <country> · **30-day downloads**: <N> · **Core keywords searched**: <X>
Likely causes (ordered by likelihood):
1. **Too few keywords**: at least 3 valid tokens are required for any rival to pass the density threshold. Check whether `raw.keywords` in `phase_a_competitors_<slug>.json` is empty or has only 1-2 tokens.
2. **The app is the leader of this niche**: no rival outranks you ≥ 3 times across your own SERP.
3. **Category mismatch**: your `primary_genre_id` does not match any candidate rival — common for niche keywords with cross-category mixing.
To dig deeper, run `python3 scripts/competitor_research.py show-b "<app>"` to inspect the phase_b candidate pool (the pre-filter detail).
10 inviolable rules
- Each rival is its own
H2 (##)block — low-density layout. - Keywords wrapped in backticks
`桌面便签`. - Column headers are full words in the user's conversation language. Never use single-letter abbreviations
T/S/K/X. - The "Why this one" line uses a
>blockquote (translate the label to the user's conversation language). - The keywords table shows exactly top 3 outranked keywords per rival — full list is in JSON.
dropped_by_relevancenever appears in markdown. JSON only.- Sort rivals by
threat_scoredescending. - Closing "Top N" + "deeper look at one rival" guidance is required (translated to the user's conversation language).
- Paste the full markdown back into the conversation. "Saved to data/competitors_<slug>.md" alone is not allowed.
- Empty-state: when
len(filtered) == 0, render the Empty-state template above (no##rival blocks); never invent placeholder rivals.
Data source conventions
| Dimension | Source |
|---|---|
| Pick app | data/apps_full.json via aso_optimize_v2.find_app |
| Main market | the country with the largest 30-day downloads in sales_cache.json |
| primary_genre_id | iTunes Lookup, cached in data/itunes_lookup_cache.json (no TTL) |
| SERP top-200 per token | iTunes Search API (https://itunes.apple.com/search), cached in data/serp_details_cache.json |
| Keyword popularity | keyword_local.lookup_popularity (static keyword_reference_<region>.json) |
| Tokenization | LLM semantic split (not regex / jieba) |
| Relevance filter | LLM batched call over name + description[:200] |
Key parameters
| Parameter | Value | Note |
|---|---|---|
SERP_LIMIT | 200 | top-N per iTunes Search call |
MIN_OUTRANK_COUNT | 3 | candidate must outrank on ≥ this many tokens |
MAX_CANDIDATES_BEFORE_LLM | 25 | phase_b truncates to this |
DESCRIPTION_TRUNCATE | 200 | chars shown to LLM per candidate |
TOP_N_RIVALS | 10 | upper bound on filtered |
MIN_RIVALS_FOR_REPORT | 3 | below this, ⚠️ evidence-thin warning |
TOP_K_KEYWORDS_PER_CARD | 3 | per-card keyword table size in markdown |
CLI
python3 scripts/competitor_research.py analyze "Sticky Note Pro"
python3 scripts/competitor_research.py rank "Sticky Note Pro" --tokens "便签,桌面便签,sticky note,memo"
python3 scripts/competitor_research.py show-a "Sticky Note Pro"
python3 scripts/competitor_research.py show-b "Sticky Note Pro"
Connection to existing workflows
- An
aso-daily-reportrun that finds an app dropping out of top 20 on its own keyword → trigger this skill to see who took the slot. - Use the resulting "Top N" rivals to seed a follow-up
aso-optimizeskill run for<app>for keyword reshuffling. - No downstream skill consumes
competitors_<slug>.jsonyet — wiringfeature-ideation/growth-strategyis a separate task (see spec §15).
Known limits
- LLM tokenization cannot run unattended (cron-incompatible).
- SERP changes hourly; the 7-day rank cache may be stale on borderline rivals.
- An app with ≤ 2 distinct tokens cannot reach
MIN_OUTRANK_COUNT = 3→ empty result. - Drop reasons in
dropped_by_relevancevary across runs on borderline cases (audit via the JSON).
Checklist (must pass before pasting back)
Content
- Main list of 5–10 rivals (≥3 to skip warning, else show ⚠️)
- Each card shows exactly top 3 keywords
- Sorted by
threat_scoredescending
Language
- Single-language throughout the rendered output (matches the user's conversation language)
- No single-letter abbreviations
T/S/K/X - No technical jargon (no "SERP" / "RAG" / "outrank" in user-visible text)
- Keywords wrapped in backticks
Structure
- Each rival uses
## N. <name> - The "Why this one" label uses
>blockquote -
dropped_by_relevanceNOT rendered - Closing "Top N" + "deeper look at one rival" line present
Delivery
-
data/competitors_<slug>.jsonwritten -
data/competitors_<slug>.mdwritten - Full markdown pasted back into the conversation (not just "saved")