Seo Audit

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:

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

`` DATAFORSEO_LOGIN= DATAFORSEO_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:

| Subagent type | Task | |---------------|------| | seo-keywords | "Run keyword analysis for `. Return JSON with keyword_score (0-100), top_opportunities (top 20 by volume/difficulty ratio), and intent_breakdown." | | seo-technical | "Run technical audit for (max 100 pages). Return JSON with technical_score (0-100), critical_issues, high_issues, and crawl_summary." | | seo-competitors | "Find top 10 competitors for . Return JSON with competitive_score (0-100), competitors list, and serp_overlap." | | seo-content | "Analyze content topical authority for . Return JSON with content_score (0-100), strong_topics, weak_topics, missing_topics." | | seo-backlinks | "Audit backlink profile for `. Return JSON with authorityscore (0-100), backlinksummary, topreferrers, anchordistribution, toxicity_flags." |

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": "",
  "generated_at": "",
  "scores": {
    "overall": 72,
    "keywords": 78, "technical": 65, "competitors": 70,
    "content": 75, "authority": 68
  },
  "executive_summary": "",
  "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/-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 — 
Composite Score: /100

📡 Powered by DataForSEO API ·  live API calls · ~$ 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: ~$
   Run `/seo report-pdf ` 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).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zubair-trabzada
• Source: zubair-trabzada/dataforseo-claude
• License: MIT

Install and usage instructions live in the source repository linked above.