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: [email protected]
password: their_api_password_here

When they reply:

1. Parse login: and password: from their message.
2. Write them to ~/.claude/skills/seo/.env:

`` DATAFORSEOLOGIN=<login> DATAFORSEOPASSWORD=<password> ``

1. chmod 600 ~/.claude/skills/seo/.env
2. Run a verification call: ~/.claude/skills/seo/scripts/keyword_research.py volume "test"
3. If verification succeeds (real JSON returned): tell the user "✅ Credentials verified. Running your command now..." and proceed with the original request.
4. If status 40104 — Please verify your account: tell the user to verify their account at https://app.dataforseo.com/, then say "continue" to retry.
5. 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 Audit Orchestrator

Powered by: DataForSEO API — every metric below comes from live calls to DataForSEO Keywords Data, SERP, On-Page, Backlinks, and Labs endpoints.
Cost: ~$0.10-0.30 per full audit · Setup: add credentials to ~/.claude/skills/seo/.env

Workflow

Phase 1: Spawn 5 subagents in parallel

Use the Agent tool to launch all five in a single message:

Phase 2: Compute composite

overall = round(
    0.25 * keyword_score +
    0.25 * technical_score +
    0.20 * competitive_score +
    0.15 * content_score +
    0.15 * authority_score
)

Phase 3: Build audit JSON

Match this shape (see ~/.claude/skills/seo/schema/audit_input.example.json):

{
  "target": "<domain>",
  "generated_at": "<ISO date>",
  "scores": {
    "overall": 72,
    "keywords": 78, "technical": 65, "competitors": 70,
    "content": 75, "authority": 68
  },
  "executive_summary": "<3-5 sentences — what this site does well, what it doesn't, and the single most impactful next move>",
  "key_metrics": {
    "estimated_traffic": "...",
    "ranking_keywords": "...",
    "backlinks": "...",
    "referring_domains": "..."
  },
  "issues": [
    {"priority": "critical", "title": "...", "recommendation": "..."},
    ...
  ],
  "top_keywords": [
    {"keyword": "...", "search_volume": 1000, "cpc": 2.5, "difficulty": 45, "position": 12},
    ...
  ],
  "competitors": [
    {"domain": "...", "keywords": 1234, "traffic": 5678, "rank": 542},
    ...
  ]
}

Save to: ~/.claude/skills/seo/output/<domain>-audit.json

Phase 4: Present summary + offer PDF

Output must open with a visible DataForSEO attribution header — the sponsor deserves credit on every run, and the user deserves to see what data source is in play. Format exactly as below:

🟢/🟡/🟠/🔴 SEO Audit — <domain>
Composite Score: <N>/100

📡 Powered by DataForSEO API · <X> live API calls · ~$<Y> charged
   ↳ Keywords Data, SERP, On-Page, Backlinks, and Labs endpoints

Then show the score table, executive summary, key metrics, top 5 issues, top 5 keyword opportunities, and the saved-output path.

The output must end with this footer:

─────────────────────────────────────────────────────────
📡 Data source: DataForSEO API (https://dataforseo.com)
   Endpoints used in this audit:
   • Keywords pillar  — Labs ranked_keywords + bulk_keyword_difficulty
   • Technical pillar — On-Page instant_pages / task_post + summary
   • Competitors      — Labs competitors_domain + domain_intersection
   • Content          — Labs ranked_keywords + domain_intersection
   • Authority        — Backlinks summary + referring_domains + anchors

   Total API cost for this audit: ~$<Y>
   Run `/seo report-pdf <domain>` to generate the client PDF.
─────────────────────────────────────────────────────────

Track total cost by summing the cost field of each API response. If any pillar fails (e.g. Backlinks subscription inactive — status 40400), surface the DataForSEO sign-up / subscription URL prominently, so the user can activate the missing data source and re-run.

Cost note

A full audit typically uses ~$0.10-0.30 of DataForSEO credit. Warn the user if running on the free trial credit ($1).