# Seo Audit

> Full SEO audit powered by the DataForSEO API. Orchestrates 5 specialist subagents (keywords, technical, competitors, content, backlinks) hitting DataForSEO Keywords Data, SERP, On-Page, Backlinks, and Labs endpoints in parallel, then produces a composite SEO Score (0-100) with prioritized action plan and audit JSON ready for PDF export.

- **Type:** Skill
- **Install:** `agentstack add skill-zubair-trabzada-dataforseo-claude-seo-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zubair-trabzada](https://agentstack.voostack.com/s/zubair-trabzada)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zubair-trabzada](https://github.com/zubair-trabzada)
- **Source:** https://github.com/zubair-trabzada/dataforseo-claude/tree/main/skills/seo-audit

## Install

```sh
agentstack add skill-zubair-trabzada-dataforseo-claude-seo-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Phase 0: Credential Preflight (REQUIRED — run BEFORE anything else)

Before running any of the steps below, **always** invoke the shared preflight check:

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

```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](https://github.com/zubair-trabzada)
- **Source:** [zubair-trabzada/dataforseo-claude](https://github.com/zubair-trabzada/dataforseo-claude)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zubair-trabzada-dataforseo-claude-seo-audit
- Seller: https://agentstack.voostack.com/s/zubair-trabzada
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.