agentsclimarketplace

Competitor research

Skill fengyiqicoder/AppMate/skills/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

Install
npx -y skills add fengyiqicoder/AppMate --skill competitor-research

Assembled 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
Roleproduces the competitive signalconsumes it
SignaliTunes Search SERP overlap, strict outrankreuses this skill's data/competitors_<slug>.json (auto-chains this skill when the file is missing)
Output rolethe deliverable itselftransient input evidence in their phase_a JSONs
Persistencedata/competitors_<slug>.json (cached, reused)not cached

Input / Output / Trigger

ItemContent
Triggeruser says "find competitors for <app>" / "跑 <app> 的竞品" / invokes this skill for <app>
Inputdata/apps_full.json + data/sales_cache.json
Outputdata/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 intervention2 (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's
  • keep: 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

  1. Each rival is its own H2 (##) block — low-density layout.
  2. Keywords wrapped in backticks `桌面便签`.
  3. Column headers are full words in the user's conversation language. Never use single-letter abbreviations T/S/K/X.
  4. The "Why this one" line uses a > blockquote (translate the label to the user's conversation language).
  5. The keywords table shows exactly top 3 outranked keywords per rival — full list is in JSON.
  6. dropped_by_relevance never appears in markdown. JSON only.
  7. Sort rivals by threat_score descending.
  8. Closing "Top N" + "deeper look at one rival" guidance is required (translated to the user's conversation language).
  9. Paste the full markdown back into the conversation. "Saved to data/competitors_<slug>.md" alone is not allowed.
  10. Empty-state: when len(filtered) == 0, render the Empty-state template above (no ## rival blocks); never invent placeholder rivals.

Data source conventions

DimensionSource
Pick appdata/apps_full.json via aso_optimize_v2.find_app
Main marketthe country with the largest 30-day downloads in sales_cache.json
primary_genre_idiTunes Lookup, cached in data/itunes_lookup_cache.json (no TTL)
SERP top-200 per tokeniTunes Search API (https://itunes.apple.com/search), cached in data/serp_details_cache.json
Keyword popularitykeyword_local.lookup_popularity (static keyword_reference_<region>.json)
TokenizationLLM semantic split (not regex / jieba)
Relevance filterLLM batched call over name + description[:200]

Key parameters

ParameterValueNote
SERP_LIMIT200top-N per iTunes Search call
MIN_OUTRANK_COUNT3candidate must outrank on ≥ this many tokens
MAX_CANDIDATES_BEFORE_LLM25phase_b truncates to this
DESCRIPTION_TRUNCATE200chars shown to LLM per candidate
TOP_N_RIVALS10upper bound on filtered
MIN_RIVALS_FOR_REPORT3below this, ⚠️ evidence-thin warning
TOP_K_KEYWORDS_PER_CARD3per-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-report run 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-optimize skill run for <app> for keyword reshuffling.
  • No downstream skill consumes competitors_<slug>.json yet — wiring feature-ideation / growth-strategy is 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_relevance vary 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_score descending

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_relevance NOT rendered
  • Closing "Top N" + "deeper look at one rival" line present

Delivery

  • data/competitors_<slug>.json written
  • data/competitors_<slug>.md written
  • Full markdown pasted back into the conversation (not just "saved")

Keep looking

Skills are one crate of 611,178. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.