@appeeky/spec 0.0.0-stage → 0.1.0

package/skills/appeeky-spec-review/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: appeeky-spec-review
+description: Review what past store listing changes did in an Appeeky Spec repo, decide whether to keep or revert them, update the playbook and plan the next change. Use when asked "did the last listing change work?", "should we revert?", for a weekly ASO review, to close experiments, or to summarize listing releases for a team update or PR.
+metadata:
+  version: 1.2.0
+---
+
+# Review listing releases with Appeeky Spec
+
+Each push in `appeeky/releases/` holds the before/after values, the hypothesis (`note`) and the search ranks from right before it. `verify` measures again on day 7 and day 14.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## 1. Measure
+
+```bash
+npx @appeeky/spec verify --playbook --json
+```
+
+This only measures releases that reached day 7 or day 14 and have not been measured for that day. Use `verify --now <release-id>` only when the user wants an early look, and say that early ranks are noisy. With `APPEEKY_API_KEY` set, each check also has `metrics`: conversion, downloads, revenue, trials and ads (Apple Search Ads, plus the Meta and TikTok campaigns under `ads:`) before and after the push, each marked `better`, `worse` or `flat`, and due experiments on those metrics are closed for you (`closedExperiments`). The JSON lists experiments that still need a value (`dueExperiments`).
+
+## 2. Read the verdict
+
+| Verdict | Meaning | Usual action |
+| --- | --- | --- |
+| `won` | More targets rose (3+ places) than fell | Keep. Note what worked in the playbook |
+| `lost` | One top-10 target, or two top-20 targets, fell out of the top 20 by 10+ places | Propose `revert` |
+| `mixed` | Some rose, as many or more fell | Look at which targets moved and their popularity before deciding |
+| `flat` | Nothing moved 3+ places | Wait for day 14; then treat as no effect |
+
+When the check has `control`, read `net`: the places the changed storefronts gained beyond the unchanged ones. A "won" with a small net was turned into "mixed" (see `note`): the whole store moved. A metric change marked flat with a `noise` larger than the change is within its normal week-to-week range; do not credit or blame the release for it.
+
+When no rank moved and the check has `decidedBy`, the verdict came from those outcome metrics, in this order:
+
+1. organic installs and revenue,
+2. else conversion,
+3. else downloads,
+4. else the category rank.
+
+Say so: "won on organic installs, ranks unchanged".
+
+A verdict decided by `category_rank` is the weakest kind. The chart moves with ads, featuring and season too, so say that and prefer waiting for day 14.
+
+Two more metrics can be in `metrics.changes` (see appeeky-spec-visibility):
+
+- `ai_visibility`: the share of AI assistant answers that name the app. Assistants update slowly, so read it on day 14.
+- `category_rank`: lower is better, so a negative change is good.
+
+Before recommending, check:
+
+- **Popularity.** One popular term lost can outweigh three tiny ones gained.
+- **Conversion and revenue.** When a check has `metrics` (or `conversion`), more ranks with lower conversion or revenue is not a win, and flat ranks with better conversion can be. Lead with the outcome the user cares about: revenue and trials before downloads, downloads before ranks.
+- **Other causes.** A new app version, a featuring, a competitor's change (`appeeky/competitors/changes.md`), an ad campaign starting (`ads --json`) or seasonality in the same window. Say when the result could be noise.
+- **Day 7 vs day 14.** App Store ranking changes settle over one to two weeks; prefer the day-14 check when it exists.
+
+## 3. Revert when it lost
+
+```bash
+npx @appeeky/spec revert <release-id>
+npx @appeeky/spec diff --json
+```
+
+`revert` only edits the files. Push only when the user agrees, with a note: `push --note "Revert <id>: lost '<keyword>' (<before> → <after>)"`. App Store fields other than promotional text need a new version.
+
+## 4. Close experiments
+
+`verify` closes due experiments on `conversion`, `downloads`, `revenue`, `trial_conversion`, `cpa`, `meta_cpi`, `tiktok_cpa` and the other measured metrics. With `attribution:` in the spec, checks also carry `organic_installs`, `organic_revenue` and `organic_paid`: whether more people found the app in search and paid. For UGC, creator or ad experiments, start them with `--link` so their installs are counted exactly. `appeeky-spec ads --json` shows spend and cost per install per paid channel; `--save` keeps a copy in `appeeky/ads/`. For the rest (installs per 1,000 views, tap-through rate), ask the user for the value or read it from the data they point to, then `experiment close <id> --value <n> --note "..." --playbook`. When starting one, prefer a measured metric: `experiment add --metric trial_conversion` takes its baseline from the last days.
+
+## 5. Update the playbook and plan
+
+`appeeky/playbook.md` gets one line per result from `--playbook`. Add a short "why" in your own words when the cause is clear (for example: "subtitle words beat keyword-field words for 'white noise'"). Then propose the next single change, with a hypothesis that does not repeat a losing one.
+
+## Summaries
+
+`log --markdown -n <count>` prints releases as Markdown tables with the note and the latest verdict, ready for a PR description or a team update.

