/seo-outreach-report

name: seo-outreach-report
description: 'Use when generating a polished single-PDF SEO snapshot for a third-party domain owner. The output is a decision-maker-friendly document in plain language for non-SEO-experts (shop owners, founders, executives), not a technical site audit. Triggers include "send the owner of X.de an SEO snapshot", "generate a report for the owner", "show X.de their SEO status", "make a PDF for a non-technical decision maker about their SEO". Complements `claude-seo:seo-audit` when the goal is communication for a non-technical audience rather than technical depth. Complements `make-pdf` when the input is a domain (not a markdown file) and the workflow needs editorial narrative integrated with Sistrix / DataForSEO / PSI data.'
user-invocable: true
argument-hint: '[domain | comma-separated-slugs]'
allowed-tools: [Read, Write, Bash(node:*), Bash(curl:*)]
license: MIT
metadata:
  author: Max Schottke
  version: '0.5.4'
  category: marketing

SEO Outreach Report

Overview

Generates a 10-chapter PDF report per domain for non-technical decision-makers. Data sources: Sistrix VI, DataForSEO Labs (rankings + competitors + backlinks), Google PSI v5 (lab + CrUX). Renders via Chrome-headless without puppeteer.

**Output:** `~/Downloads/SEO-Auswertung-<domain>-<YYYY-MM-DD>.pdf` (~1 MB per report)

When to use

• A shop owner / executive needs SEO clarity in plain language
• Client onboarding or recurring quarterly status update
• Multi-domain audit for competitive analysis or portfolio review
• You need a printable, sendable snapshot for a non-technical reader

**Don't use for:**

• Deep technical SEO audit (too much detail, wrong audience)
• Your own domain optimization — work directly with the data, no PDF needed
• Pure keyword research
• YMYL domains (medical, legal, financial) without expert review — see YMYL notice below

YMYL notice

The PDF this skill generates contains a concrete action plan with cost ranges, timelines, and prioritized recommendations. For Your-Money-Your-Life sites (medical / health, legal, financial, regulated industries), have a domain expert review the action plan before publication or client delivery. Examples of recommendations that need expert review in those contexts:

• Author-page suggestions touching credentials, licensing, or chamber-association display
• Schema-markup recommendations for medical / legal entities (MedicalBusiness, Physician, Attorney) — these have specific data-quality expectations from Google
• Off-page link-building suggestions that could conflict with industry advertising codes (e.g. medical marketing regulations in DE, US, EU)
• Cost ranges quoted in EUR are typical for the DE consulting market — verify against your local market before quoting to a client

The plugin treats all sites uniformly at the SEO-mechanics level; it does not validate domain-specific compliance, fiduciary obligations, or industry-specific marketing regulations.

API cost expectation per run

Default configuration produces ~5 API calls per target domain: 1 Sistrix VI, 1 Sistrix VI overview, 18 monthly VI history points, 1 DataForSEO ranked_keywords, 1 backlinks/summary, 1 domain_rank_overview, 1 competitors_domain, 1 referring_domains, 2 PSI runs (mobile + desktop).

Typical realized cost per domain: 5–50 ct in DataForSEO credits plus 18 Sistrix calls plus 2 PSI calls (free with API key). Multi-domain batches multiply linearly. Before running against many domains, estimate cost first — see COSTS.md.

Pipeline (4 steps)

seo-audit-fetch-v2.js  →  ~/.cache/seo-rescue/<slug>-raw.json     (Sistrix + DataForSEO + PSI)
seo-extract-v2.js      →  ~/.cache/seo-rescue/<slug>-summary.json (KPIs, top keywords, quick wins)
seo-onpage.js          →  ~/.cache/seo-rescue/seo-onpage.json     (title, H1, schema from local HTML)
seo-report-gen.js      →  ~/Downloads/SEO-Auswertung-<domain>-<date>.pdf

Cache directory `~/.cache/seo-rescue/` is created mode `0700` (owner-only). Override with `SEO_CACHE_DIR=/path` if needed.

The scripts in this skill folder are self-contained. Prerequisite: a `.env` file (any path) with:

SISTRIX_API_KEY=...       # https://www.sistrix.de/ (API tier must include VI endpoint)
DATAFORSEO_LOGIN=...      # https://dataforseo.com/ — pay-per-call
DATAFORSEO_PASSWORD=...
GOOGLE_API_KEY=...        # https://console.cloud.google.com/ — enable PageSpeed Insights API

Recommended path convention: `~/.config/seo-outreach-report/.env` or `./.env` in your working directory. See `.env.example` in this skill folder.

Quick start (adding a new domain)

1. Edit `audit-config.json` (copy from `audit-config.example.json`):

   {
     "targets": [
       { "slug": "newslug", "domain": "example.de", "host": "https://example.de/", "label": "Example Company" }
     ],
     "narrative": {
       "newslug": { "headline": "...", "business_one_liner": "...", "diagnose": [...], "fazit": [...], "action_plan": [...] }
     }
   }

2. Cache the homepage HTML locally for on-page analysis (cache dir is auto-created):

   CACHE_DIR="${SEO_CACHE_DIR:-$HOME/.cache/seo-rescue}"
   mkdir -p "$CACHE_DIR" && chmod 700 "$CACHE_DIR"
   curl -s -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" "https://example.de/" > "$CACHE_DIR/newslug-home.html"

3. Run the pipeline:

   ENV_PATH=/path/to/your/.env  # or ~/.config/seo-outreach-report/.env
   node --env-file="$ENV_PATH" seo-audit-fetch-v2.js newslug
   node seo-extract-v2.js
   node seo-onpage.js
   node seo-report-gen.js

Report structure (10 chapters)

1. **Cover** with data-driven headline 2. **Executive summary for decision-makers** — 4 KPI gauges + top 5 prioritized actions 3. **Status quo** — neutral inventory (no judgment) 4. **Google visibility over time** — 18-month VI chart + plain-language interpretation 5. **Where you rank today** — top 15 keywords +