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 Competitor Analysis Skill
Powered by: DataForSEO API — Labs competitors_domain + Labs domain_intersection.
Cost: ~$0.05-0.08 per run.
Run
~/.claude/skills/seo/scripts/domain_overview.py competitors --target <domain> --limit 20
For each of the top 5 competitors, also pull intersection (shared keywords):
~/.claude/skills/seo/scripts/domain_overview.py intersect --you <domain> --competitor <competitor>
What to surface
Top 10 competitors table
| Rank | Domain | Common keywords | Their unique keywords | Est. traffic | Domain rank |
|---|
The DataForSEO competitors endpoint already ranks them by SERP overlap with
your target — keep that order.
SERP overlap analysis
For the top 3 competitors:
- How many keywords does the target share with them? (intersect call)
- What's the average position gap? (you at #15, them at #4 = -11 gap)
- Any keywords where the target outranks the competitor? (rare wins to defend)
Strategic groupings
- Direct competitors — share 30%+ of keywords
- Adjacent competitors — share 10-30% (worth monitoring, not chasing)
- Aspirational — much higher domain rank, shared keywords < 10% (long-term)
Competitive Score (0-100)
How dominant is the target in its competitive set?
competitive_score = 100 * (target_traffic / max(sum_of_top_10_traffic, 1))
Capped at 100. Above 30 = strong, 10-30 = mid-tier, <10 = challenger.
Return JSON shape
{
"competitive_score": 24,
"competitors": [
{"domain": "...", "common_keywords": 1234, "unique_keywords": 5678, "traffic": 99999, "rank": 421},
...
],
"serp_overlap": {
"<competitor>": {"shared": 234, "avg_gap": -8.4, "wins": 12}
},
"strategic_groups": {
"direct": ["a.com", "b.com"],
"adjacent": ["c.com"],
"aspirational": ["d.com"]
}
}