package/skills/appeeky-spec-targets/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: appeeky-spec-targets
+description: Choose and prioritize the searches an app should be found for (the `targets` in appeeky.spec.yaml), from personas, competitors and keyword popularity. Use when asked which keywords to target, to do keyword research, to fill or clean up targets, to define personas, or to react to a competitor changing its title or subtitle.
+metadata:
+  version: 1.0.0
+---
+
+# Choose targets with Appeeky Spec
+
+`targets` in `appeeky.spec.yaml` are the searches the app should be found for, per storefront. Coverage, suggestions, rank baselines and release verdicts are all measured against them, so wrong targets make every later step wrong. Pick them before editing any listing.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## 1. Start from people, not words
+
+Write down who the app is for as `personas`, with how each one searches:
+
+```yaml
+personas:
+  - id: new-parents
+    name: New parents
+    description: Need their baby to fall asleep, often at night with one hand free.
+    searches: [baby sleep sounds, white noise baby, lullaby]
+```
+
+Ask the user when you cannot tell from the repo, website or current listing. `searches` are seeds, not final targets. Experiments refer to personas by id.
+
+The same personas are the source of the AI visibility intents (`aiVisibility.intents`, see appeeky-spec-visibility). A persona's need ("fall asleep to rain sounds") is an intent. How they would ask an assistant is a prompt; it is longer and more conversational than a store search.
+
+## 2. Collect candidates
+
+From, in this order:
+
+1. The personas' `searches`.
+2. `suggest --json`: missing target words and Appeeky keyword ideas (with `APPEEKY_API_KEY`).
+3. Competitors: `competitors pull` writes the searches each competitor ranks best for to `appeeky/competitors/`, and what the top apps for the seed searches put in their titles and subtitles. With the Appeeky MCP server connected, use its keyword and competitor tools for popularity, difficulty, rankings and recent metadata changes.
+4. Store search suggestions in the storefront's language.
+
+Drop other apps' brand names and trademarks, generic one-word terms the category giants own ("music", "photo"), and searches the app does not actually serve.
+
+## 3. Prioritize
+
+For each candidate, look at popularity (how many search it), difficulty (how strong the apps ranking for it are) and relevance (would someone searching this install this app?).
+
+- Relevance first: an irrelevant search that ranks still does not convert.
+- Prefer specific phrases with decent popularity over head terms a small app cannot reach ("screenshot organizer" over "screenshot").
+- Keep about 5 to 15 targets per storefront. More cannot be covered by a 30 + 30 + 100 character listing and cannot be measured clearly.
+- Put the most important target first; it should go in the name or the title.
+
+## 4. Write them
+
+```yaml
+targets:
+  us: [screenshot organizer, screenshot search, screenshot manager]
+  de: [screenshots organisieren, bildschirmfotos suchen]
+```
+
+Then `coverage --json`: anything `missing` is the next listing change (see appeeky-spec). Each language market needs its own research, never translated targets (see appeeky-spec-localize).
+
+## Competitor moves
+
+When a competitor drops a word from its title or subtitle, the search can open up; when it adds one of your targets, expect pressure on that rank. Check whether the word is one of your targets and how your rank moves, and propose a listing change only for a target that matters. Desktop lists these under ASO → Competitor moves.
+
+## Changing targets later
+
+Targets are the yardstick of every release. Change them deliberately, say why in the commit, and do not swap targets in the same release as a listing change you want to measure.

