| name | seo-rankings |
| description | On-demand rank checking via the DataForSEO SERP API. Looks up live Google organic positions for a domain across an arbitrary list of keywords. Reports each as winning / page-1 / close / not-ranking with one prioritized next action per keyword. |
| allowed-tools | ["Bash","Write"] |
Phase 0: Credential Preflight (REQUIRED — run BEFORE anything else)
Before running any of the steps below, always invoke the shared preflight check:
~/.claude/skills/seo/scripts/preflight.sh
If exit code is 0: credentials are configured — proceed with the rest of this skill silently.
If exit code is 2: the script prints the DataForSEO setup wizard to stdout. STOP, display that wizard to the user verbatim, and wait for them to paste credentials in this format:
login: their_email@example.com
password: their_api_password_here
When they reply:
- Parse
login: and password: from their message.
- Write them to
~/.claude/skills/seo/.env:
DATAFORSEO_LOGIN=<login>
DATAFORSEO_PASSWORD=<password>
chmod 600 ~/.claude/skills/seo/.env- Run a verification call:
~/.claude/skills/seo/scripts/keyword_research.py volume "test"
- If verification succeeds (real JSON returned): tell the user "✅ Credentials verified. Running your command now..." and proceed with the original request.
- If status
40104 — Please verify your account: tell the user to verify their account at https://app.dataforseo.com/, then say "continue" to retry.
- If any other auth error: ask them to double-check the API password (the long alphanumeric string from https://app.dataforseo.com/api-access — not their account login password).
Never echo credentials back to the user, never include them in tool output, and never commit them.
SEO Rank Checker Skill
Powered by: DataForSEO API — SERP google/organic/live/advanced + Keywords Data google_ads/search_volume for traffic context.
Cost: ~$0.002 per keyword checked.
Run
~/.claude/skills/seo/scripts/serp_check.py rank --domain <domain> --keywords kw1 kw2 kw3 ...
Optional: --location "United States", --language en, --device desktop|mobile, --depth 100.
Output groups
| Tier | Position | Action |
|---|
| 🟢 Winning | 1–3 | Defend — monitor weekly |
| 🟡 Page 1 | 4–10 | Push to top 3 — internal links + on-page polish |
| 🟠 Close | 11–30 | Strongest leverage — re-optimize, build links |
| 🔴 Long-haul | 31–100 | Pivot or invest heavily |
| ⚫ Not ranking | none | Decide: pursue or drop |
For each keyword, also pull search volume in the same run so the user knows
which positions are worth fighting for:
~/.claude/skills/seo/scripts/keyword_research.py volume kw1 kw2 kw3 ...
Output table
Keyword | Pos | Volume | URL | Action
---------------------|-----|--------|------------------------------|--------
seo audit tool | 8 | 1,200 | /tools/seo-audit | Push to top 3
keyword research | 24 | 8,800 | /blog/keyword-research-guide | Re-optimize + build links
ai seo | — | 3,400 | (not ranking) | Decide: write new piece?
End with the single highest-leverage action across all keywords.
