appeeky spec
← Learn

Users · 6 min read

Reviews, answered in a pull request

Pull every review into the repo, read the summary, draft replies with your agent and send them after a review.

What users write is the best brief for your listing, and replying shows the next reader someone is listening. The spec brings both stores' reviews into the repo, so your agent can read them and you can answer them through a pull request.

Pull reviews into the repo

With an Appeeky key and your stores connected in Appeeky, reviews pull writes every review, one JSON object per line, in a file per month. Pull again and new reviews are added; edited or answered ones are replaced.

zsh
$ npx @appeeky/spec reviews pull
App Store 412 reviews · 38 new · 2 changed
Google Play 198 reviews · 21 new
Wrote appeeky/reviews/summary.md
▾ appeeky/reviews
▾ app-store
2026-10.jsonl
2026-11.jsonl
▾ google-play
2026-11.jsonl
▾ replies# drafts, sent after review
summary.md# the numbers, for people and agents

Read the summary

summary.md puts the last 30 days next to the 30 before: how many reviews, the average, the share of one- and two-star ones, how many wait for a reply. Then ratings per app version, which shows when an update made people unhappy, and the low ratings still without a reply. Last, the words users use that your listing does not: phrases that come up in three or more reviews and appear in no listing, often the next target or the next feature.

appeeky/reviews/summary.md
## App Store
| | reviews | average | 1–2 stars | unanswered |
| last 30 days | 184 | 4.52 | 6% | 11 |
| 30 days before | 151 | 4.31 | 11% | 9 |
Low ratings without a reply:
- `1834` 2★ 2026-11-02 US: Wish it had fan sounds
- `1821` 1★ 2026-10-30 GB: Crashes when I open settings
## Words users use that your listing does not
| words | reviews | of them 1–3 stars |
| fan sounds | 9 | 5 |
| sleep timer | 7 | 6 |
zsh
$ npx @appeeky/spec reviews list --rating 1-2 --unanswered
2★ 2026-11-02 app-store US 3.1 1834
Wish it had fan sounds for summer nights.
1★ 2026-10-30 app-store GB 3.1 1821
Crashes when I open settings.

Draft replies

reviews reply <id> --text writes a draft to appeeky/reviews/replies/, with the review it answers next to it. Ask your agent to draft them; the review skill keeps them specific, short and honest.

appeeky/reviews/replies/app-store-1834.yaml
id: "1834"
store: app-store
review: "2★ 2026-11-02: Wish it had fan sounds for summer nights."
text: Thanks! Fan sounds are in 3.2, out this week.
status: draft

Send after review

Commit the drafts on a branch and open a pull request. Someone reads them like any copy that goes public. After the merge, reviews push sends every draft and marks it sent:

zsh
$ npx @appeeky/spec reviews push
1834 app-store
Thanks! Fan sounds are in 3.2, out this week.
Sent 1.

Reviews are listing input

The same complaint three times is a feature people look for. If they search for it, it is a target; if they expect it, it belongs in the description or the first screenshot. The agent reads summary.md before it proposes a listing change, and verify compares the average rating and the share of low ratings around every push.