appeeky spec
← Learn

Agents · 6 min read

Working with your coding agent

Install the skills once, ask in plain words, and know what the agent does on its own and what it leaves to you.

The spec was built to be driven by Claude Code, Codex, Cursor or Gemini. You say what you want; the agent does the research, the edits and the checks; you decide what ships.

Why it works with agents

Agents are good at files and commands, and that is all the spec is: YAML and markdown in the repo, and a CLI that answers in JSON. There is no dashboard to drive, no session to keep. The agent works on the listing the way it works on your code.

Install the skills

A skill is a short guide the agent reads when the task calls for it. Install them once per repo:

zsh
$ npx skills add appeeky/skills
  • appeeky-specSet up the spec, find gaps, edit the listing, check and push
  • appeeky-spec-targetsPersonas, keyword research, which searches to target
  • appeeky-spec-localizeA new language or country, spare keyword space
  • appeeky-spec-reviewDay-7 and day-14 results, keep or revert, the playbook
  • appeeky-spec-cofounderThe weekly review: one listing change, a brief and a pull request
  • appeeky-spec-reviewsReview themes with counts, replies within each store's limit
  • appeeky-spec-competitorsFinding competitors, what to do when one moves
  • appeeky-spec-screenshotsApp Store screenshot sets, sizes, counts and tests
  • appeeky-spec-socialPosts as files for every platform, comments and replies
  • appeeky-spec-ugcCreator personas, video briefs, the cost first
  • appeeky-spec-adsApple Search Ads, Meta and TikTok, paid searches worth targeting
  • appeeky-spec-attributionWhere installs and revenue come from, smart links, data pull
  • appeeky-spec-experimentsAny experiment's metric and result, pricing tests
  • appeeky-spec-visibilityAI assistants naming the app, the category chart
  • appeeky-spec-seoThe website: seo check, llms.txt, Search Console, Google ranks
  • appeeky-spec-automationGitHub workflows and secrets, other CI, failed runs
  • appeeky-spec-serverA VM or container host: Docker, the .env, logs, updates

Ask in plain words

you Get us ranking for “fan sounds” in the US.

agent Reading playbook.md and the last two releases first.

$ appeeky-spec coverage --country us --json

“fan” is missing. The es-MX keyword field has 37 characters free and the US reads it.

edited appeeky/store/app-store/es-MX.yaml

$ appeeky-spec check --json → 0 errors

$ appeeky-spec diff --json → 1 field

Ready. Shall I open a pull request, or push with the note “Add fan to es-MX for US”?

  • “Get us ranking for “fan sounds” in the US.”

    coverage → finds room in es-MX → edits → check

  • “Launch in Germany.”

    targets for de → writes de-DE → check → diff

  • “Did last week's change work?”

    verify → reads the verdict → proposes keep or revert

  • “Answer the one-star reviews.”

    reviews list → drafts replies → leaves them for your review

What it does, and what it leaves to you

On its own

  • Reads the playbook and past releases
  • Researches searches and competitors
  • Edits listing files and drafts replies
  • Runs check, coverage, diff, verify
  • Explains the change and opens a PR

Only when you say so

  • push to the stores
  • push --yes, skipping the question
  • reviews push, sending replies
  • pull over files you edited

Everything has --json

Every command takes --json and prints the same facts as structured data, so an agent reads results instead of guessing from text. You can use it too, in scripts or your own tools.

zsh
$ npx @appeeky/spec coverage --country us --json
$ npx @appeeky/spec diff --json
$ npx @appeeky/spec verify --playbook --json

Review like code

The safest setup is the one you already have: the agent works on a branch and opens a pull request, the GitHub Action comments what will change, a person approves, and the merge ships it. See How it works with GitHub Actions.