seed-scout

The Competitor Scout finds the gap you can win in. People who already pay a rival tell the App Store exactly what is wrong with it, in public, every day. This skill reads those reviews in bulk, counts what the angry ones complain about, and turns that into one plain sentence per rival that a business plan and a pitch deck can stand on. It reports what reviewers wrote and how often. It never makes a complaint up, and it never calls a rival bad in general.

${CLAUDE_SKILL_DIR} below is this skill's folder (where this SKILL.md lives).

python3 "${CLAUDE_SKILL_DIR}/scout.py" find "dog walking"                   # the apps people find for the idea
python3 "${CLAUDE_SKILL_DIR}/scout.py" reviews 547320928 --write            # 500 most recent -> seed/reviews/
python3 "${CLAUDE_SKILL_DIR}/scout.py" reviews "Wag" --write                # a name works: it says which app it picked
python3 "${CLAUDE_SKILL_DIR}/scout.py" themes 547320928                     # what the 1-2 star reviews say
python3 "${CLAUDE_SKILL_DIR}/scout.py" compare 547320928 940734609 --write  # weak points -> seed/competitors.json
python3 "${CLAUDE_SKILL_DIR}/scout.py" pricing 547320928 --note "keeps 20% of each booking" --source URL --write
python3 "${CLAUDE_SKILL_DIR}/scout.py" show

Other flags: --pages 1..10 (50 reviews a page), --stars 1 (one-star only), --by count (the most mentioned theme instead of the gap), --rules FILE (your own themes), --country gb, --dir, --json, --today, --offline DIR (saved responses, for testing).

What it reads and writes

file / feed	what
iTunes Search API	find, and turning a name into an app id. Free, no key, not an official API
iTunes Lookup API	each app's rating, rating count and full name
customer-reviews RSS	.../rss/customerreviews/page=N/id=APP_ID/sortby=mostrecent/json: 50 a page, 10 pages, so the 500 most recent reviews in one country
seed/reviews/<app_id>.json	with --write: the reviews read (date, stars, title, text, version; no reviewer names)
seed/competitors.json	compare --write: one row per app with themes, top_theme, weak_point, weak_point_line, examples, the rating and the source. /seed-plan, /seed-deck and /seed-coach read it

How the themes and the weak point work

• Low reviews are the one- and two-star ones (--stars changes it). M in "N of M" is how many of those were read, N how many mention the theme.
• Keyword rules, on the title and the text, case-insensitive. A review can hit several themes. The rules are listed at the top of scout.py; --rules FILE adds themes for another industry ({"key": {"label", "patterns"}}).
• The weak point of each app, when you compare two or more: the theme that sets it apart, its share of low reviews minus the pooled share of the other apps. Support complaints show up for every app, so they rarely win; a complaint one rival gets far more than the others does. A theme needs at least 5% of the app's low reviews to count. With one app, or --by count, it is the most mentioned theme. The output says when the two differ.
• Rounding. The rating rounds half up to one decimal (4.88527 is 4.9). Shares are one decimal. Counts are exact.
• Polite. One request at a time, a one-second pause between pages, a 20-second timeout, a User-Agent that names this project.

Steps

1. Ask for the idea in a few words, the way a customer would search for it. Run scout.py find "<words>" and pick the two to four real rivals (the most ratings, the same job). Confirm the list with the user.
2. Run scout.py reviews APP_ID --write for each one.
3. Run scout.py compare APP_ID APP_ID ... --write. Read every rival's weak point, its evidence line and its examples.
4. Read the examples before you quote a theme. Keyword rules miss sarcasm and catch the odd false hit. If a theme looks wrong, open seed/reviews/<id>.json, read the matching reviews and say what you saw.
5. Read each rival's pricing page by hand. Search for "<rival> fees" or "<rival> pricing", open the rival's own help or pricing page, and write down what it actually charges with scout.py pricing APP_ID --note "..." --source URL --write. A fee you cannot link to stays out of the plan.
6. Tell the user, per rival: the rating and rating count, the weak point, "N of M recent 1-2 star reviews mention it", and the pricing note with its link. Then say the gap in one line: what the new product does about it.
7. Hand off to /seed-market to size the market, then /seed-model and /seed-plan, which pull seed/competitors.json into the Competition section. /seed-coach turns it into the questions investors will ask.

Example: the reel

Leashly (a made-up startup: "a dog-walking app with flat prices and a backup walker on every walk"). On October 25, 2026 the scout read the 500 most recent US reviews of Rover and of Wag!. scout.py compare 547320928 940734609 --write:

Competitors: their most recent App Store reviews, 1-2 star only
  app            rating    ratings  low/read   weak point                  evidence
  Rover             4.9    515,771   341/500   fees and pricing            106 of 341 (31.1%)
  Wag!              4.8     67,447   324/500   cancellations and no-shows  81 of 324 (25.0%)
Weak point = the complaint that sets each app apart: its share of low reviews minus the others'.
  Wag!: the most mentioned is customer support (95 of 324), but the other apps get it about as often.

Rover's fee share is 31.1% against Wag!'s 24.7%, a 6.4 point gap. Wag!'s cancellation share is 25.0% against Rover's 12.3%, a 12.7 point gap. The pricing note comes from Rover's own help center: Rover keeps 20% of each sitter booking and adds a service fee for owners at checkout. That is Leashly's story: flat $25 walks with no surprise fees, and a backup walker on every walk.

Rules

• Quote counts as "N of M recent 1-2 star reviews mention X", with the date read. Never "everyone hates X".
• Reviews are what reviewers wrote, not facts about the company. Pricing claims come from the rival's own page, with its URL.
• Never copy a stranger's review into a deck or an email. Titles in the plan are fine as evidence; the full texts stay in seed/reviews/.
• Never log in to the App Store or anywhere else. These feeds are public.

What it never does

It never invents a review, a rating or a fee, never posts a review, never contacts a competitor or a reviewer, and never says a rival is failing. A weak point is where customers complain most, compared with the others.