package/skills/appeeky-spec-visibility/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: appeeky-spec-visibility
+description: Get an app named when people ask ChatGPT, Claude, Gemini or Perplexity for an app like it, and track its category chart rank, in an Appeeky Spec repo. Use when asked about AI visibility, AI search, LLM or GEO/AEO recommendations, "does ChatGPT recommend us", which questions to track, why a competitor is named instead, or how the app ranks in its category.
+metadata:
+  version: 1.0.0
+---
+
+# AI visibility and category rank with Appeeky Spec
+
+Two ways people find an app outside a keyword search: they ask an AI assistant, or they browse the category chart. The spec records both and `verify` measures them around every push.
+
+Run commands as `npx @appeeky/spec <command> --json`.
+
+## AI visibility
+
+### The model
+
+- An **intent** is what someone wants: "fall asleep to rain sounds". Labels need 8+ characters.
+- A **prompt** is one way to ask for it: "what app plays rain sounds to help me sleep". Prompts need 15+ characters.
+- Both live in `appeeky.spec.yaml` under `aiVisibility.intents.<country>`. Appeeky AI Visibility asks each assistant every prompt on a schedule. It records whether the answer names the app, in what position, who else is named and which pages are cited.
+
+Needs `APPEEKY_API_KEY` on a plan with AI Visibility.
+
+### Set up
+
+1. `visibility init`. If Appeeky already tracks intents, they are written into the spec. If not, Appeeky writes them from the store listing in the background; run `init` again a few minutes later.
+2. Read the intents with the user. Keep the ones a real person of a persona would ask (see `personas` in the spec). Drop vague ones.
+3. After the user approves the edits (in a pull request), run `visibility sync`. It only adds. It lists what exists only in Appeeky and archives it only with `--prune`, which you run only when the user asks.
+
+Good prompts:
+
+- Sound like a person typing: "best white noise app for a newborn", not "white noise app".
+- Never contain the app's own name (that measures nothing) or a competitor's name.
+- Each intent gets 2 to 4 prompts phrased differently: a question, a request for a list ("top 5…"), a comparison need ("an app like X but free" is fine without naming X).
+- Use the storefront's language. A `de` intent gets German prompts written for German speakers, not translations.
+
+### Read the results
+
+`visibility pull` writes `appeeky/visibility/<country>.yaml`:
+
+| Field | Meaning |
+| --- | --- |
+| `summary` | intents by status: `winning` (named in 25%+ of answers), `weak`, `missing`, `noData` (not scanned yet) |
+| `intents[].you` | share of answers that name the app, averaged over the assistants, 0–100 |
+| `intents[].byModel` | the same per assistant: one assistant can name you while another never does |
+| `intents[].namedInstead` | who the assistants name instead, with their share |
+| `sources` | pages the assistants cite (mostly Perplexity), most cited first; `yours: true` is the app's own site |
+| `fixes` | open suggestions from Appeeky for an intent |
+
+`appeeky/visibility/changes.md` keeps what moved between pulls: an intent that went from `missing` to `winning`, or the app's site starting to be cited.
+
+### Improve it
+
+Assistants repeat what the web says about an app. In order of what you can change:
+
+1. **The listing.** The first lines of the description and the subtitle should say what the app does in the intent's words ("rain sounds for sleep", not "an immersive audio experience"). This is a normal listing change: propose it in a pull request and measure it like any release (see appeeky-spec).
+2. **The app's own website.** A page per main use case, in plain words, with the app's name and store links. When `sources` shows the assistants cite pages like it from competitors, the same kind of page is the gap.
+3. **Cited third-party pages.** `sources` lists them: review sites, Reddit threads, "best apps for…" articles. Tell the user which ones name the competitors in `namedInstead` but not the app. Getting listed there is the user's outreach, not something to fake.
+4. **`fixes`.** Read each one. Propose the ones that are listing or website edits; summarize the rest for the user.
+
+Never write fake reviews, posts or comments, and never make claims the app does not live up to. Assistants also read those.
+
+### Measure it
+
+`verify` reads Appeeky's daily series as `ai_visibility`, the 0–1 share of answers that name the app. It compares the days before a push with the days after. Assistant answers change slowly and scans may be weekly, so a day-7 move is a hint and day 14 counts. `visibility scan` asks the assistants now. It uses AI Visibility credits: run it only when the user asks.
+
+## Category rank
+
+`category pull` adds today's rank in the category chart (top 100) for each storefront to `appeeky/category.csv`.
+
+- **App Store:** reads Apple's chart, no key. The genre comes from the app, and a paid app is read from top-paid.
+- **Google Play:** needs `APPEEKY_API_KEY` and `category.googlePlay` in the spec (e.g. `HEALTH_AND_FITNESS`). Ask the user for the category if it is not set.
+- An empty rank means not in the top 100.
+
+The rank mostly follows downloads, so it moves with everything: listing changes, ads, featuring, seasonality. Read it as a sign, not a cause:
+
+- `verify` reads it as `category_rank`, where lower is better. When no target search moved and there is no analytics data, it decides the release (`decidedBy: ["category_rank"]`). Say so.
+- A jump on the day an ad campaign started is the ad, not the listing. Check `appeeky ads` and `loops.md` first.
+- It needs history: run it daily (the daily workflow does) so there are days before each push.