Kappmaker Aso

KAppMaker — ASO Keyword Research

Before starting

Read AiGuidelines/ first — the PRD and positioning already answer most questions. This is a skill-driven procedure: you (Claude) execute it with your own tools. No kappmaker binary is involved and none needs to be installed.

ASO Keyword Research — Find high-value keywords via Astro MCP

This is a skill-driven procedure, not an external CLI command. You (Claude) drive it using the Astro MCP tools (real-time App Store search data, competitor keywords, popularity + difficulty scores) when they're available in the session, and write the curated keyword list to AiGuidelines/keywords.md for the user to review and feed into other ASO commands.

Output of this workflow is the natural input to the Localize ASO Metadata workflow below — research first, then expand the chosen keywords across the 9 US-indexed locales with mode=keyword-expansion.

Trigger phrases:

• Using kappmaker, research keywords for <base keyword>
• Using kappmaker, find aso keywords [for/around/related to] <topic>
• Using kappmaker, keyword research <base>
• "find keywords", "keyword research", "aso keyword discovery", "find sub-niche keywords"

Argument parsing:

• base / base keyword — required eventually, but can be derived if missing. Resolution order:
  1. Explicit value in the user message (base="ai image generator" or in-line: "research keywords for AI image generator")
  2. If a PRD / app idea / app description file exists in the project (e.g. AiGuidelines/prd.md, AiGuidelines/app-idea.md, or any *.md under AiGuidelines/ that reads like a product description; fall back to the project README.md), read it and pick the strongest noun phrase that describes the app's core function. Confirm the choice with the user before proceeding.
  3. If MobileApp/distribution/ios/appstore_metadata/texts/en-US/name.txt + subtitle.txt exist, infer the base keyword from those (e.g. name=Drift Tuner, subtitle=Real-Time Drift Coach → base=drift coaching). Confirm with the user.
  4. As a last resort, ask the user directly.
• competitors — optional, comma-separated list of competitor app names or App Store IDs. If omitted, the workflow discovers top apps for the base keyword via search_app_store.
• min_popularity — optional, default 30
• max_difficulty — optional, default 45
• target_count — optional, default 30–50 unique keywords after filtering
• output — optional, default AiGuidelines/keywords.md

Preflight: check Astro MCP availability

Before proceeding, verify that at least these Astro MCP tools are visible in the current session: search_app_store, extract_competitors_keywords, get_keyword_suggestions. (Names may vary slightly between Astro MCP versions — list_apps, add_app, get_app_keywords, track_app, etc. are also useful when available.)

If none of those tools are present:

• Tell the user: "Astro MCP is not connected in this session. The keyword-research workflow needs it for popularity/difficulty data. Either install/connect Astro MCP (see https://tryastro.app/docs/mcp/), or I can do a best-effort brainstorm without scores — say 'brainstorm without astro' to continue."
• On brainstorm without astro (or equivalent), fall back to the Manual brainstorm fallback procedure below — generate ~30 sub-niche candidates via your own knowledge, mark scores as ?, and tell the user to validate them on App Store Connect or a separate ASO dashboard.

Procedure (with Astro MCP)

1. Discover competitor apps

   • Call search_app_store({ query: <base> }) to get the top live apps ranking for the base keyword.
   • Pick the top 5–10 most relevant ones (skip mega-apps with unrelated reach, e.g. don't include "Google" when researching "manga translator"). Note their app_id (App Store ID).
   • If the user passed competitors=, prefer those; supplement with discovery results up to 10 total.

2. Track competitor apps in Astro (so their keyword data is available)

   • If a list_apps tool exists, call it first to see which competitors are already tracked.
   • For each untracked competitor, call add_app / track_app with the App Store ID. Some tools require platform (ios / android) — default to ios unless the user is Android-only.
   • If add_app returns a quota error (free-tier limits), surface it to the user and proceed with whatever competitors got tracked. Don't abort.

3. Extract competitor keywords

   • For each tracked competitor, call extract_competitors_keywords({ app_id: <id> }) (or get_app_keywords). Collect every returned keyword along with its popularity and difficulty scores. Tag each with the source competitor app name.

4. Expand with AI suggestions

   • Call get_keyword_suggestions({ base_keyword: <base> }) (and/or per-competitor if the tool supports it). Add those to the candidate pool.

5. Filter and dedupe

   • Drop any keyword where popularity < min_popularity OR difficulty > max_difficulty.
   • Remove exact duplicates (case-insensitive). For near-duplicates (singular/plural pairs, e.g. ai photo editor / ai photo editors), keep the one with higher popularity unless both score well.
   • Drop keywords that are clearly off-topic (e.g. a "fitness" keyword surfaced from a competitor that also happens to sell supplements when researching "workout planner"). Use the base keyword as the relevance anchor — when in doubt, prefer keeping the keyword if it could plausibly match the app's value prop.
   • Aim for target_count (30–50) unique, relevant entries. If you have fewer after filtering, relax max_difficulty by +5 and retry the filter once — tell the user you did so.

6. Cluster into sub-niches

   • Group the filtered keywords by semantic cluster (e.g. for "AI image generator": text-to-image, image editing, style transfer, avatar / portrait, interior design, try-on, etc.).
   • Each cluster becomes a section heading in the output. This makes the file directly usable by localize-metadata mode=keyword-expansion (each cluster maps cleanly to one of the 9 indexed locales).

7. Write AiGuidelines/keywords.md

   • Use the Output format below.
   • Create the AiGuidelines/ directory if it doesn't exist.
   • If a previous AiGuidelines/keywords.md exists, ask once before overwriting: "AiGuidelines/keywords.md already exists. Overwrite? [y/N]". On N, write to AiGuidelines/keywords-<ISO-date>.md instead.

8. Print a short console summary: total candidates → filtered count → final clusters → file path. Then suggest the next step:

   Next: run `Using kappmaker, localize metadata mode=keyword-expansion keywords="..."` with these keywords to fan them across the 9 US-indexed locales.
   

Output format

Write AiGuidelines/keywords.md exactly as specified in references/keywords-md-format.md — header with base/filters/sources, a top-5 "Recommended primary keywords" table, one table per sub-niche cluster, and a "Discarded" table showing what the filters rejected and why. The cluster-per-section structure is what localize-metadata mode=keyword-expansion consumes downstream.

Manual brainstorm fallback (when Astro MCP is unavailable)

If the user chose to brainstorm without Astro MCP:

1. Use your own knowledge of the App Store category around the base keyword to generate 30–50 sub-niche candidates. Cluster them the same way (sub-niche groupings).
2. Mark Popularity and Difficulty columns as ? (unknown) so the user understands these aren't measured numbers — they're hypothesis-only.
3. In the file header, add a prominent note: > ⚠️ Popularity/difficulty scores are NOT included — Astro MCP was unavailable. Validate these candidates on App Store Connect, [Astro](https://tryastro.app/docs/mcp/), AppTweak, or Sensor Tower before using them in production listings.
4. Skip the "Discarded" section (there's nothing to filter against).

The file structure (clusters + recommended primary keywords) stays the same so the user gets the same downstream value.

Tips and edge cases

• Free-tier rate limits: Astro free tier limits tracked-app count. If add_app fails with quota error, work with whatever competitors are already tracked + AI suggestions. Don't abort.
• Very narrow niches: if the base keyword is hyper-specific (e.g. "vintage manga panel translator"), extract_competitors_keywords may return only 5–10 keywords post-filter. That's fine — write them all and let the user know the niche is small.
• Very broad keywords: if the base is generic (e.g. "ai", "photo"), the candidate pool will be huge and the filter cutoffs may still leave 200+ entries. Cap output at target_count × 1.5 and tell the user to narrow the base.
• Multi-language base: if the user's base keyword is non-English, the App Store search results are localized — Astro returns keywords in that language. The workflow still works; just note in the file header which storefront / language the data is for.
• Chain to localize-metadata: at the end of AiGuidelines/keywords.md, include a ready-to-paste command line suggestion using the top ~10 keywords:

  Using kappmaker, localize metadata mode=keyword-expansion keywords="<10 picks comma-separated>"
  

Where this sits in the flow

• Before this: The app's positioning in AiGuidelines/.
• After this: kappmaker-aso-metadata — turn the chosen keywords into the actual title, subtitle and keyword fields.