diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index a635cd93..51cda1f2 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -1489,6 +1489,21 @@ "category": "Tools & Integrations", "description": "Reverse engineer Rust binaries and libraries: triage targets, demangle symbols, recover crate namespaces, and map panic, unwind, async, and FFI paths." }, + { + "name": "seo-dungeon", + "displayName": "SEO Dungeon", + "source": { + "source": "local", + "path": "./plugins/avalonreset/seo-dungeon" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Tools & Integrations", + "description": "Gamified local SEO audits that turn website issues into 16-bit dungeon battles for Codex, Claude, and Gemini CLI workflows.", + "icon": "./plugins/avalonreset/seo-dungeon/assets/icon.svg" + }, { "name": "sitemd", "displayName": "sitemd", diff --git a/README.md b/README.md index 63d31fb5..09e29c88 100644 --- a/README.md +++ b/README.md @@ -251,6 +251,7 @@ Third-party plugins built by the community. [PRs welcome](#contributing)! - [Remotion Plugin](https://github.com/tim-osterhus/codex-remotion-plugin) - Build parameterized Remotion videos in Codex with the official Remotion docs MCP, composition scaffolding, and a data-driven launch-video workflow. - [ScrapeGraph AI](https://github.com/ScrapeGraphAI/just-scrape) - AI-powered web scraping CLI to search, scrape, extract structured JSON, crawl, and monitor web pages via the ScrapeGraph AI API. - [Rust Reverse Engineering](https://github.com/jingjing2222/rust-reverse-engineering-skill) - Reverse engineer Rust binaries and libraries: triage targets, demangle symbols, recover crate namespaces, and map panic, unwind, async, and FFI paths. +- [SEO Dungeon](https://github.com/avalonreset/seo-dungeon) - Gamified local SEO audits that turn website issues into 16-bit dungeon battles for Codex, Claude, and Gemini CLI workflows. - [sitemd](https://github.com/sitemd-cc/sitemd) - Build websites from Markdown via MCP — 22 tools for creating pages, generating content, validating, running SEO audits, configuring settings, and deploying static sites to Cloudflare Pages. - [Synta MCP](https://github.com/Synta-ai/n8n-mcp-codex-plugin-synta) - Build, edit, validate, and self-heal n8n workflows with Synta MCP tools and Codex-ready workflow guidance. - [Task Scheduler](https://github.com/6Delta9/task-scheduler-codex-plugin) - OpenAI Codex plugin and local MCP server for turning task lists into realistic schedules with blocked dates, capacity overrides, overflow tracking, and markdown planning output. diff --git a/plugins.json b/plugins.json index d2d1f21e..9b40b3b7 100644 --- a/plugins.json +++ b/plugins.json @@ -2,8 +2,8 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "name": "awesome-codex-plugins", "version": "1.0.0", - "last_updated": "2026-06-16", - "total": 112, + "last_updated": "2026-06-19", + "total": 113, "categories": [ "Development & Workflow", "Tools & Integrations" @@ -1019,6 +1019,16 @@ "source": "awesome-codex-plugins", "install_url": "https://raw.githubusercontent.com/jingjing2222/rust-reverse-engineering-skill/HEAD/.codex-plugin/plugin.json" }, + { + "name": "SEO Dungeon", + "url": "https://github.com/avalonreset/seo-dungeon", + "owner": "avalonreset", + "repo": "seo-dungeon", + "description": "Gamified local SEO audits that turn website issues into 16-bit dungeon battles for Codex, Claude, and Gemini CLI workflows.", + "category": "Tools & Integrations", + "source": "awesome-codex-plugins", + "install_url": "https://raw.githubusercontent.com/avalonreset/seo-dungeon/HEAD/.codex-plugin/plugin.json" + }, { "name": "sitemd", "url": "https://github.com/sitemd-cc/sitemd", diff --git a/plugins/avalonreset/seo-dungeon/.codex-plugin/plugin.json b/plugins/avalonreset/seo-dungeon/.codex-plugin/plugin.json new file mode 100644 index 00000000..d731f631 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/.codex-plugin/plugin.json @@ -0,0 +1,64 @@ +{ + "name": "seo-dungeon", + "version": "2.2.16", + "description": "SEO Dungeon skill suite with a gamified local audit UI. 25 sub-skills (21 core + 1 orchestrator + 1 framework integration + 2 extension mirrors), 18 sub-agents, and 23 Codex agent profiles backed by the v2.2 SEO engine.", + "author": { + "name": "Avalon Reset", + "email": "avalonreset@users.noreply.github.com", + "url": "https://github.com/avalonreset" + }, + "homepage": "https://github.com/avalonreset/seo-dungeon", + "repository": "https://github.com/avalonreset/seo-dungeon", + "license": "MIT", + "keywords": [ + "codex", + "codex-cli", + "codex-skills", + "claude", + "gemini", + "seo", + "ai-seo", + "technical-seo", + "content-quality", + "schema-markup", + "core-web-vitals", + "local-seo", + "generative-engine-optimization", + "ai-search", + "sitemap", + "image-optimization", + "google-search-console", + "dataforseo", + "mcp", + "pagespeed", + "crux", + "backlinks", + "semantic-clustering", + "sxo", + "drift-monitoring", + "ecommerce-seo", + "automation", + "marketing-automation" + ], + "skills": "./skills/", + "hooks": "./hooks/hooks.json", + "interface": { + "displayName": "SEO Dungeon", + "shortDescription": "Run SEO Dungeon audits and SEO workflows in Codex.", + "longDescription": "SEO Dungeon is a gamified SEO analysis suite with Codex-compatible skills, Codex agent profiles, portable agent prompts, shared cache artifacts, optional SEO data integrations, and a dungeon crawler UI.", + "developerName": "Avalon Reset", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Write" + ], + "websiteURL": "https://github.com/avalonreset/seo-dungeon", + "defaultPrompt": [ + "Audit this website for SEO issues.", + "Check schema and Core Web Vitals for this URL.", + "Build an SEO action plan for this business." + ], + "brandColor": "#D4AF37", + "composerIcon": "./assets/icon.svg" + } +} diff --git a/plugins/avalonreset/seo-dungeon/.codexignore b/plugins/avalonreset/seo-dungeon/.codexignore new file mode 100644 index 00000000..ebccd2c6 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/.codexignore @@ -0,0 +1,18 @@ +.codex/ +.codex-work/ +.git/ +.github/ +.pytest_cache/ +.venv/ +build/ +dist/ +dungeon/.logs/ +dungeon/dist/ +dungeon/node_modules/ +node_modules/ +output/ +playwright-report/ +site/ +test-results/ +*.egg-info/ +*.log diff --git a/plugins/avalonreset/seo-dungeon/LICENSE b/plugins/avalonreset/seo-dungeon/LICENSE new file mode 100644 index 00000000..764c5404 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Avalon Reset + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/avalonreset/seo-dungeon/README.md b/plugins/avalonreset/seo-dungeon/README.md new file mode 100644 index 00000000..8c87c9a3 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/README.md @@ -0,0 +1,302 @@ +

+ SEO Dungeon - Gamified SEO Audit Tool +

+ +# SEO Dungeon - AI SEO Audits as Dungeon Battles + +[![CI](https://github.com/avalonreset/seo-dungeon/actions/workflows/ci.yml/badge.svg)](https://github.com/avalonreset/seo-dungeon/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) +[![Version](https://img.shields.io/badge/version-2.2.16-blue)](CHANGELOG.md) +[![Runtime](https://img.shields.io/badge/runtime-Codex%20%7C%20Claude%20%7C%20Gemini-2ea44f)](dungeon/) + +SEO Dungeon turns SEO audits into a 16-bit dungeon crawler. Enter a domain, +inspect the issues as demons, and use a local AI CLI to analyze or fix them +inside your project. The packaged bridge selects Codex by default and also +supports Claude Code and Gemini CLI when those local tools are installed. + +## Screenshots & Key Art + + + + + + + + + + + + + + +
SEO Dungeon title screen with character and runtime selection
Pick a CLI, pick a warrior, enter a domain		Gate scene showing quest continuation options
Continue a previous quest or begin a new one
SEO Dungeon audit loading hallway with the hero descending
Run a fresh audit while the hero descends		Dungeon hall showing SEO issue demons sorted by severity
Browse SEO demons sorted by severity
Turn-based battle scene with real-time Guild Ledger
Battle demons with agent-powered fixes		SEO Dungeon social preview key art
Share-ready key art for the public repo
+ +## How It Works + +1. Choose a local CLI runtime: Codex, Claude Code, or Gemini CLI. Codex is + selected by default in the packaged app. +2. Choose a character profile: + - Warrior: deep profile. Codex uses `xhigh`; Claude uses `opus`; Gemini uses `pro`. + - Samurai: balanced profile. Codex uses `high`; Claude uses `sonnet`; Gemini uses `flash`. + - Knight: fast profile. Codex uses `medium`; Claude uses `haiku`; Gemini uses `flash-lite`. +3. Enter a domain and local project path. +4. Arm YOLO Mode so Codex runs with `--dangerously-bypass-approvals-and-sandbox`. +5. Run a full `/seo audit` through the selected local CLI. +6. Review SEO issues as dungeon demons sorted by severity. +7. Use **Attack** to send a scoped agent turn for the selected issue. +8. Queue or steer follow-up prompts through the Guild Ledger while work is + running; queued prompts release when the active turn settles. +9. Use **Vanquish** when you decide the issue is handled. + +The Guild Ledger sidebar can be resized or hidden while you work, and the title +screen remembers your last domain and project folder. YOLO Mode is deliberately +not remembered; it must be armed on each fresh app launch. + +The dungeon bridge starts local CLI processes only. It does not proxy model +access and does not route through browser automation or consumer-app wrappers. + +## SEO Engine + +The bundled v2.2 engine is synchronized with Daniel Agrici's public +`AgriciDaniel/claude-seo` v2.2.0 release. It includes 25 sub-skills (21 core + +1 orchestrator + 1 framework integration + 2 extension mirrors), 18 portable +sub-agents, 23 Codex agent profiles, and 50 Python execution scripts. + +Full audits are treated as multi-agent work by default. SEO Dungeon asks the +selected runtime to fan out specialist audit workers in parallel whenever that +runtime supports it, and delegated workers inherit the selected strength profile: +Warrior stays extra-high, Samurai stays high, and Knight stays medium. + +| Area | Coverage | +|------|----------| +| Audit | Full-site audits, page audits, technical SEO, schema, sitemap, image SEO, hardened URL safety | +| Content | E-E-A-T, content briefs, semantic clustering, SXO, competitor pages, QRG-aligned quality gates | +| Growth | Local SEO, maps intelligence, backlinks, e-commerce, programmatic SEO | +| Monitoring | SEO drift baselines and comparisons | +| Data | Google SEO APIs, DataForSEO, Firecrawl, Ahrefs, Bing Webmaster, Profound, SE Ranking, Unlighthouse | +| Assets | SEO image generation planning through the optional Banana/Gemini extension mirror | +| Framework | FLOW prompts for Find, Leverage, Optimize, Win, and local workflows | + +## Quick Start + +### Prerequisites + +- Node.js 22+ +- Python 3.10+ +- Git +- Codex CLI installed and signed in for the packaged default runtime +- Optional: Claude Code CLI or Gemini CLI for the runtime picker options + +### Install Codex Skills + +```powershell +# Windows +.\install.ps1 +``` + +```bash +# macOS/Linux +bash install.sh +``` + +The installer places the SEO skills under your Codex home and copies the Codex +TOML profiles into the Codex agents folder. The portable `agents/` Markdown +prompts remain in the repository for compatible non-Codex agent workflows. + +### Run The Game + +```bash +cd dungeon +npm install +npm run dev +``` + +Open [http://localhost:3002](http://localhost:3002). The bridge server starts on +port `3003`. + +For live development visibility, keep a second terminal open: + +```bash +cd dungeon +npm run logs +``` + +The bridge mirrors startup, runtime selection, CLI executable paths, child +exits, and errors to `dungeon/.logs/bridge.log`. + +### Codex Remote Control + +When the app and bridge are running, Codex can use the local helper to drive the +browser-owned setup and Guild Ledger paths: + +```powershell +cd dungeon +npm run remote -- status --json +npm run remote -- event --wait --timeout 30000 --kind ui-intent --action launch --domain seodungeon.com --project E:\seo-dungeon-website --runtime codex --profile fast --character knight --dangerous-bypass --meta source=codex-helper +npm run remote -- send --wait --timeout 120000 --project E:\seo-dungeon-website --profile fast --dangerous-bypass -- "/seo page https://seodungeon.com" +npm run remote -- watch --kind ledger-result --filter-source guild-ledger --count 1 --timeout 30000 +``` + +The helper talks to the localhost WebSocket bridge. It does not automate the +Codex desktop composer; the browser applies `ui-intent` setup/start actions and +the Guild Ledger claims `send` commands through the normal Codex app-server +runtime. `event --wait` waits for a matching browser `ui-result`; `watch` remains +available for passive session observation. + +To record a browser-side walkthrough of the structured intent path: + +```powershell +cd dungeon +npm run demo:remote-intents -- --keep-open-ms 100 +``` + +The recorder uses isolated dynamic ports, drives `launch`, Gate resume, Hall +issue selection, Battle attack, queue steer/stop/clear, and remote vanquish +through `npm run remote -- event --wait`, then writes a WebM, screenshot, +manifest, session log, ledger transcript, and CLI result receipts under +`dungeon/.logs/remote-intents-demo//`. This is the fast browser proof +lane for recursive testing before a full desktop capture. + +To record the same structured intent path as a full Windows desktop capture: + +```powershell +cd dungeon +npm run proof:desktop-intents -- --fake-codex --keep-open-ms 100 --allow-foreground-mismatch +``` + +This writes an MP4 at the current desktop resolution, early and late frames, +browser screenshot, manifest, session log, ledger transcript, and CLI receipts +under `dungeon/.logs/desktop-intents-proof//`. The default +fake-Codex mode is for recursive smoke testing. Release/demo proof should use +`--real-codex --position-codex-window`, Codex visible on the left, SEO Dungeon +visible on the right, and no `--allow-foreground-mismatch`. + +Runtime environment: + +| Variable | Default | Purpose | +|----------|---------|---------| +| `SEO_DUNGEON_RUNTIME` | `codex` | Bridge fallback runtime when the UI does not send one | +| `SEO_DUNGEON_CODEX_CLI` | `codex` | Codex executable override | +| `SEO_DUNGEON_CODEX_TRANSPORT` | `app-server` | Set to `exec` to use the older `codex exec --json` transport | +| `SEO_DUNGEON_CODEX_DANGEROUS_BYPASS` | unset | Set to `1` to force Codex YOLO mode from the bridge when no UI setting is provided | +| `SEO_DUNGEON_CODEX_BYPASS` | unset | Short alias for `SEO_DUNGEON_CODEX_DANGEROUS_BYPASS` | +| `SEO_DUNGEON_SESSION_LOG` | `.logs/session-events.jsonl` from `npm start` | Local bounded remote session ledger; set to `0` to disable | +| `SEO_DUNGEON_CLAUDE_CLI` | `claude` | Claude Code executable override | +| `SEO_DUNGEON_GEMINI_CLI` | `gemini` | Gemini CLI executable override | +| `SEO_DUNGEON_CODEX_MODEL` | Codex default | Optional Codex model override | +| `SEO_DUNGEON_CODEX_EFFORT_DEEP` | `xhigh` | Codex Warrior effort | +| `SEO_DUNGEON_CODEX_EFFORT_BALANCED` | `high` | Codex Samurai effort | +| `SEO_DUNGEON_CODEX_EFFORT_FAST` | `medium` | Codex Knight effort | +| `SEO_DUNGEON_CLAUDE_MODEL_DEEP` | `opus` | Claude Warrior model alias | +| `SEO_DUNGEON_CLAUDE_MODEL_BALANCED` | `sonnet` | Claude Samurai model alias | +| `SEO_DUNGEON_CLAUDE_MODEL_FAST` | `haiku` | Claude Knight model alias | +| `SEO_DUNGEON_GEMINI_MODEL_DEEP` | `pro` | Gemini Warrior model alias | +| `SEO_DUNGEON_GEMINI_MODEL_BALANCED` | `flash` | Gemini Samurai model alias | +| `SEO_DUNGEON_GEMINI_MODEL_FAST` | `flash-lite` | Gemini Knight model alias | +| `GEMINI_API_KEY` | unset | Required by Gemini CLI when it is not authenticated through another supported Gemini CLI auth path | +| `SEO_DUNGEON_CLAUDE_ARGS` | `--print --output-format text --permission-mode acceptEdits` | Claude CLI argument template | +| `SEO_DUNGEON_GEMINI_ARGS` | `--prompt {{prompt}} --output-format text --approval-mode auto_edit` | Gemini CLI argument template | + +Set a model variable to `default`, `auto`, or `none` to let that CLI use its own +configured default model. + +### Project API Credentials + +SEO Dungeon treats the selected project folder as the credential source for +audit integrations. Add a `.env` or `.env.local` file at that project root when +you want live data: + +```bash +DATAFORSEO_USERNAME=your-login +DATAFORSEO_PASSWORD=your-password +FIRECRAWL_API_KEY=fc-your-api-key +GOOGLE_API_KEY=your-google-api-key +GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json +GSC_SITE_URL=https://example.com/ +GA4_PROPERTY_ID=123456789 +``` + +The bridge forwards known SEO-related keys from the project `.env` into the +selected local CLI. DataForSEO, Firecrawl, and Google workflows should use those +credentials directly first. MCP servers are optional adapters: if you already +have one configured, an agent may use it quietly, but SEO Dungeon does not +require MCP setup for audits. + +First audits can take 5-10 minutes because `/seo audit` fans out multiple +specialist passes. Cached audits are much faster. + +## Commands + +| Command | What it does | +|---------|-------------| +| `/seo audit ` | Full website audit | +| `/seo page ` | Deep single-page analysis | +| `/seo technical ` | Technical SEO audit | +| `/seo content ` | E-E-A-T and content quality | +| `/seo content-brief ` | Detailed SEO content brief | +| `/seo schema ` | Schema.org detection and generation | +| `/seo sitemap ` | XML sitemap analysis or generation | +| `/seo images ` | Image SEO analysis | +| `/seo geo ` | AI search readiness | +| `/seo plan ` | Strategic SEO planning | +| `/seo flow [stage] [url|topic]` | FLOW framework prompts | +| `/seo cluster ` | Semantic clustering | +| `/seo sxo ` | Search experience optimization | +| `/seo drift baseline ` | Capture drift baseline | +| `/seo drift compare ` | Compare against drift baseline | +| `/seo ecommerce ` | E-commerce SEO | +| `/seo programmatic [url]` | Programmatic SEO | +| `/seo competitor-pages [url]` | Competitor comparison pages | +| `/seo local ` | Local SEO | +| `/seo maps [cmd] [args]` | Maps intelligence | +| `/seo hreflang ` | International SEO | +| `/seo google [cmd] [url]` | Google SEO APIs | +| `/seo backlinks ` | Backlink analysis | +| `/seo dataforseo [cmd]` | DataForSEO extension | +| `/seo firecrawl [cmd] ` | Firecrawl extension | +| `/seo image-gen [use-case]` | SEO image generation planning extension | + +## Architecture + +```text +seo-dungeon/ + dungeon/ # Phaser game and WebSocket bridge + server/index.js # Local CLI bridge + src/scenes/ # Game scenes + src/utils/ # Sound, WebSocket client, colors, particles + skills/ # 25 SEO engine skills + agents/ # 18 portable Markdown agent prompts + agents-codex/ # 23 Codex TOML agent profiles + scripts/ # 50 Python SEO scripts + schema/ # JSON-LD templates + extensions/ # Optional SEO data, crawl, and asset add-ons +``` + +## Troubleshooting + +| Problem | Fix | +|---------|-----| +| "The dungeon is unreachable" | Bridge server is not running. Run `npm run server` in `dungeon/`. | +| Skills not found by Codex | Run `install.ps1` or `install.sh` from the repo root. | +| Codex, Claude, or Gemini fails to spawn | Confirm the selected CLI is installed, signed in, and available on `PATH`. On Windows, the bridge resolves `.ps1`, `.cmd`, `.bat`, and `.exe` shims before launching; override `SEO_DUNGEON_CODEX_CLI`, `SEO_DUNGEON_CLAUDE_CLI`, or `SEO_DUNGEON_GEMINI_CLI` if your CLI lives elsewhere. | +| Audit takes a long time | Normal for first full-site audits. Use cached audits when available. | +| Google API commands fail | Run `/seo google` for setup instructions. | +| Drift baseline not found | Run `/seo drift baseline ` before `/seo drift compare `. | + +## Asset Credits + +| Asset | Creator | License | Source | +|-------|---------|---------|--------| +| DungeonTileset II | 0x72 | CC0 | [itch.io](https://0x72.itch.io/dungeontileset-ii) | +| Medieval Warrior Pack | LuizMelo | Free for personal and commercial use | [itch.io](https://luizmelo.itch.io/medieval-warrior-pack-2) | +| Martial Hero Pack | LuizMelo | Free for personal and commercial use | [itch.io](https://luizmelo.itch.io/martial-hero) | +| RPG GUI Construction Kit v1.0 | Lamoot | CC-BY 3.0 | [OpenGameArt](https://opengameart.org/content/rpg-gui-construction-kit-v10) | +| Golden UI | Buch | CC0 | [OpenGameArt](https://opengameart.org/content/golden-ui) | + +## License + +[MIT](LICENSE) - Copyright (c) 2026 Avalon Reset. + +SEO engine code is derived from Daniel Agrici's open-source SEO skill suite and +used under the MIT license. SEO Dungeon is independent and runs through local +terminal-agent workflows selected in the app. diff --git a/plugins/avalonreset/seo-dungeon/SECURITY.md b/plugins/avalonreset/seo-dungeon/SECURITY.md new file mode 100644 index 00000000..f5b601e6 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/SECURITY.md @@ -0,0 +1,25 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly: + +1. **Do NOT open a public issue** +2. Open a [GitHub Security Advisory](https://github.com/avalonreset/seo-dungeon/security/advisories/new) on this repo +3. Or contact the maintainer directly + +## Response Timeline + +- **Acknowledgment**: Within 72 hours of report +- **Status update**: Within 7 days with initial assessment +- **Resolution**: We aim to release a fix within 30 days for confirmed vulnerabilities + +## Supported Versions + +Only the latest version receives security updates. + +## Security Practices + +- No credentials or API keys are stored in this repository +- The WebSocket bridge runs locally and does not expose ports externally +- The bridge only spawns local `codex exec --json` processes diff --git a/plugins/avalonreset/seo-dungeon/assets/icon.svg b/plugins/avalonreset/seo-dungeon/assets/icon.svg new file mode 100644 index 00000000..a806c523 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/assets/icon.svg @@ -0,0 +1,12 @@ + + SEO Dungeon icon + Gold dungeon shield with crossed swords and search lens. + + + + + + + + + diff --git a/plugins/avalonreset/seo-dungeon/hooks/hooks.json b/plugins/avalonreset/seo-dungeon/hooks/hooks.json new file mode 100644 index 00000000..51d70f75 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/hooks/hooks.json @@ -0,0 +1,20 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Edit|Write", + "hooks": [ + { + "type": "command", + "command": "node", + "args": [ + "${CLAUDE_PLUGIN_ROOT}/hooks/run-python-hook.js", + "${CLAUDE_PLUGIN_ROOT}/hooks/validate-schema.py", + "${tool_input.file_path}" + ] + } + ] + } + ] + } +} diff --git a/plugins/avalonreset/seo-dungeon/hooks/run-python-hook.js b/plugins/avalonreset/seo-dungeon/hooks/run-python-hook.js new file mode 100644 index 00000000..f71d3dcb --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/hooks/run-python-hook.js @@ -0,0 +1,65 @@ +#!/usr/bin/env node +"use strict"; + +const { spawnSync } = require("child_process"); + +function stripWrappingQuotes(value) { + return value.replace(/^["']|["']$/g, ""); +} + +function pythonCandidates() { + const candidates = []; + if (process.env.CLAUDE_SEO_PYTHON) { + candidates.push({ + label: "CLAUDE_SEO_PYTHON", + exe: stripWrappingQuotes(process.env.CLAUDE_SEO_PYTHON), + args: [], + }); + } + candidates.push( + { label: "py -3", exe: "py", args: ["-3"] }, + { label: "python3", exe: "python3", args: [] }, + { label: "python", exe: "python", args: [] }, + ); + return candidates; +} + +function isStoreStubOutput(text) { + return /Microsoft Store|WindowsApps|App execution alias|was not found/i.test(text); +} + +function probe(candidate) { + const script = "import sys; print(sys.executable); print(sys.version.split()[0])"; + const result = spawnSync(candidate.exe, [...candidate.args, "-c", script], { + encoding: "utf8", + }); + const output = `${result.stdout || ""}\n${result.stderr || ""}`; + return result.status === 0 && Boolean((result.stdout || "").trim()) && !isStoreStubOutput(output); +} + +function main() { + const [, , hookScript, ...hookArgs] = process.argv; + if (!hookScript) { + process.exit(0); + } + + for (const candidate of pythonCandidates()) { + if (!probe(candidate)) { + continue; + } + const result = spawnSync(candidate.exe, [...candidate.args, hookScript, ...hookArgs], { + stdio: "inherit", + }); + if (result.error) { + continue; + } + process.exit(result.status === null ? 1 : result.status); + } + + console.error( + "Claude SEO hook could not find Python. Tried CLAUDE_SEO_PYTHON, py -3, python3, python.", + ); + process.exit(1); +} + +main(); diff --git a/plugins/avalonreset/seo-dungeon/hooks/validate-schema.py b/plugins/avalonreset/seo-dungeon/hooks/validate-schema.py new file mode 100644 index 00000000..78590040 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/hooks/validate-schema.py @@ -0,0 +1,179 @@ +#!/usr/bin/env python3 +"""Post-edit schema validation hook for Claude Code. + +Validates JSON-LD schema after file edits. Returns exit code 2 to block +if critical validation errors found. + +Hook configuration in ~/.claude/settings.json: +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Edit|Write", + "hooks": [ + { + "type": "command", + "command": "node", + "args": [ + "${CLAUDE_PLUGIN_ROOT}/hooks/run-python-hook.js", + "${CLAUDE_PLUGIN_ROOT}/hooks/validate-schema.py", + "${tool_input.file_path}" + ] + } + ] + } + ] + } +} + +Note: matcher filters by tool name only (Edit, Write). The script itself +checks if the file contains schema markup before validating. +""" + +import json +import re +import sys +import os +from typing import List + + +def validate_jsonld(content: str) -> List[str]: + """Validate JSON-LD blocks in HTML content.""" + errors = [] + pattern = r'(.*?)' + blocks = re.findall(pattern, content, re.DOTALL | re.IGNORECASE) + + if not blocks: + return [] # No schema found; not an error + + for i, block in enumerate(blocks, 1): + block = block.strip() + try: + data = json.loads(block) + except json.JSONDecodeError as e: + errors.append(f"Block {i}: Invalid JSON; {e}") + continue + + if isinstance(data, list): + for item in data: + errors.extend(_validate_schema_object(item, i)) + elif isinstance(data, dict): + errors.extend(_validate_schema_object(data, i)) + + return errors + + +def _validate_schema_object(obj: dict, block_num: int) -> List[str]: + """Validate a single schema object.""" + errors = [] + prefix = f"Block {block_num}" + + # Check @context + if "@context" not in obj: + errors.append(f"{prefix}: Missing @context") + elif obj["@context"] not in ("https://schema.org", "http://schema.org"): + errors.append(f"{prefix}: @context should be 'https://schema.org'") + + # Check @type + if "@type" not in obj: + errors.append(f"{prefix}: Missing @type") + + # Check for placeholder text + placeholders = [ + "[Business Name]", + "[City]", + "[State]", + "[Phone]", + "[Address]", + "[Your", + "[INSERT", + "REPLACE", + "[URL]", + "[Email]", + ] + text = json.dumps(obj) + for p in placeholders: + if p.lower() in text.lower(): + errors.append(f"{prefix}: Contains placeholder text: {p}") + + # Check for deprecated types + schema_type = obj.get("@type", "") + deprecated = { + "HowTo": "deprecated September 2023", + "SpecialAnnouncement": "deprecated July 31, 2025", + "CourseInfo": "retired June 2025", + "EstimatedSalary": "retired June 2025", + "LearningVideo": "retired June 2025", + "ClaimReview": "retired June 2025; fact-check rich results discontinued", + "VehicleListing": "retired June 2025; vehicle listing structured data discontinued", + } + if schema_type in deprecated: + errors.append(f"{prefix}: @type '{schema_type}' is {deprecated[schema_type]}") + + # Check for restricted types used incorrectly. + # FAQPage is intentionally NOT flagged: Google retired FAQ rich results for + # all sites (May 7, 2026), but the markup still aids AI Mode / AI Overviews + # entity resolution, so it is valid to ship. See skills/seo-schema/SKILL.md. + restricted: dict = {} + if schema_type in restricted: + errors.append(f"{prefix}: @type '{schema_type}' is {restricted[schema_type]}; verify site qualifies") + + return errors + + +def main(): + if len(sys.argv) < 2: + sys.exit(0) + + filepath = sys.argv[1] + + if not os.path.isfile(filepath): + sys.exit(0) + + # Only validate HTML-like files + valid_extensions = (".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte", ".php", ".ejs") + if not filepath.lower().endswith(valid_extensions): + sys.exit(0) + + # File-size guard: skip files >10MB to bound memory + hook latency. + # Real source files almost never exceed this; bigger inputs are typically + # generated, minified bundles or accidental binary writes. + MAX_FILE_BYTES = 10 * 1024 * 1024 # 10 MiB + try: + if os.path.getsize(filepath) > MAX_FILE_BYTES: + sys.exit(0) + except OSError: + sys.exit(0) + + try: + with open(filepath, "r", encoding="utf-8", errors="ignore") as f: + content = f.read() + except (OSError, IOError): + sys.exit(0) + + errors = validate_jsonld(content) + + if not errors: + sys.exit(0) + + # Categorize errors + critical_keywords = ["placeholder", "deprecated", "retired"] + critical = [e for e in errors if any(kw in e.lower() for kw in critical_keywords)] + warnings = [e for e in errors if e not in critical] + + if warnings: + print("WARN Schema validation warnings:") + for w in warnings: + print(f" - {w}") + + if critical: + print("ERROR Schema validation ERRORS (blocking):") + for e in critical: + print(f" - {e}") + sys.exit(2) # Block the edit + + sys.exit(1) # Warnings only; proceed + + +if __name__ == "__main__": + main() diff --git a/plugins/avalonreset/seo-dungeon/pyproject.toml b/plugins/avalonreset/seo-dungeon/pyproject.toml new file mode 100644 index 00000000..eab094da --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/pyproject.toml @@ -0,0 +1,24 @@ +[project] +name = "seo-dungeon" +version = "2.2.16" +description = "Gamified SEO Dungeon skill suite with local AI CLI compatibility" +requires-python = ">=3.10" +license = "MIT" +readme = "README.md" +authors = [ + {name = "Avalon Reset", email = "avalonreset@users.noreply.github.com"}, + {name = "Daniel Agrici", email = "agricidaniel@gmail.com"} +] +keywords = ["seo", "codex", "claude-code", "gemini-cli", "schema-markup", "core-web-vitals", "ai-search", "geo"] + +[project.urls] +Homepage = "https://github.com/avalonreset/seo-dungeon" +Repository = "https://github.com/avalonreset/seo-dungeon" + +[tool.ruff] +target-version = "py310" +line-length = 100 + +[tool.ruff.lint] +select = ["E", "F", "W", "I"] +ignore = ["E501"] diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-audit/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-audit/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-audit/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-audit/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-audit/SKILL.md new file mode 100644 index 00000000..b1c85a69 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-audit/SKILL.md @@ -0,0 +1,182 @@ +--- +name: seo-audit +description: "Full website SEO audit with parallel subagent delegation. Crawls up to 500 pages, detects business type, delegates to up to 15 specialists (8 always + 7 conditional), generates health score. Use when user says audit, full SEO check, analyze my site, or website health check." +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Full Website SEO Audit + +## Process + +1. **Render homepage**: use `python3 scripts/render_page.py --mode auto --json` to capture raw HTML, rendered HTML, extracted text, SPA status, and accessibility data when needed +2. **Detect business type**: analyze homepage signals per seo orchestrator +3. **Crawl site**: follow internal links up to 500 pages, respect robots.txt +4. **Delegate to subagents** concurrently. Use inline sequential work only when the current runtime has no subagent or parallel-agent facility. In SEO Dungeon, preserve the selected strength profile for delegated agents: Warrior/deep = extra-high or highest available effort, Samurai/balanced = high, Knight/fast = medium. + - `seo-technical` -- robots.txt, sitemaps, canonicals, Core Web Vitals, security headers + - `seo-content` -- E-E-A-T, readability, thin content, AI citation readiness + - `seo-schema` -- detection, validation, generation recommendations + - `seo-sitemap` -- structure analysis, quality gates, missing pages + - `seo-performance` -- LCP, INP, CLS measurements + - `seo-visual` -- screenshots, mobile testing, above-fold analysis + - `seo-geo` -- AI crawler access, llms.txt, citability, brand mention signals + - `seo-local` -- GBP signals, NAP consistency, reviews, local schema, industry-specific local factors (spawn when Local Service industry detected: brick-and-mortar, SAB, or hybrid business type) + - `seo-maps` -- Geo-grid rank tracking, GBP audit, review intelligence, competitor radius mapping (spawn when Local Service detected AND DataForSEO credentials/tools are available) + - `seo-google` -- CWV field data (CrUX), URL indexation (GSC), organic traffic (GA4) (spawn when Google API credentials detected via `python3 scripts/google_auth.py --check`) + - `seo-backlinks` -- Backlink profile data: DA/PA, referring domains, anchor text, toxic links (spawn when Moz or Bing API credentials detected via `python3 scripts/backlinks_auth.py --check`, or always include Common Crawl domain-level metrics) + - `seo-cluster` -- Semantic clustering analysis (spawn when content strategy signals detected: blog, pillar pages, topic clusters) + - `seo-sxo` -- Search experience analysis: page-type mismatch, user stories, persona scoring (always include in full audits) + - `seo-drift` -- Drift analysis: compare against stored baseline (spawn when drift baseline exists for the URL via `python3 scripts/drift_history.py `) + - `seo-ecommerce` -- Product schema, marketplace intelligence (spawn when E-commerce industry detected) +5. **Score** -- aggregate into SEO Health Score (0-100) +6. **Persist audit artifacts** -- write all outputs under `{domain}-audit/` +7. **Report** -- generate prioritized action plan and optional PDF/HTML report + +## Crawl Configuration + +``` +Max pages: 500 +Respect robots.txt: Yes +Follow redirects: Yes (max 3 hops) +Timeout per page: 30 seconds +Concurrent requests: 5 +Delay between requests: 1 second +``` + +## Output Files + +- `{domain}-audit/FULL-AUDIT-REPORT.md`: Comprehensive findings +- `{domain}-audit/ACTION-PLAN.md`: Prioritized recommendations (Critical > High > Medium > Low) +- `{domain}-audit/audit-data.json`: Structured audit envelope for report generation +- `{domain}-audit/findings/*.md`: Per-category specialist findings (`technical.md`, `content.md`, `schema.md`, `performance.md`, `visual.md`, etc.) +- `{domain}-audit/screenshots/`: Desktop + mobile captures (if Playwright available) +- **PDF Report** (recommended): Generate a professional A4 PDF using `scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain --output-dir {domain}-audit/`. This produces a white-cover enterprise report with TOC, executive summary, charts (Lighthouse gauges, query bars, index donut), metric cards, threshold tables, prioritized recommendations with effort estimates, and implementation roadmap. Always offer PDF generation after completing an audit. + +## Structured Audit Data Envelope + +Write `{domain}-audit/audit-data.json` with this shape so `python3 scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain --output-dir {domain}-audit/` can generate a report even when Google API data is unavailable: + +```json +{ + "summary": { + "health_score": 0, + "business_type": "detected type", + "top_findings": [], + "quick_wins": [] + }, + "categories": [ + { + "name": "Technical SEO", + "score": 0, + "what_works": [], + "findings": [ + { + "title": "Finding title", + "severity": "Critical|High|Medium|Low|Info", + "description": "Evidence-backed detail", + "recommendation": "Specific fix" + } + ] + } + ], + "action_plan": { + "phases": [ + {"name": "Phase 1: Critical Fixes", "timeframe": "Week 1", "items": []}, + {"name": "Phase 2: High-Impact Improvements", "timeframe": "Weeks 2-3", "items": []}, + {"name": "Phase 3: Content & Authority", "timeframe": "Month 2", "items": []}, + {"name": "Phase 4: Monitoring & Iteration", "timeframe": "Ongoing", "items": []} + ] + }, + "artifacts": { + "findings_dir": "findings/", + "screenshots_dir": "screenshots/" + } +} +``` + +## Scoring Weights + +| Category | Weight | +|----------|--------| +| Technical SEO | 22% | +| Content Quality | 23% | +| On-Page SEO | 20% | +| Schema / Structured Data | 10% | +| Performance (CWV) | 10% | +| AI Search Readiness | 10% | +| Images | 5% | + +## Report Structure + +### Executive Summary +- Overall SEO Health Score (0-100) +- Business type detected +- Top 5 critical issues +- Top 5 quick wins + +### Technical SEO +- Crawlability issues +- Indexability problems +- Security concerns +- Core Web Vitals status + +### Content Quality +- E-E-A-T assessment +- Thin content pages +- Duplicate content issues +- Readability scores + +### On-Page SEO +- Title tag issues +- Meta description problems +- Heading structure +- Internal linking gaps + +### Schema & Structured Data +- Current implementation +- Validation errors +- Missing opportunities + +### Performance +- LCP, INP, CLS scores +- Resource optimization needs +- Third-party script impact + +### Images +- Missing alt text +- Oversized images +- Format recommendations + +### AI Search Readiness +- Citability score +- Structural improvements +- Authority signals + +## Priority Definitions + +- **Critical**: Blocks indexing or causes penalties (fix immediately) +- **High**: Significantly impacts rankings (fix within 1 week) +- **Medium**: Optimization opportunity (fix within 1 month) +- **Low**: Nice to have (backlog) + +## DataForSEO Integration (Optional) + +If DataForSEO credentials or optional tools are available, spawn the `seo-dataforseo` agent alongside existing subagents to enrich the audit with live data: real SERP positions, backlink profiles with spam scores, on-page analysis (Lighthouse), business listings, and AI visibility checks (ChatGPT scraper, LLM mentions). Do not block the audit on DataForSEO; fall back to deterministic/free sources when credentials are absent. + +## Google API Integration (Optional) + +If Google API credentials are configured (`python3 scripts/google_auth.py --check`), spawn the `seo-google` agent to enrich the audit with real Google field data: CrUX Core Web Vitals (replaces lab-only estimates), GSC URL indexation status, search performance (clicks, impressions, CTR), and GA4 organic traffic trends. The Performance (CWV) category score benefits most from field data. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site content. Suggest the user verify the URL and try again. | +| robots.txt blocks crawling | Report which paths are blocked. Analyze only accessible pages and note the limitation in the report. | +| Rate limiting (429 responses) | Back off and reduce concurrent requests. Report partial results with a note on which sections could not be completed. | +| Timeout on large sites (500+ pages) | Cap the crawl at the timeout limit. Report findings for pages crawled and estimate total site scope. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-backlinks/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-backlinks/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-backlinks/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-backlinks/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-backlinks/SKILL.md new file mode 100644 index 00000000..5ccaab46 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-backlinks/SKILL.md @@ -0,0 +1,264 @@ +--- +name: seo-backlinks +description: "Backlink profile analysis: referring domains, anchor text distribution, toxic link detection, competitor gap analysis. Works with free APIs (Moz, Bing Webmaster, Common Crawl) and DataForSEO extension. Use when user says backlinks, link profile, referring domains, anchor text, toxic links, link gap, link building, disavow, or backlink audit." +user-invocable: true +argument-hint: "" +license: MIT +compatibility: "Free: Common Crawl + verify always available. Optional: Moz API, Bing Webmaster (free signup). Premium: DataForSEO extension." +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Backlink Profile Analysis + +## Source Detection + +Before analysis, detect available data sources: + +1. **DataForSEO MCP** (premium): Check if `dataforseo_backlinks_summary` tool is available +2. **Moz API** (free signup): `python3 scripts/backlinks_auth.py --check moz --json` +3. **Bing Webmaster** (free signup): `python3 scripts/backlinks_auth.py --check bing --json` +4. **Common Crawl** (always available): Domain-level graph with PageRank +5. **Verification Crawler** (always available): Checks if known backlinks still exist + +Run `python3 scripts/backlinks_auth.py --check --json` to detect all sources at once. + +If no sources are configured beyond the always-available tier: +- Still produce a report using Common Crawl domain metrics +- Suggest: "Run `/seo backlinks setup` to add free Moz and Bing API keys for richer data" + +## Quick Reference + +| Command | Purpose | +|---------|---------| +| `/seo backlinks ` | Full backlink profile analysis (uses all available sources) | +| `/seo backlinks gap ` | Competitor backlink gap analysis | +| `/seo backlinks toxic ` | Toxic link detection and disavow recommendations | +| `/seo backlinks new ` | New and lost backlinks (DataForSEO only) | +| `/seo backlinks verify --links ` | Verify known backlinks still exist | +| `/seo backlinks setup` | Show setup instructions for free backlink APIs | + +## Analysis Framework + +Produce all 7 sections below. Each section lists data sources in preference order. + +### 1. Profile Overview + +**DataForSEO:** `dataforseo_backlinks_summary` → total backlinks, referring domains, domain rank, follow ratio, trend. + +**Moz API:** `python3 scripts/moz_api.py metrics --json` → Domain Authority, Page Authority, Spam Score, linking root domains, external links. + +**Common Crawl:** `python3 scripts/commoncrawl_graph.py --json` → in-degree (referring domain count), PageRank, harmonic centrality. + +**Scoring:** + +| Metric | Good | Warning | Critical | +|--------|------|---------|----------| +| Referring domains | >100 | 20-100 | <20 | +| Follow ratio | >60% | 40-60% | <40% | +| Domain diversity | No single domain >5% | 1 domain >10% | 1 domain >25% | +| Trend | Growing or stable | Slow decline | Rapid decline (>20%/quarter) | + +### 2. Anchor Text Distribution + +**DataForSEO:** `dataforseo_backlinks_anchors` + +**Moz API:** `python3 scripts/moz_api.py anchors --json` + +**Bing Webmaster:** `python3 scripts/bing_webmaster.py links --json` (extract anchor text from link details) + +**Healthy distribution benchmarks:** + +| Anchor Type | Target Range | Over-Optimization Signal | +|-------------|-------------|-------------------------| +| Branded (company/domain name) | 30-50% | <15% | +| URL/naked link | 15-25% | N/A | +| Generic ("click here", "learn more") | 10-20% | N/A | +| Exact match keyword | 3-10% | >15% | +| Partial match keyword | 5-15% | >25% | +| Long-tail / natural | 5-15% | N/A | + +Flag if exact-match anchors exceed 15% -- this is a Google Penguin risk signal. + +### 3. Referring Domain Quality + +**DataForSEO:** `dataforseo_backlinks_referring_domains` + +**Moz API:** `python3 scripts/moz_api.py domains --json` → domains with DA scores + +**Common Crawl:** `python3 scripts/commoncrawl_graph.py --json` → top referring domains (domain-level, no authority scores) + +Analyze: +- **TLD distribution**: .edu, .gov, .org = high authority. Excessive .xyz, .info = low quality +- **Country distribution**: Match target market. 80%+ from irrelevant countries = PBN signal +- **Domain rank distribution**: Healthy profiles have links from all authority tiers +- **Follow/nofollow per domain**: Sites that only nofollow = limited SEO value + +### 4. Toxic Link Detection + +**DataForSEO:** `dataforseo_backlinks_bulk_spam_score` + toxic patterns from reference + +**Moz API:** Spam Score from `python3 scripts/moz_api.py metrics --json` (1-17% scale, >11% = high risk) + +**Verification Crawler:** `python3 scripts/verify_backlinks.py --target --links --json` (verify suspicious links still exist) + +**High-risk indicators (flag immediately):** +- Links from known PBN (Private Blog Network) domains +- Unnatural anchor text patterns (100% exact match from a domain) +- Links from penalized or deindexed domains +- Mass directory submissions (50+ directory links) +- Link farms (sites with 10K+ outbound links per page) +- Paid link patterns (footer/sidebar links across all pages of a domain) + +**Medium-risk indicators (review manually):** +- Links from unrelated niches +- Reciprocal link patterns +- Links from thin content pages (<100 words) +- Excessive links from a single domain (>50 backlinks from 1 domain) + +Load `references/backlink-quality.md` for the full 30 toxic patterns and disavow criteria. + +### 5. Top Pages by Backlinks + +**DataForSEO:** `dataforseo_backlinks_backlinks` with target type "page" + +**Moz API:** `python3 scripts/moz_api.py pages --json` + +Find: +- Which pages attract the most backlinks +- Pages with high-authority links (link magnets) +- Pages with zero backlinks (internal linking opportunities) +- 404 pages with backlinks (redirect opportunities to reclaim link equity) + +### 6. Competitor Gap Analysis + +**DataForSEO:** `dataforseo_backlinks_referring_domains` for both domains, then compare + +**Bing Webmaster (unique!):** `python3 scripts/bing_webmaster.py compare --json` — the only free tool with built-in competitor comparison + +**Moz API:** Compare DA/PA between domains via `python3 scripts/moz_api.py metrics --json` for each + +Output: +- Domains linking to competitor but NOT to target = link building opportunities +- Domains linking to both = validate existing relationships +- Domains linking only to target = competitive advantage +- Top 20 link building opportunities with domain authority + +### 7. New and Lost Backlinks + +**DataForSEO only:** `dataforseo_backlinks_backlinks` with date filters for 30/60/90 day changes + +**Verification Crawler:** For known links, verify current status with `python3 scripts/verify_backlinks.py` + +**Note:** Free sources cannot track new/lost links over time. If this section is requested without DataForSEO, inform the user: "Link velocity tracking requires the DataForSEO extension. Free sources provide point-in-time snapshots only." + +**Red flags:** +- Sudden spike in new links (possible negative SEO attack) +- Sudden loss of many links (site penalty or content removal) +- Declining velocity over 3+ months (content not attracting links) + +## Backlink Health Score + +Calculate a 0-100 score. When mixing sources, apply confidence weighting: + +| Factor | Weight | Sources (preference order) | Confidence | +|--------|--------|---------------------------|------------| +| Referring domain count | 20% | DataForSEO > Moz > CC in-degree | 1.0 / 0.85 / 0.50 | +| Domain quality distribution | 20% | DataForSEO > Moz DA distribution | 1.0 / 0.85 | +| Anchor text naturalness | 15% | DataForSEO > Moz > Bing anchors | 1.0 / 0.85 / 0.70 | +| Toxic link ratio | 20% | DataForSEO > Moz spam score | 1.0 / 0.85 | +| Link velocity trend | 10% | DataForSEO only | 1.0 | +| Follow/nofollow ratio | 5% | DataForSEO > Bing details | 1.0 / 0.70 | +| Geographic relevance | 10% | DataForSEO > Bing country | 1.0 / 0.70 | + +**Data sufficiency gate:** Count how many of the 7 factors have at least one data source available. +- **4+ factors with data:** Produce a numeric 0-100 score (redistribute missing weights proportionally) +- **Fewer than 4 factors:** Do NOT produce a numeric score. Instead display: + ``` + Backlink Health Score: INSUFFICIENT DATA (X/7 factors scored) + ``` + Show individual factor scores that ARE available with their source and confidence. + Recommend: "Configure Moz API (free) for a scoreable profile. Run `/seo backlinks setup`" + +When only CC is available, cap maximum score at 70/100. +A numeric score with fewer than 4 data sources is **misleading** — it implies poor health when +the reality is we simply lack data. + +## Output Format + +### Backlink Health Score: XX/100 (or INSUFFICIENT DATA) + +| Section | Status | Score | Data Source | +|---------|--------|-------|-------------| +| Profile Overview | pass/warn/fail | XX/100 | Moz (0.85) | +| Anchor Distribution | pass/warn/fail | XX/100 | Moz (0.85) | +| Referring Domain Quality | pass/warn/fail | XX/100 | CC (0.50) | +| Toxic Links | pass/warn/fail | XX/100 | Moz Spam (0.85) | +| Top Pages | info | N/A | Moz (0.85) | +| Link Velocity | pass/warn/fail | XX/100 | DataForSEO only | + +### Critical Issues (fix immediately) +### High Priority (fix within 1 month) +### Medium Priority (ongoing improvement) +### Link Building Opportunities (top 10) + +## Error Handling + +| Error | Cause | Resolution | +|-------|-------|-----------| +| No sources configured | No API keys, no DataForSEO | Run `/seo backlinks setup` | +| Moz rate limit | Free tier: 1 req/10s | Wait 10 seconds, retry. Built into script. | +| Bing site not verified | Site not verified in Bing | Verify at https://www.bing.com/webmasters | +| CC download timeout | Large graph file, slow connection | Use `--timeout 180` flag | +| DataForSEO unavailable | Extension not installed | Run `./extensions/dataforseo/install.sh` | +| No backlink data returned | Domain too new or very small | Note: small sites may have <10 backlinks | + +**Fallback cascade:** +1. DataForSEO available? → Use as primary (confidence: 1.0) +2. Moz configured? → Use for DA/PA/spam/anchors (confidence: 0.85) +3. Bing configured? → Use for links/competitor comparison (confidence: 0.70) +4. Always: Common Crawl for domain-level metrics (confidence: 0.50) +5. Always: Verification crawler for known link checks (confidence: 0.95) +6. Nothing works? → "Run `/seo backlinks setup` to configure free APIs" + +## Pre-Delivery Review (MANDATORY) + +Before presenting any backlink analysis to the user, run this checklist internally. +Do NOT skip this step. Fix any issues found before showing the report. + +### Fact-Check Every Claim +- [ ] **Schema claims**: Did parse_html return `@type` for each block? If any `@type` is missing, + re-check — it may use `@graph` wrapper (valid JSON-LD, not malformed). +- [ ] **"link_removed" findings**: Is the page JS-rendered? If `unverifiable_js`, say so — never + report a JS-rendered page as "link removed" (that's a false negative). +- [ ] **H1 findings**: Are any H1s in the `h1_suspicious` list? If so, note they are likely + counters/stats, not semantic headings. +- [ ] **Reciprocal links**: If site A links to site B AND B links back to A, flag it as a + reciprocal link pattern. Check outbound links against verified inbound sources. +- [ ] **Health score**: Are 4+ of 7 factors scored? If not, report INSUFFICIENT DATA — never + show a misleading numeric score. + +### Verify Data Source Labels +- [ ] Every metric in the report has a source label (e.g., "Parsed (0.95)", "CC (0.50)") +- [ ] Every "not found" result distinguishes between "not crawled" vs "below threshold" vs "error" +- [ ] Social media pages flagged as `unverifiable_js` (not `link_removed`) + +### Cross-Check Consistency +- [ ] Platform detection matches actual signals (check for wp-content, shopify CDN, etc.) +- [ ] Referring domain count in summary matches the actual verified links list +- [ ] No claim is presented without a data source backing it + +If ANY check fails, fix the finding before presenting. Never present inferred data as fact. + +## Post-Analysis + +After completing any backlink analysis command, always offer: +"Generate a professional PDF report? Use `/seo google report`" + +## Reference Documentation + +Load on demand (do NOT load at startup): +- `skills/seo/references/backlink-quality.md` -- Detailed toxic link patterns and scoring methodology (shared reference, load when analyzing toxic links or spam scores) +- `skills/seo/references/free-backlink-sources.md` -- Source comparison, confidence weighting, setup guides (shared reference, load when configuring free backlink APIs) diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-cluster/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/SKILL.md new file mode 100644 index 00000000..0680ed14 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/SKILL.md @@ -0,0 +1,322 @@ +--- +name: seo-cluster +description: > + SERP-based semantic topic clustering for content architecture planning. Groups + keywords by actual Google SERP overlap (not text similarity), designs hub-and-spoke + content clusters with internal link matrices, and generates interactive + visualizations. Optionally executes content creation if claude-blog is installed. + Use when user says "topic cluster", "content cluster", "semantic clustering", + "pillar page", "hub and spoke", "content architecture", "keyword grouping", + or "cluster plan". +user-invocable: true +argument-hint: "" +license: MIT +metadata: + author: AgriciDaniel + original_author: "Lutfiya Miller (Pro Hub Challenge Winner)" + version: "2.2.16" + category: seo +--- + +# Semantic Topic Clustering (v1.9.0) + +SERP-overlap-driven keyword clustering for content architecture. Groups keywords +by how Google actually ranks them (shared top-10 results), not by text similarity. +Designs hub-and-spoke content clusters with internal link matrices and generates +interactive cluster map visualizations. + +**Scripts:** Located at the plugin root `scripts/` directory. + +--- + +## Quick Reference + +| Command | What it does | +|---------|-------------| +| `/seo cluster plan ` | Full planning workflow: expand, cluster, architect, visualize | +| `/seo cluster plan --from strategy` | Import from existing `/seo plan` output | +| `/seo cluster execute` | Execute plan: create content via claude-blog or output briefs | +| `/seo cluster map` | Regenerate the interactive cluster visualization | + +--- + +## Planning Workflow + +### Step 1: Seed Keyword Expansion + +Expand the seed keyword into 30-50 variants using WebSearch: + +1. **Related searches** — Search the seed, extract "related searches" and "people also search for" +2. **People Also Ask (PAA)** — Extract all PAA questions from SERP results +3. **Long-tail modifiers** — Append common modifiers: "best", "how to", "vs", "for beginners", "tools", "examples", "guide", "template", "mistakes", "checklist" +4. **Question mining** — Generate who/what/when/where/why/how variants +5. **Intent modifiers** — Add commercial modifiers: "pricing", "review", "alternative", "comparison", "free", "top" + +**Deduplication:** Normalize variants (lowercase, strip articles), remove exact duplicates. +Target: 30-50 unique keyword variants. If under 30, run a second expansion pass +with the top PAA questions as seeds. + +### Step 2: SERP Overlap Clustering + +This is the core differentiator. Load `references/serp-overlap-methodology.md` for +the full algorithm. + +**Process:** +1. Group keywords by initial intent guess (reduces pairwise comparisons) +2. For each candidate pair within a group, WebSearch both keywords +3. Count shared URLs in the top 10 organic results (ignore ads, featured snippets, PAA) +4. Apply thresholds: + +| Shared Results | Relationship | Action | +|---------------|-------------|--------| +| 7-10 | Same post | Merge into single target page | +| 4-6 | Same cluster | Group under same spoke cluster | +| 2-3 | Interlink | Place in adjacent clusters, add cross-links | +| 0-1 | Separate | Assign to different clusters or exclude | + +**Optimization:** With 40 keywords, full pairwise = 780 comparisons. Instead: +- Pre-group by intent (4 groups of ~10 = 4 x 45 = 180 comparisons) +- Only cross-check group boundary keywords +- Skip pairs where both are long-tail variants of the same head term (assume same cluster) + +**DataForSEO integration:** If DataForSEO MCP is available, use `serp_organic_live_advanced` +instead of WebSearch for SERP data. Run `python3 scripts/dataforseo_costs.py check serp_organic_live_advanced --count N` +before each batch. If `"status": "needs_approval"`, show cost estimate and ask user. +If `"status": "blocked"`, fall back to WebSearch. + +### Step 3: Intent Classification + +Classify each keyword into one of four intent categories: + +| Intent | Signals | Include in Clusters? | +|--------|---------|---------------------| +| Informational | how, what, why, guide, tutorial, learn | Yes | +| Commercial | best, top, review, comparison, vs, alternative | Yes | +| Transactional | buy, price, discount, coupon, order, sign up | Yes | +| Navigational | brand names, specific product names, login | No (exclude) | + +Remove navigational keywords from clustering. Flag borderline cases for +manual review. Keywords can have mixed intent (e.g., "best CRM software" is +both commercial and informational) -- classify by dominant intent. + +### Step 4: Hub-and-Spoke Architecture + +Load `references/hub-spoke-architecture.md` for full specifications. + +**Design the cluster structure:** + +1. **Select the pillar keyword** — Highest volume, broadest intent, most SERP overlap with other keywords +2. **Group spokes into clusters** — Each cluster is a subtopic area (2-5 clusters per pillar) +3. **Assign posts to clusters** — Each cluster gets 2-4 spoke posts +4. **Select templates per post** — Based on intent classification: + +| Intent Pattern | Template Options | +|---------------|-----------------| +| Informational (broad) | ultimate-guide | +| Informational (how) | how-to | +| Informational (list) | listicle | +| Informational (concept) | explainer | +| Commercial (compare) | comparison | +| Commercial (evaluate) | review | +| Commercial (rank) | best-of | +| Transactional | landing-page | + +5. **Set word count targets:** + - Pillar page: 2500-4000 words + - Spoke posts: 1200-1800 words + +6. **Cannibalization check** — No two posts share the same primary keyword. If SERP + overlap is 7+, merge those keywords into a single post targeting both. + +### Step 5: Internal Link Matrix + +Design the bidirectional linking structure: + +| Link Type | Direction | Requirement | +|-----------|-----------|-------------| +| Spoke to pillar | spoke -> pillar | Mandatory (every spoke) | +| Pillar to spoke | pillar -> spoke | Mandatory (every spoke) | +| Spoke to spoke (within cluster) | spoke <-> spoke | 2-3 links per post | +| Cross-cluster | spoke -> spoke (other cluster) | 0-1 links per post | + +**Rules:** +- Every post must have minimum 3 incoming internal links +- No orphan pages (every post reachable from pillar in 2 clicks) +- Anchor text must use target keyword or close variant (no "click here") +- Link placement: within body content, not just navigation/sidebar + +Generate the link matrix as a JSON adjacency list: +```json +{ + "links": [ + { "from": "pillar", "to": "cluster-0-post-0", "type": "mandatory", "anchor": "keyword" }, + { "from": "cluster-0-post-0", "to": "pillar", "type": "mandatory", "anchor": "keyword" } + ] +} +``` + +### Step 6: Interactive Cluster Map + +Generate `cluster-map.html` using the template at `templates/cluster-map.html`. + +1. Read the template file +2. Build the `CLUSTER_DATA` JSON object from the cluster plan: + ```javascript + { + pillar: { title, keyword, volume, template, wordCount, url }, + clusters: [{ name, color, posts: [{ title, keyword, volume, template, wordCount, url, status }] }], + links: [{ from, to, type }], + meta: { totalPosts, totalClusters, totalLinks, estimatedWords } + } + ``` +3. Replace the `CLUSTER_DATA` placeholder in the template with the actual JSON +4. Write the completed HTML file to the output directory +5. Inform user: "Open `cluster-map.html` in a browser to explore the interactive cluster map." + +--- + +## Strategy Import + +When invoked with `--from strategy`: + +1. Look for the most recent `/seo plan` output in the current directory (search for + files matching `*SEO*Plan*`, `*strategy*`, `*content-strategy*`) +2. Parse markdown tables for: keywords, page types, content pillars, URL structures +3. Validate extracted data: check for duplicates, missing keywords, incomplete entries +4. Enrich with SERP data: run SERP overlap analysis on extracted keywords +5. Build cluster plan using the imported keywords as the starting set (skip Step 1) + +If no strategy file is found, prompt the user: "No existing SEO plan found in the +current directory. Run `/seo plan` first, or provide a seed keyword for fresh clustering." + +--- + +## Execution Workflow + +When `/seo cluster execute` is invoked: + +### Check for claude-blog + +``` +Test: Does ~/.claude/skills/blog/SKILL.md exist? +``` + +**If claude-blog IS installed:** + +1. Load `references/execution-workflow.md` for the full algorithm +2. Read `cluster-plan.json` from the current directory +3. Check for resume state: scan output directory for already-written posts +4. Execute in priority order: pillar first, then spokes by volume (highest first) +5. For each post, invoke the `blog-write` skill with cluster context: + - Cluster role (pillar or spoke) + - Position in cluster (cluster index, post index) + - Target keyword and secondary keywords + - Template type and word count target + - Internal links to include (with anchors) + - Links to receive from future posts (placeholder markers) +6. After each post is written, scan previous posts for backward link placeholders + and inject the new post's URL +7. After all posts are written, generate the cluster scorecard + +**If claude-blog is NOT installed:** + +1. Generate detailed content briefs for each post in the cluster plan +2. Each brief includes: + - Title and meta description + - Primary keyword and secondary keywords + - Template type and suggested structure (H2/H3 outline) + - Word count target + - Internal links to include (with anchor text) + - Key points to cover + - Competing pages to differentiate from +3. Write briefs to `cluster-briefs/` directory as individual markdown files +4. Inform user: "Install [claude-blog](https://github.com/AgriciDaniel/claude-blog) + to auto-create content. Briefs saved to `cluster-briefs/`." + +--- + +## Cluster Scorecard + +Post-execution quality report. Run automatically after `/seo cluster execute` or +on demand via analysis of the output directory. + +| Metric | Target | How Measured | +|--------|--------|-------------| +| Coverage | 100% | Posts written / posts planned | +| Link Density | 3+ per post | Count internal links per post | +| Orphan Pages | 0 | Posts with < 1 incoming link | +| Cannibalization | 0 conflicts | Check for duplicate primary keywords | +| Image Count | 1+ per post | Posts with at least one image | +| Pillar Links | 100% | All spokes link to pillar and vice versa | +| Cross-Links | 80%+ | Recommended spoke-to-spoke links implemented | +| Content Gaps | 0 | Planned posts that were skipped or incomplete | + +--- + +## Map Regeneration + +When `/seo cluster map` is invoked: + +1. Read `cluster-plan.json` from the current directory +2. Scan output directory and update post statuses (planned vs written) +3. Regenerate `cluster-map.html` with updated statuses +4. Report: posts written vs planned, link completion percentage + +--- + +## Output Files + +All outputs are written to the current working directory: + +| File | Description | +|------|-------------| +| `cluster-plan.json` | Machine-readable cluster plan (full data) | +| `cluster-plan.md` | Human-readable cluster plan summary | +| `cluster-map.html` | Interactive SVG visualization | +| `cluster-briefs/` | Content briefs (if no claude-blog) | +| `cluster-scorecard.md` | Post-execution quality report | + +--- + +## Cross-Skill Integration + +| Skill | Relationship | +|-------|-------------| +| `seo-plan` | Import source: strategy import reads seo-plan output | +| `seo-content` | Quality check: E-E-A-T validation of generated content | +| `seo-schema` | Schema markup: Article, BreadcrumbList, ItemList for cluster pages | +| `seo-dataforseo` | Data source: SERP data when DataForSEO MCP is available | +| `seo-google` | Reporting: generate PDF report of cluster plan and scorecard | + +After cluster planning or execution completes, offer: +"Generate a PDF report? Use `/seo google report`" + +--- + +## Error Handling + +| Error | Cause | Resolution | +|-------|-------|------------| +| "No seed keyword provided" | Missing argument | Prompt user for seed keyword or URL | +| "Insufficient keyword variants" | Expansion yielded < 15 keywords | Run second expansion pass with PAA questions | +| "SERP data unavailable" | WebSearch and DataForSEO both failing | Retry after 30s; if persistent, use intent-only clustering with warning | +| "No strategy file found" | `--from strategy` but no plan exists | Prompt user to run `/seo plan` first | +| "cluster-plan.json not found" | Execute without planning | Prompt user to run `/seo cluster plan` first | +| "claude-blog not installed" | Execute attempted without blog skill | Generate content briefs instead; suggest installation | +| "DataForSEO budget exceeded" | Cost check returned "blocked" | Fall back to WebSearch; inform user | +| "Duplicate primary keywords" | Cannibalization detected | Merge affected posts or reassign keywords | +| "Orphan page detected" | Post missing incoming links | Add links from nearest cluster siblings | +| "Resume state corrupted" | Mismatch between plan and output | Rebuild state from output directory scan | + +--- + +## Security + +- All URLs fetched via `python3 scripts/render_page.py --mode auto` (SPA-aware SSRF protection via `url_safety`) +- No credentials stored or transmitted +- Output files contain no PII or API keys +- DataForSEO cost checks run before every API call + +## FLOW Framework Integration + +For prompt-guided keyword research and gap analysis, use `/seo flow find [url|topic]` — FLOW's 5 find-stage prompts complement the SERP-overlap clustering methodology with structured discovery prompts. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/execution-workflow.md b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/execution-workflow.md new file mode 100644 index 00000000..c98382fc --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/execution-workflow.md @@ -0,0 +1,180 @@ +# Execution Workflow + +## Overview + +The execution phase transforms a `cluster-plan.json` into actual content. It handles +priority ordering, context injection for the blog writer, backward link updates, +resume capability, and post-execution quality scoring. + +## Priority Algorithm + +Content is created in this strict order: + +1. **Pillar page first** -- The hub must exist before any spokes can link to it +2. **Spokes by search volume (descending)** -- Highest-volume spokes first for + maximum early impact +3. **Within same volume, by cluster index** -- Process Cluster 0 before Cluster 1 +4. **Within same cluster, by post index** -- Process Post 0 before Post 1 + +Rationale: The pillar establishes the topical authority foundation. High-volume +spokes generate the most organic traffic, so they should be published earliest +for faster compounding returns. + +## Cluster Context Injection + +When invoking `blog-write` for each post, pass a structured context block: + +```json +{ + "cluster_context": { + "role": "pillar|spoke", + "pillar_title": "The Complete Guide to ...", + "pillar_url": "/guide/...", + "cluster_name": "Cluster Name", + "cluster_index": 0, + "post_index": 0, + "primary_keyword": "target keyword", + "secondary_keywords": ["variant 1", "variant 2"], + "template": "how-to", + "word_count_target": 1500, + "outgoing_links": [ + { "url": "/pillar-url", "anchor": "main topic guide", "type": "mandatory" }, + { "url": "/sibling-post", "anchor": "related subtopic", "type": "recommended" } + ], + "incoming_link_placeholder": "", + "differentiation_note": "This post should focus on X, while sibling post covers Y" + } +} +``` + +### Context Fields Explained + +| Field | Purpose | +|-------|---------| +| `role` | Whether this is the pillar or a spoke (affects depth and breadth) | +| `pillar_title` / `pillar_url` | So spokes can link back to the pillar | +| `cluster_name` / `cluster_index` | For organizing and labeling | +| `post_index` | Position within the cluster | +| `primary_keyword` | The main target keyword for this post | +| `secondary_keywords` | Additional keywords to naturally incorporate | +| `template` | Content template to follow (how-to, listicle, comparison, etc.) | +| `word_count_target` | Target word count (not a hard limit, a guideline) | +| `outgoing_links` | Links this post MUST include, with suggested anchor text | +| `incoming_link_placeholder` | HTML comment marker for future backward link injection | +| `differentiation_note` | How this post differs from siblings targeting similar topics | + +## Backward Link Injection + +After each new post is written, update previously written posts to link to it: + +### Process + +1. Read the link matrix from `cluster-plan.json` +2. Identify all posts that should link TO the newly written post +3. For each of those posts (that is already written): + a. Open the post file + b. Search for the placeholder comment: `` + c. Replace the placeholder with an actual contextual link + d. If no placeholder found, append a contextual link in the most relevant section +4. Log all backward links added + +### Placeholder Format + +```html + +``` + +This is inserted during content creation at a contextually appropriate location. +When the target post is later written, the placeholder is replaced with: + +```html +For a deeper dive, see our guide on anchor text. +``` + +## Resume Capability + +Execution can be interrupted and resumed. The resume algorithm: + +### Detection + +1. Read `cluster-plan.json` from the current directory +2. Scan the output directory for existing post files +3. Match found files against the plan using: + - Filename patterns (slug derived from title or keyword) + - Content inspection (check for `primary_keyword` in frontmatter or first H1) +4. Mark matched posts as `"status": "written"` in the plan + +### Resume Logic + +1. Load the plan with updated statuses +2. Filter to `"status": "planned"` posts only +3. Apply the priority algorithm to the remaining posts +4. Continue execution from the next unwritten post +5. Run backward link injection for any links between newly written and + previously written posts + +### Edge Cases + +- If the pillar is missing but spokes exist, write the pillar first and then + inject backward links into existing spokes +- If a spoke file exists but is incomplete (under 50% of target word count), + treat it as unwritten and recreate +- If `cluster-plan.json` has been modified since last execution, re-validate + the plan before resuming + +## Scorecard Metrics + +After execution completes (or on demand), generate `cluster-scorecard.md`: + +### Metric Definitions + +| Metric | Formula | Target | +|--------|---------|--------| +| Coverage | `written_posts / planned_posts * 100` | 100% | +| Link Density | `total_internal_links / total_posts` | >= 3.0 per post | +| Orphan Pages | Count of posts with 0 incoming internal links | 0 | +| Pillar Connectivity | `spokes_linking_to_pillar / total_spokes * 100` | 100% | +| Reverse Pillar Links | `spokes_linked_from_pillar / total_spokes * 100` | 100% | +| Cross-Links | `implemented_cross_links / recommended_cross_links * 100` | >= 80% | +| Cannibalization | Count of posts sharing a primary keyword | 0 | +| Image Count | Posts with at least one image / total posts | >= 90% | +| Content Gaps | Planned posts not yet written | 0 | +| Avg Word Count | Mean word count across all written posts | Within 10% of targets | + +### Scorecard Output Format + +```markdown +# Cluster Scorecard: [Seed Keyword] + +## Summary +- Posts: X/Y written (Z%) +- Total words: N (estimated: M) +- Internal links: L (density: L/Y per post) + +## Metrics +| Metric | Score | Status | +|--------|-------|--------| +| Coverage | 100% | PASS | +| Link Density | 3.2/post | PASS | +| ... + +## Issues Found +- [List any FAIL or WARN metrics with remediation steps] + +## Next Steps +- [Actionable items to reach 100% on all metrics] +``` + +## Quality Gates + +Before marking execution as complete, verify: + +1. Every spoke links to the pillar (mandatory) +2. The pillar links to every spoke (mandatory) +3. No post has fewer than 3 incoming internal links +4. No two posts share the same primary keyword +5. No orphan pages exist +6. All posts meet minimum word count (80% of target) + +If any gate fails, flag it in the scorecard and provide specific remediation +instructions. Do NOT silently pass a failing cluster. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/hub-spoke-architecture.md b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/hub-spoke-architecture.md new file mode 100644 index 00000000..56986ac7 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/hub-spoke-architecture.md @@ -0,0 +1,181 @@ +# Hub-and-Spoke Content Architecture + +## Structure Overview + +A hub-and-spoke cluster consists of one pillar page (the hub) connected to multiple +spoke clusters, each containing 2-4 individual posts. The pillar provides broad +coverage; spokes provide deep dives into subtopics. + +``` + [Spoke 1a] --- [Spoke 1b] + \ / + [Cluster 1] + | +[Spoke 2a] -- [Cluster 2] -- [PILLAR] -- [Cluster 3] -- [Spoke 3a] +[Spoke 2b] / \ [Spoke 3b] + | + [Cluster 4] + / \ + [Spoke 4a] --- [Spoke 4b] +``` + +## Pillar Page Specifications + +| Attribute | Requirement | +|-----------|-------------| +| Word count | 2,500-4,000 words | +| Keyword | Broadest, highest-volume keyword in the set | +| Content type | Comprehensive overview covering all cluster subtopics | +| Template | `ultimate-guide` (default) | +| Internal links | Link to EVERY spoke post in every cluster (mandatory) | +| Structure | Table of contents, section per cluster, summary per subtopic | +| Schema | Article + BreadcrumbList + ItemList (listing all cluster pages) | +| Update frequency | Refresh quarterly or when new spokes are added | + +## Spoke Page Specifications + +| Attribute | Requirement | +|-----------|-------------| +| Word count | 1,200-1,800 words | +| Keyword | Specific subtopic keyword (unique per post) | +| Content type | Deep-dive into a single subtopic | +| Template | Selected by intent (see template mapping below) | +| Internal links | Link to pillar (mandatory) + 2-3 sibling spokes | +| Schema | Article + BreadcrumbList | +| Depth | More detailed than the pillar's coverage of the same subtopic | + +## Cluster Constraints + +| Constraint | Value | +|-----------|-------| +| Clusters per pillar | 2-5 | +| Posts per cluster | 2-4 | +| Total posts (including pillar) | 5-21 | +| Max total estimated words | ~50,000 (pillar + 20 spokes at max) | + +## Template Auto-Selection by Intent + +| Intent Pattern | Template | Description | +|---------------|----------|-------------| +| Informational (broad) | `ultimate-guide` | Comprehensive topic overview | +| Informational (how) | `how-to` | Step-by-step instructions | +| Informational (list) | `listicle` | Numbered list of items/tips | +| Informational (concept) | `explainer` | Deep explanation of a concept | +| Commercial (compare) | `comparison` | Side-by-side product/service comparison | +| Commercial (evaluate) | `review` | In-depth review of a single product/service | +| Commercial (rank) | `best-of` | Ranked list of top options | +| Transactional | `landing-page` | Conversion-focused page | + +**Selection logic:** +1. Match the keyword's classified intent to the table above +2. If multiple templates match, prefer the one whose SERP results show the most + similar content format (e.g., if top results are all listicles, use `listicle`) +3. Avoid duplicate templates within the same cluster unless justified by intent + +## Internal Link Rules + +### Mandatory Links +- Every spoke MUST link to the pillar (at least once in body content) +- The pillar MUST link to every spoke (in its relevant section) +- These are non-negotiable -- a cluster without these links is structurally broken + +### Recommended Links +- Spoke-to-spoke within the same cluster: 2-3 links per post +- Use contextual anchor text (target keyword or close variant) +- Place links within body paragraphs, not just in "related posts" sections + +### Optional Links +- Cross-cluster spoke-to-spoke: 0-1 links per post +- Only when there is a genuine topical bridge between clusters +- Avoid forcing cross-links that do not add reader value + +### Minimum Link Requirements +- Every post must have at least 3 incoming internal links +- No orphan pages (every page reachable from pillar within 2 clicks) +- Anchor text diversity: no single anchor text used for more than 40% of links to a page + +## Cannibalization Prevention + +1. **No two posts share the same primary keyword.** Period. +2. If SERP overlap between two keywords is 7+, merge into a single post +3. After clustering, verify uniqueness: list all primary keywords and check for + near-duplicates (e.g., "best CRM" and "top CRM software") +4. If near-duplicates found, either merge the posts or differentiate by intent + (e.g., one as "best-of" list, another as "comparison") + +## JSON-LD Schema Templates + +### Pillar Page +```json +[ + { "@type": "Article", "headline": "...", "author": {...}, "datePublished": "..." }, + { "@type": "BreadcrumbList", "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "..." }, + { "@type": "ListItem", "position": 2, "name": "Pillar Title", "item": "..." } + ]}, + { "@type": "ItemList", "name": "Topic Cluster", "itemListElement": [ + { "@type": "ListItem", "position": 1, "url": "spoke-1-url" } + ]} +] +``` + +### Spoke Page +```json +[ + { "@type": "Article", "headline": "...", "author": {...}, "isPartOf": { "@id": "pillar-url" } }, + { "@type": "BreadcrumbList", "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "..." }, + { "@type": "ListItem", "position": 2, "name": "Pillar Title", "item": "pillar-url" }, + { "@type": "ListItem", "position": 3, "name": "Spoke Title", "item": "..." } + ]} +] +``` + +## cluster-plan.json Schema + +```json +{ + "version": "1.9.0", + "seed_keyword": "string", + "created_at": "ISO-8601", + "pillar": { + "title": "string", + "keyword": "string", + "volume": 0, + "template": "ultimate-guide", + "wordCount": 4000, + "url": "string", + "status": "planned|written" + }, + "clusters": [ + { + "name": "Cluster Name", + "posts": [ + { + "title": "string", + "keyword": "string", + "volume": 0, + "template": "string", + "wordCount": 1500, + "url": "string", + "status": "planned|written" + } + ] + } + ], + "links": [ + { "from": "pillar", "to": "cluster-0-post-0", "type": "mandatory", "anchor": "keyword" } + ], + "serp_matrix": { + "keywords": ["string"], + "scores": [[0]] + }, + "scorecard": { + "coverage": 0.0, + "linkDensity": 0.0, + "orphanPages": 0, + "cannibalization": 0, + "contentGaps": 0 + } +} +``` diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/serp-overlap-methodology.md b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/serp-overlap-methodology.md new file mode 100644 index 00000000..1c023225 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/references/serp-overlap-methodology.md @@ -0,0 +1,108 @@ +# SERP Overlap Methodology + +## Core Principle + +Two keywords that return the same Google results should be targeted by the same page. +Two keywords that return completely different results need separate pages. This is the +foundation of SERP-based clustering -- using Google's own ranking decisions to determine +content architecture rather than relying on keyword text similarity or stemming. + +## Scoring Algorithm + +### Step 1: Collect SERP Data + +For each keyword in the candidate set, retrieve the top 10 organic results: +- Use WebSearch or DataForSEO `serp_organic_live_advanced` +- Extract only organic result URLs (ignore ads, featured snippets, PAA, knowledge panels) +- Normalize URLs: strip protocol, trailing slash, and query parameters (except meaningful ones) +- Store as a set of 10 URLs per keyword + +### Step 2: Pairwise Comparison + +For each pair of keywords (A, B): +1. Retrieve the URL sets: `urls_A` and `urls_B` +2. Compute overlap: `shared = urls_A intersection urls_B` +3. Score: `overlap_score = len(shared)` + +### Step 3: Apply Thresholds + +| Overlap Score | Relationship | Action | +|--------------|-------------|--------| +| 7-10 | **Same post** | Merge keywords into one target page. Use higher-volume keyword as primary. | +| 4-6 | **Same cluster** | Place in same spoke cluster. May be separate posts or same post depending on volume difference. | +| 2-3 | **Interlink** | Place in adjacent clusters. Create cross-cluster internal links. | +| 0-1 | **Separate** | Different clusters entirely or exclude from current pillar topic. | + +### Step 4: Handle Ambiguous Scores (3-4 Range) + +Scores in the 3-4 range require tiebreaking: +1. Check domain overlap (same domains but different pages = closer relationship) +2. Check intent alignment (same intent category = lean toward same cluster) +3. Check volume ratio (if one keyword has 10x+ more volume, it likely deserves its own post) +4. When in doubt, keep in same cluster with separate posts (err toward cohesion) + +## Optimization Strategy + +Full pairwise comparison of N keywords requires N*(N-1)/2 SERP fetches. For 40 +keywords, that is 780 comparisons. Optimize by reducing unnecessary checks: + +### Pre-Grouping + +1. Classify all keywords by intent (Informational, Commercial, Transactional) +2. Group keywords that share the same head term (e.g., "CRM software" variants) +3. Only run pairwise SERP comparison within pre-groups +4. Cross-check boundary keywords (highest volume in each group) across groups + +### Skip Rules + +- If keywords A and B are both long-tail variants of the same head term AND share + the same intent, assume overlap 4-6 (same cluster) without checking SERP +- If keywords are in different intent categories, assume overlap 0-2 unless they + share a head term +- Verify assumptions with spot-check SERP comparisons (sample 20% of skipped pairs) + +## Scoring Matrix Format + +Store the overlap data as a symmetric matrix in `cluster-plan.json`: + +```json +{ + "serp_matrix": { + "keywords": ["keyword-a", "keyword-b", "keyword-c"], + "scores": [ + [10, 5, 1], + [5, 10, 3], + [1, 3, 10] + ] + } +} +``` + +Diagonal is always 10 (a keyword overlaps perfectly with itself). + +## Anti-Patterns + +1. **Never cluster by text similarity alone.** "Dog training tips" and "dog training + classes" may have completely different SERPs despite similar text. +2. **Never use stemming-only grouping.** "Run" and "running" may target different + intents entirely. +3. **Never assume related searches belong in the same cluster.** Verify with SERP data. +4. **Never ignore SERP feature differences.** If keyword A triggers a local pack and + keyword B triggers a featured snippet, they likely need different content types + even with moderate URL overlap. +5. **Never treat all domains equally.** Wikipedia and Reddit appear in many SERPs. + Consider filtering out ubiquitous domains (top 5 most common) before scoring, or + weighting domain-specific results higher. + +## Data Source Priority + +1. **DataForSEO** (if available): Most reliable, consistent SERP data. Use + `serp_organic_live_advanced` with `location_code: 2840` (US) and `language_code: "en"`. +2. **WebSearch** (fallback): Adequate for clustering but results may vary by session. + Run multiple searches for the same keyword and use the most common result set. + +## Caching + +Within a single clustering session, cache all SERP results. If keyword A's results +are fetched for the A-B comparison, reuse them for the A-C comparison. This halves +the number of actual SERP fetches needed. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-cluster/templates/cluster-map.html b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/templates/cluster-map.html new file mode 100644 index 00000000..b9dd964a --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-cluster/templates/cluster-map.html @@ -0,0 +1,599 @@ + + + + + + Content Cluster Map + + + +
+

Content Cluster Map

+

SERP-based semantic topic clustering

+
+ +
+
+
0
+
Total Posts
+
+
+
0
+
Clusters
+
+
+ +
Internal Links
+
+
+
0
+
Est. Words
+
+
+ +
+ + Content Cluster Map + Interactive visualization of a hub-and-spoke content architecture. The central pillar node connects to surrounding cluster groups, each containing spoke pages. + +
+ +
+
Mandatory link
+
Recommended link
+
Optional link
+
Written
+
Planned
+
+ +
Generated by Claude SEO v1.9.0
+ +
+ + + + diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-competitor-pages/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-competitor-pages/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-competitor-pages/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-competitor-pages/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-competitor-pages/SKILL.md new file mode 100644 index 00000000..270a50d7 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-competitor-pages/SKILL.md @@ -0,0 +1,220 @@ +--- +name: seo-competitor-pages +description: > + Generate SEO-optimized competitor comparison and alternatives pages. Covers + "X vs Y" layouts, "alternatives to X" pages, feature matrices, schema markup, + and conversion optimization. Use when user says "comparison page", "vs page", + "alternatives page", "competitor comparison", "X vs Y", "versus", + "compare competitors", or "alternative to". +user-invocable: true +argument-hint: "[url or generate] [competitor]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Competitor Comparison & Alternatives Pages + +Create high-converting comparison and alternatives pages that target +competitive intent keywords with accurate, structured content. + +## Page Types + +### 1. "X vs Y" Comparison Pages +- Direct head-to-head comparison between two products/services +- Balanced feature-by-feature analysis +- Clear verdict or recommendation with justification +- Target keyword: `[Product A] vs [Product B]` + +### 2. "Alternatives to X" Pages +- List of alternatives to a specific product/service +- Each alternative with brief summary, pros/cons, best-for use case +- Target keyword: `[Product] alternatives`, `best alternatives to [Product]` + +### 3. "Best [Category] Tools" Roundup Pages +- Curated list of top tools/services in a category +- Ranking criteria clearly stated +- Target keyword: `best [category] tools [year]`, `top [category] software` + +### 4. Comparison Table Pages +- Feature matrix with multiple products in columns +- Sortable/filterable if interactive +- Target keyword: `[category] comparison`, `[category] comparison chart` + +## Comparison Table Generation + +### Feature Matrix Layout +``` +| Feature | Your Product | Competitor A | Competitor B | +|------------------|:------------:|:------------:|:------------:| +| Feature 1 | ✅ | ✅ | ❌ | +| Feature 2 | ✅ | ⚠️ Partial | ✅ | +| Feature 3 | ✅ | ❌ | ❌ | +| Pricing (from) | $X/mo | $Y/mo | $Z/mo | +| Free Tier | ✅ | ❌ | ✅ | +``` + +### Data Accuracy Requirements +- All feature claims must be verifiable from public sources +- Pricing must be current (include "as of [date]" note) +- Update frequency: review quarterly or when competitors ship major changes +- Link to source for each competitor data point where possible + +## Schema Markup Recommendations + +### Product Schema with AggregateRating +```json +{ + "@context": "https://schema.org", + "@type": "Product", + "name": "[Product Name]", + "description": "[Product Description]", + "brand": { + "@type": "Brand", + "name": "[Brand Name]" + }, + "aggregateRating": { + "@type": "AggregateRating", + "ratingValue": "[Rating]", + "reviewCount": "[Count]", + "bestRating": "5", + "worstRating": "1" + } +} +``` + +### SoftwareApplication (for software comparisons) +```json +{ + "@context": "https://schema.org", + "@type": "SoftwareApplication", + "name": "[Software Name]", + "applicationCategory": "[Category]", + "operatingSystem": "[OS]", + "offers": { + "@type": "Offer", + "price": "[Price]", + "priceCurrency": "USD" + } +} +``` + +### ItemList (for roundup pages) +```json +{ + "@context": "https://schema.org", + "@type": "ItemList", + "name": "Best [Category] Tools [Year]", + "itemListOrder": "https://schema.org/ItemListOrderDescending", + "numberOfItems": "[Count]", + "itemListElement": [ + { + "@type": "ListItem", + "position": 1, + "name": "[Product Name]", + "url": "[Product URL]" + } + ] +} +``` + +## Keyword Targeting + +### Comparison Intent Patterns +| Pattern | Example | Search Volume Signal | +|---------|---------|---------------------| +| `[A] vs [B]` | "Slack vs Teams" | High | +| `[A] alternative` | "Figma alternatives" | High | +| `[A] alternatives [year]` | "Notion alternatives 2026" | High | +| `best [category] tools` | "best project management tools" | High | +| `[A] vs [B] for [use case]` | "AWS vs Azure for startups" | Medium | +| `[A] review [year]` | "Monday.com review 2026" | Medium | +| `[A] vs [B] pricing` | "HubSpot vs Salesforce pricing" | Medium | +| `is [A] better than [B]` | "is Notion better than Confluence" | Medium | + +### Title Tag Formulas +- X vs Y: `[A] vs [B]: [Key Differentiator] ([Year])` +- Alternatives: `[N] Best [A] Alternatives in [Year] (Free & Paid)` +- Roundup: `[N] Best [Category] Tools in [Year], Compared & Ranked` + +### H1 Patterns +- Match title tag intent +- Include primary keyword naturally +- Keep under 70 characters + +## Conversion-Optimized Layouts + +### CTA Placement +- **Above fold**: Brief comparison summary with primary CTA +- **After comparison table**: "Try [Your Product] free" CTA +- **Bottom of page**: Final recommendation with CTA +- Avoid aggressive CTAs in competitor description sections (reduces trust) + +### Social Proof Sections +- Customer testimonials relevant to comparison criteria +- G2/Capterra/TrustPilot ratings (with source links) +- Case studies showing migration from competitor +- "Switched from [Competitor]" stories + +### Pricing Highlights +- Clear pricing comparison table +- Highlight value advantages (not just lowest price) +- Include hidden costs (setup fees, per-user pricing, overage charges) +- Link to full pricing page + +### Trust Signals +- "Last updated [date]" timestamp +- Author with relevant expertise +- Methodology disclosure (how comparisons were conducted) +- Disclosure of own product affiliation + +## Fairness Guidelines + +- **Accuracy**: All competitor information must be verifiable from public sources +- **No defamation**: Never make false or misleading claims about competitors +- **Cite sources**: Link to competitor websites, review sites, or documentation +- **Timely updates**: Review and update when competitors release major changes +- **Disclose affiliation**: Clearly state which product is yours +- **Balanced presentation**: Acknowledge competitor strengths honestly +- **Pricing accuracy**: Include "as of [date]" disclaimers on all pricing data +- **Feature verification**: Test competitor features where possible, cite documentation otherwise + +## Internal Linking + +- Link to your own product/service pages from comparison sections +- Cross-link between related comparison pages (e.g., "A vs B" links to "A vs C") +- Link to feature-specific pages when discussing individual features +- Breadcrumb: Home > Comparisons > [This Page] +- Related comparisons section at bottom of page +- Link to case studies and testimonials mentioned in the comparison + +## Output + +### Comparison Page Template +- `COMPARISON-PAGE.md`: Ready-to-implement page structure with sections +- Feature matrix table +- Content outline with word count targets (minimum 1,500 words) + +### Schema Markup +- `comparison-schema.json`: Product/SoftwareApplication/ItemList JSON-LD + +### Keyword Strategy +- Primary and secondary keywords +- Related long-tail opportunities +- Content gaps vs existing competitor pages + +### Recommendations +- Content improvements for existing comparison pages +- New comparison page opportunities +- Schema markup additions +- Conversion optimization suggestions + +## Error Handling + +| Scenario | Action | +|----------|--------| +| Competitor URL unreachable | Report which competitor URLs failed. Proceed with available data and note gaps in the comparison. | +| Insufficient competitor data (pricing, features unavailable) | Flag missing data points clearly. Use "Not publicly available" in comparison tables rather than guessing. | +| No product/service overlap found | Report that the products serve different markets. Suggest alternative competitors that share feature overlap, or pivot to a category roundup format. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/LICENSE.txt new file mode 100644 index 00000000..caa05229 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 puneetindersingh +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/SKILL.md new file mode 100644 index 00000000..248f497f --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/SKILL.md @@ -0,0 +1,247 @@ +--- +name: seo-content-brief +description: > + Generate competitive SEO content briefs with per-section word counts, + competitor scoring, keyword density guidance, and page-type templates. + Supports both new page briefs and improve-existing-page briefs. + Use when user says "content brief", "write a brief", "content outline", + "blog brief", "service page brief", "brief for", "writing brief", + "content plan", or "outline for". +user-invocable: true +argument-hint: "[url-or-keyword] [page-type]" +license: MIT +metadata: + author: puneetindersingh + original_author: puneetindersingh + version: "1.0.0" + category: seo +--- + +# SEO Content Brief Generator + +Generate research-backed content briefs that help writers produce pages capable of outranking current top results. Briefs include competitor analysis with gap scoring, per-section word count breakdowns, keyword placement rules, and page-type-specific templates. + +## Process + +### 1. Determine Brief Mode + +**Improve mode** (existing page URL provided): +- Fetch the existing page content and structure +- Identify what is already strong (keep it) +- Identify missing, thin, or outdated sections +- Distinguish "keep/strengthen" vs "add new" sections in the outline +- Do not recommend a full rewrite when targeted improvements will win + +**New page mode** (keyword or topic provided, no existing page): +- Use the target site's homepage or sitemap for business context only +- Build the brief from scratch for a new page +- Focus on competitive gaps the new page can fill + +### 2. Fetch Context + +- Fetch the target URL or homepage to understand the business +- Fetch the sitemap to discover all existing pages, categories, and services +- This context is critical for the Website Relevance Rule (see below) + +### 3. Analyse SERPs + +- Identify the top 5 ranking pages for the target keyword +- Filter out non-competitors (Wikipedia, Reddit, Pinterest, Amazon, YouTube, government sites, SEO tool pages, job boards, directories, news aggregators, social platforms). See `references/excluded-domains.md` for the full list. +- Score each real competitor: Depth (1-10), Formatting (1-10), SEO (1-10), UX (1-10) +- Identify three gap types: + - **Topic gaps:** subtopics competitors miss entirely + - **Depth gaps:** topics covered but shallow + - **Quality gaps:** outdated info, no expert perspective, poor formatting +- Calculate gap priority: `Impact x Competitive Advantage / Effort` + +### 4. Classify Search Intent + +- **Informational:** user wants to learn (guides, how-tos, definitions) +- **Commercial:** user is researching before buying (comparisons, reviews, "best X") +- **Transactional:** user is ready to act (buy, book, enquire, sign up) +- **Navigational:** user is looking for a specific site or page + +Identify what SERP format Google rewards for this query: long-form guide, listicle, comparison table, landing page, FAQ, video, local pack. + +### 5. Build the Brief + +Apply the page-type template from `references/page-type-templates.md`, then customise based on competitor gaps and search intent. + +## Critical Rules + +### Website Relevance Rule + +Every heading, subtopic, keyword, and FAQ you suggest MUST be something the target website can credibly write about based on its actual services or products. + +- Read the site's homepage and sitemap to understand what it does +- Do not borrow competitor structure if those sections cover things this site does not offer +- Before each suggestion, ask: "Can this website actually deliver on this content?" If no, remove it. + +### Site Structure Coverage Rule + +When briefing a hub, overview, category, or "types of" page: +- The outline MUST reference every relevant product category, service, or sub-page that exists on the site +- Do not invent categories that don't exist, do not leave out categories that do exist +- Each category should appear as its own section with an internal link suggestion +- This ensures the page acts as a proper hub linking to all child pages + +For non-hub pages (single service page, blog post), use site structure to suggest relevant internal links but do not force every category into the outline. + +### Output Language Rules + +- Never mention researcher names, framework names, or tool names in the output (no "Ben Goodey method", "Frase.io formula", "Princeton GEO", "Clearscope", "Backlinko") +- These are internal thinking tools only. The output must read as plain, professional advice. +- Write for a business owner or content writer, not an SEO academic + +## Keyword Density and Placement + +Read `references/keyword-density.md` for the full rules. Summary: + +**Primary keyword density:** 0.5% to 2.0% of total word count. +- Above 2% requires review. Above 3% risks keyword stuffing penalties. +- First 1-2 mentions carry the most SEO weight. Diminishing returns after. +- For a 1,000-word article at 1-2%: roughly 10-20 total appearances including headings, body, and alt text. + +**Primary keyword MUST appear in:** +1. Title tag (near the front) +2. H1 tag (near the front) +3. URL slug +4. Meta description +5. First paragraph / first 100 words +6. At least one image alt text + +**Primary keyword does NOT need to appear in:** +- Every H2 or H3 (subtopics carry context naturally if H1 covers it) +- Every paragraph or section + +**Secondary keywords:** +- 5-8 closely related supporting terms distributed through body content +- 10-15 broader semantic terms covering related concepts +- Use in H2-H6 subheadings where natural +- Synonyms improve readability and do NOT count toward keyword density + +**Per-section keyword guidance:** For each section in the outline, specify: +- Which keyword (primary or secondary) belongs in the heading +- Whether the body should include the primary keyword or a variation +- Example: "Use secondary keyword 'structural drafting services' in H2. Body: mention primary keyword once." + +**Distribution:** Spread the primary keyword evenly. Do not front-load or cluster in one section. + +## Meta Tag Rules + +**Title tag:** +- 50-60 characters (never under 50, never over 60) +- Primary keyword first, brand name last +- Separate brand with a pipe or dash (match the site's existing pattern) +- Lead with outcomes, numbers, or specifics when possible + +**Meta description:** +- 130-150 characters (never under 130, never over 150) +- Active voice, expand on the title with USPs and specifics +- End with a call to action +- No brand name at the end (it's already in the title) +- No quotes (Google truncates at quotes) + +## Information Gain (non-negotiable) + +Every brief must specify EXACTLY what new value this content adds that no current ranking page provides. Must be specific: +- Proprietary data or original research +- Case studies with real outcomes +- Expert quotes or first-hand experience +- Original synthesis or unique framework +- NOT "more detail" or "better formatting" + +## E-E-A-T Requirements + +List the exact trust signals this content needs: +- Author credentials and bio relevant to the topic +- Expert quotes or citations from authoritative sources +- Cited studies, data, or statistics with dates +- Last updated date +- Especially critical for YMYL topics (health, finance, legal, safety) + +## Internal Linking + +- Suggest 3-5 specific internal link opportunities with anchor text +- Specify whether the page is a hub (links out to cluster pages) or spoke (links to pillar page) +- Use the site structure from the sitemap to find real link targets + +## Output Format + +Always output in this exact structure: + +``` +## Content Brief: [Primary Keyword] + +### Search Intent +[Intent type, SERP format rewarded, target audience and knowledge level. 3-4 lines.] + +### Competitor Analysis +| # | URL | Key H2 Sections | Est. Words | Score | Main Gap | +|---|-----|-----------------|------------|-------|----------| +| 1 | ... | ... | ... | X/40 | ... | + +### Content Gaps and Opportunities +[Bullet list: topic gaps, depth gaps, quality gaps with specifics] + +### Winning Outline + +**H1:** [H1 with primary keyword] +**URL Slug:** /[slug] +**Target Word Count:** ~[X] words (competitor avg: ~[X] words) + +[Full H2/H3 outline with: +- Word count per section +- Content format notes (bullet list, table, definition box, etc.) +- Featured Snippet targets marked with "FS target" +- Per-section keyword guidance] + +### Recommended Meta Tags + +**Title** +[title, 60 chars max] + +**Meta Description** +[description, 150 chars max] + +### Unique Angle and Information Gain +[Specific paragraph: what exact new value this piece adds] + +### E-E-A-T Requirements +[Bullet list of exact trust signals needed] + +### Internal Linking Opportunities +[3-5 suggestions with anchor text and target URL] +``` + +## Outline-Only Mode + +When the user asks for "just an outline" or "content outline" instead of a full brief, skip the Competitor Analysis table, Content Gaps section, Information Gain section, and E-E-A-T section. Output only: + +``` +## Content Outline: [Primary Keyword] + +**H1:** [H1 with primary keyword] +**URL Slug:** /[slug] +**Target Word Count:** ~[X] words (competitor avg: ~[X] words) + +[Full H2/H3 outline with word counts, format notes, FS targets, keyword guidance, and a 1-2 sentence writing note per section] +``` + +## DataForSEO Integration (Optional) + +If DataForSEO credentials or optional tools are available, use direct DataForSEO calls for real SERP data and competitor analysis, keyword volume, difficulty scores, intent classification, and competitor content extraction. + +## Ahrefs Integration (Optional) + +If Ahrefs MCP tools are available, use `keywords-explorer-overview` for keyword volume and difficulty, `serp-overview` for SERP analysis, `site-explorer-organic-keywords` for existing keyword rankings, and `site-explorer-top-pages` for competitor page performance. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| Target URL unreachable | Report the error. Do not guess page content. Ask the user to verify the URL. | +| No competitors found after filtering | Broaden the search to include partial-match competitors. Note the thin competitive landscape in the brief. | +| Sitemap not found | Proceed without site structure context. Note that internal linking suggestions may be incomplete. | +| Page type not specified | Auto-detect from the keyword intent and SERP format. State the detected type in the brief. | +| Target word count not specified | Use competitor average as the baseline. Note this in the outline. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/excluded-domains.md b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/excluded-domains.md new file mode 100644 index 00000000..1a120ef7 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/excluded-domains.md @@ -0,0 +1,65 @@ + +# Excluded Competitor Domains + +When analysing SERPs for competitor scoring, filter out these domains. They are not real business competitors even when they rank for the target keyword. + +## Encyclopedias and Reference Sites +- wikipedia.org, britannica.com, investopedia.com, dictionary.com, merriam-webster.com, webmd.com, healthline.com, mayoclinic.org + +## Social Media Platforms +- facebook.com, instagram.com, twitter.com, x.com, linkedin.com, pinterest.com, tiktok.com, youtube.com, reddit.com, quora.com, threads.net + +## Content Platforms and Blogging +- medium.com, substack.com, blogger.com, wordpress.com, wix.com, squarespace.com, hubpages.com, tumblr.com + +## Search Engines +- google.com, bing.com, yahoo.com, duckduckgo.com, baidu.com + +## Marketplaces and E-Commerce Aggregators +- amazon.com, amazon.com.au, amazon.co.uk, ebay.com, ebay.com.au, etsy.com, shopify.com, alibaba.com, gumtree.com.au, kogan.com + +## Forums and Q&A +- stackoverflow.com, stackexchange.com, whirlpool.net.au, superuser.com, serverfault.com + +## News and Media +- bbc.com, bbc.co.uk, cnn.com, news.com.au, abc.net.au, theguardian.com, forbes.com, techcrunch.com, theverge.com, mashable.com, huffpost.com, nytimes.com, washingtonpost.com + +## Data and Research Platforms +- statista.com, ibisworld.com, similarweb.com + +## Directories, Reviews, and Listings +- maps.google.com, tripadvisor.com, yelp.com, trustpilot.com, yellowpages.com.au, bark.com, thumbtack.com, angi.com, homeadvisor.com, truelocal.com.au, hotfrog.com.au, productreview.com.au + +## Comparison and Aggregator Sites +- finder.com.au, canstar.com.au, iselect.com.au, mozo.com.au, comparethemarket.com.au, cmsmarket.com + +## Job Boards +- seek.com.au, indeed.com, glassdoor.com, jora.com, linkedin.com/jobs + +## SEO and Marketing Tool Pages +- semrush.com, ahrefs.com, moz.com, neilpatel.com, backlinko.com, searchengineland.com, searchenginejournal.com, yoast.com, screaming frog.co.uk, majestic.com + +## AI Platforms +- chat.openai.com, chatgpt.com, claude.ai, perplexity.ai, gemini.google.com, copilot.microsoft.com + +## Government Domains +- Any domain ending in .gov, .gov.au, .gov.uk, .gov.nz, .gc.ca + +## Academic Domains +- Any domain ending in .edu, .edu.au, .ac.uk, .ac.nz + +## URL Path Patterns to Exclude + +Even on otherwise valid competitor domains, exclude URLs containing: +- `/tag/`, `/tags/`, `/author/`, `/category/`, `/archive/` +- `/feed/`, `/rss/`, `/wp-json/`, `/wp-admin/` +- `/login`, `/signup`, `/register`, `/cart`, `/checkout` +- `/terms`, `/privacy`, `/cookie-policy`, `/disclaimer` +- `/sitemap`, `/robots.txt` + +## How to Use This List + +1. After fetching SERP results, check each URL against these domains +2. Remove any matches before scoring competitors +3. If fewer than 3 real competitors remain, note the thin competitive landscape +4. Never count a filtered domain in the competitor analysis table diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/keyword-density.md b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/keyword-density.md new file mode 100644 index 00000000..5900e61f --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/keyword-density.md @@ -0,0 +1,60 @@ + +# Keyword Density and Placement Rules + +Based on published research from Semrush, Ahrefs, Yoast, and Google's own guidance on keyword usage. + +## Primary Keyword Density + +**Safe range:** 0.5% to 2.0% of total word count. + +| Density | Assessment | +|---------|-----------| +| Below 0.5% | Under-optimised. Likely missing from key locations. | +| 0.5% - 2.0% | Optimal range. Natural reading, clear topic signal. | +| 2.0% - 3.0% | Review required. May read unnaturally. | +| Above 3.0% | Keyword stuffing risk. Likely to trigger penalties. | + +**Practical example:** For a 1,000-word article at 1-2%, the primary keyword should appear roughly 10-20 times total. This includes headings, body text, and image alt text. + +**Diminishing returns:** The first 1-2 mentions of the primary keyword carry the most SEO weight. After that, each additional mention provides less ranking benefit. Prioritise placement quality over quantity. + +## Required Placement Locations + +The primary keyword MUST appear in all of these: + +1. **Title tag** (near the front, not buried at the end) +2. **H1 tag** (near the front) +3. **URL slug** (lowercase, hyphenated) +4. **Meta description** (naturally integrated) +5. **First paragraph / first 100 words** (establishes topic immediately) +6. **At least one image alt text** (reinforces topic for image search) + +## Locations Where It Is NOT Required + +- Every H2 or H3 (if the H1 covers the keyword, subheadings carry context naturally through semantic relationship) +- Every paragraph or section (clustering looks unnatural) +- Anchor text of every internal link (vary the anchor text) + +## Secondary and Semantic Keywords + +| Type | Count | Usage | +|------|-------|-------| +| Closely related terms | 5-8 | Distribute through body content and H2-H6 headings | +| Broader semantic terms | 10-15 | Cover related concepts and user intent variations | +| Synonyms | As natural | Improve readability. Do NOT count toward primary density. | + +## Distribution Rules + +- **Spread evenly** throughout the content. Do not front-load all mentions into the introduction or cluster in one section. +- **Per-section guidance in briefs:** For each section in a content brief, specify: + - Which keyword (primary or secondary) should appear in the heading + - Whether the section body should include the primary keyword or a variation + - Format: "Use secondary keyword '[term]' in H2. Body: mention primary keyword once." + +## Common Mistakes + +1. **Exact-match obsession:** Using the exact phrase every time instead of natural variations. Google understands synonyms and related terms. +2. **Heading stuffing:** Putting the primary keyword in every H2 and H3. One H1 mention plus 1-2 H2 mentions is sufficient. +3. **Ignoring first 100 words:** The opening paragraph is the highest-value placement after the title and H1. +4. **Forgetting image alt text:** A free placement opportunity that also helps image search rankings. +5. **Counting synonyms as density:** "Web design", "website design", and "site design" are different strings. Only count exact-match appearances toward density. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/page-type-templates.md b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/page-type-templates.md new file mode 100644 index 00000000..e3557026 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-content-brief/references/page-type-templates.md @@ -0,0 +1,153 @@ + +# Content Brief Templates by Page Type + +Select the template that matches the page type. Adapt sections based on the specific business and competitive landscape. Not every section applies to every page. + +## Service Page + +**Goal:** Convert visitors into enquiries or bookings. + +| Section | Purpose | Format | +|---------|---------|--------| +| What is [service] | Define the service clearly | Definition box, 80-120 words | +| Who needs it | Qualify the reader | Bullet list of scenarios | +| How it works | Reduce friction, set expectations | Numbered steps | +| Costs/pricing/fees | Address the #1 question | Table or range, not exact if variable | +| Outcomes/results | Prove value | Stats, case study snippets, before/after | +| Why choose [brand] | Differentiate | 3-5 bullet points with specifics | +| FAQ | Capture PAA traffic | 5-8 questions, 40-60 words each, FS target | +| CTA | Convert | Clear action, reduce risk (free consult, no obligation) | + +**Schema:** Service + FAQPage + LocalBusiness (if location-specific) +**Primary keyword placement:** H1, first 100 words, one H2, URL slug, meta title + +## Blog Post + +**Goal:** Rank for informational queries, drive readers to service pages. + +| Section | Purpose | Format | +|---------|---------|--------| +| Direct answer | Win Featured Snippet | Answer-first paragraph, 40-60 words, FS target | +| Background/context | Set the scene | 1-2 paragraphs | +| [3-5 H2 subtopics] | Cover depth from PAA/gaps | Mix of paragraphs, lists, tables | +| Common mistakes | Add unique value | Numbered list with explanations | +| FAQ | Capture long-tail traffic | 5 questions from gap analysis | +| CTA to relevant service | Convert intent | Contextual link, not hard sell | + +**Schema:** Article + FAQPage +**Primary keyword placement:** H1, first 100 words, URL slug, meta title, one image alt text + +## Case Study + +**Goal:** Build trust, demonstrate real outcomes. + +| Section | Purpose | Format | +|---------|---------|--------| +| Outcome summary | Lead with the result | Bold stat or outcome in first line | +| Client situation | Context | 1-2 paragraphs, anonymise if needed | +| The challenge | Problem framing | What was at stake | +| Our approach | Show expertise | Step-by-step or narrative | +| The result | Prove value | Specific figures, percentages, timelines | +| Key takeaways | Reusable insight | 3-5 bullet points | +| Related services CTA | Cross-sell | Link to the relevant service page | + +**Schema:** Article (with subject and outcome in description) +**Primary keyword:** The outcome or matter type, in H1 and title + +## Category Page + +**Goal:** Rank for broad topic terms, funnel visitors to sub-pages. + +| Section | Purpose | Format | +|---------|---------|--------| +| What this area covers | Define scope | Overview paragraph | +| Sub-services/products (linked) | Hub linking | One H2 or H3 per sub-page with description and link | +| Who we help | Qualify audience | Bullet list of personas | +| Process overview | Set expectations | Numbered steps | +| FAQ | Capture variations | 5-8 questions | +| CTA | Convert | Clear next step | + +**Schema:** Service + BreadcrumbList + FAQPage +**Primary keyword:** Category name, in H1, title, URL, first paragraph +**Site Structure Rule:** MUST include every relevant sub-page from the sitemap. + +## Landing Page + +**Goal:** Single conversion action, minimal distractions. + +| Section | Purpose | Format | +|---------|---------|--------| +| Hero (offer + CTA) | Convert above fold | Headline + subheadline + button | +| Problem statement | Agitate pain | 2-3 sentences | +| Solution/benefits | Present the fix | 3-5 benefit bullets | +| Social proof | Build trust | Testimonials, logos, stats | +| How it works | Reduce friction | 3-step process | +| Objection handling / FAQ | Remove doubts | 4-6 common objections answered | +| Final CTA | Convert | Repeat the offer | + +**Schema:** WebPage + FAQPage +**Primary keyword:** Offer or outcome, in H1, title, hero subheading + +## FAQ Page + +**Goal:** Capture PAA and Featured Snippet traffic. + +| Section | Purpose | Format | +|---------|---------|--------| +| 8-15 questions | Grouped by subtopic | Each answered in 40-60 words, FS target for each | +| CTA after last question | Convert | Contextual next step | + +**Schema:** FAQPage (every Q&A as mainEntity) — Google retired FAQ rich results for all sites on May 7, 2026, so this no longer produces a SERP rich result; the markup still aids AI Mode / AI Overviews entity resolution (treat as a supporting signal, not a ranking feature). For genuine user Q&A pages, use QAPage instead. See the seo-schema skill for the canonical position. +**Primary keyword:** In H1 as "[Topic]: Frequently Asked Questions", in first answer + +## Location Page + +**Goal:** Rank for [service] + [city] queries. + +| Section | Purpose | Format | +|---------|---------|--------| +| What we do in [city] | Local relevance | Overview with city name naturally included | +| Local areas/courts/landmarks | Hyper-local signals | List of suburbs, jurisdictions, or landmarks served | +| Service areas | Geographic scope | List or embedded map | +| Why local matters | Justify the page | 1-2 paragraphs on local expertise | +| Team in [city] | E-E-A-T | Brief bios of local staff | +| Local reviews/testimonials | Trust | 2-3 reviews mentioning the location | +| FAQ | Local variations | 5 location-specific questions | +| CTA | Convert | Local phone number, address, booking link | + +**Schema:** Service + LocalBusiness (with address, phone, geo coordinates) +**Primary keyword:** [Service] [City], in H1, title, URL, first paragraph, LocalBusiness schema + +## About Page + +**Goal:** Build trust, support E-E-A-T across the site. + +| Section | Purpose | Format | +|---------|---------|--------| +| Who we are | Brand positioning | 2-3 paragraphs | +| Our story/founding | Humanise | Narrative with founding date | +| Our team | E-E-A-T | Individual bios with credentials, photos | +| Our values | Differentiate | 3-5 values with brief explanations | +| Awards/recognition | Authority | List with dates | +| Media mentions | Authority | Links to press coverage | +| CTA | Convert | Contact or services link | + +**Schema:** Organization + Person (per team member) +**Primary keyword:** Brand name or "[Brand] [industry]", in H1 and title + +## Homepage + +**Goal:** Establish brand authority, funnel to service and location pages. + +| Section | Purpose | Format | +|---------|---------|--------| +| Hero (value prop + CTA) | First impression | Headline + subheadline + primary button | +| Services overview | Show scope | Card grid or linked list to service pages | +| Why us (differentiators) | Stand out | 3-5 unique selling points | +| Social proof | Trust | Testimonials, client logos, review stars | +| Location/service area | Local relevance | Map or area list | +| FAQ (for GEO) | AI search visibility | 4-6 broad business questions | +| CTA | Convert | Repeat primary action | + +**Schema:** Organization + WebSite + Service +**Primary keyword:** Primary service + city, in H1, title, first paragraph diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-content/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-content/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-content/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-content/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-content/SKILL.md new file mode 100644 index 00000000..34cef184 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-content/SKILL.md @@ -0,0 +1,198 @@ +--- +name: seo-content +description: > + Content quality and E-E-A-T analysis with AI citation readiness assessment. + Use when user says "content quality", "E-E-A-T", "content analysis", + "readability check", "thin content", or "content audit". +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Content Quality & E-E-A-T Analysis + +## Google's "Who / How / Why" Test (canonical heuristic) + +Before scoring E-E-A-T sub-factors, every page audit should pass Google's +own three-question heuristic from the helpful-content guide: + +| Question | What to look for | +|---|---| +| **Who** created it? | Visible byline, author bio page, professional credentials. Required where readers expect it; non-negotiable for YMYL. | +| **How** was it created? | Process disclosure where readers would reasonably ask — especially for AI-assisted content. Original research / first-hand evidence / lived experience. | +| **Why** does it exist? | "To help people" rather than "to attract search clicks." Watch for niche entry without expertise, content churn for freshness signals, content written to a word-count target. | + +Primary source: +https://developers.google.com/search/docs/fundamentals/creating-helpful-content + +When all three answers are weak, the page is at risk under the core ranking +system's helpfulness signals (formerly the standalone Helpful Content System, +merged into core during the March 2024 update). + +## E-E-A-T Framework (updated Sept 2025 QRG) + +Read `skills/seo/references/eeat-framework.md` for full criteria. + +### Experience (first-hand signals) +- Original research, case studies, before/after results +- Personal anecdotes, process documentation +- Unique data, proprietary insights +- Photos/videos from direct experience + +### Expertise +- Author credentials, certifications, bio +- Professional background relevant to topic +- Technical depth appropriate for audience +- Accurate, well-sourced claims + +### Authoritativeness +- External citations, backlinks from authoritative sources +- Brand mentions, industry recognition +- Published in recognized outlets +- Cited by other experts + +### Trustworthiness +- Contact information, physical address +- Privacy policy, terms of service +- Customer testimonials, reviews +- Date stamps, transparent corrections +- Secure site (HTTPS) + +## Content Metrics + +### Word Count Analysis +Compare against page type minimums: +| Page Type | Minimum | +|-----------|---------| +| Homepage | 500 | +| Service page | 800 | +| Blog post | 1,500 | +| Product page | 300+ (400+ for complex products) | +| Location page | 500-600 | + +> **Important:** These are **topical coverage floors**, not targets. Google has confirmed word count is NOT a direct ranking factor. The goal is comprehensive topical coverage; a 500-word page that thoroughly answers the query will outrank a 2,000-word page that doesn't. Use these as guidelines for adequate coverage depth, not rigid requirements. + +### Readability +- Flesch Reading Ease: target 60-70 for general audience + +> **Note:** Flesch Reading Ease is a useful proxy for content accessibility but is NOT a direct Google ranking factor. John Mueller has confirmed Google does not use basic readability scores for ranking. Yoast deprioritized Flesch scores in v19.3. Use readability analysis as a content quality indicator, not as an SEO metric to optimize directly. +- Grade level: match target audience +- Sentence length: average 15-20 words +- Paragraph length: 2-4 sentences + +### Keyword Optimization +- Primary keyword in title, H1, first 100 words +- Natural density (1-3%) +- Semantic variations present +- No keyword stuffing + +### Content Structure +- Logical heading hierarchy (H1 -> H2 -> H3) +- Scannable sections with descriptive headings +- Bullet/numbered lists where appropriate +- Table of contents for long-form content + +### Multimedia +- Relevant images with proper alt text +- Videos where appropriate +- Infographics for complex data +- Charts/graphs for statistics + +### Internal Linking +- 3-5 relevant internal links per 1000 words +- Descriptive anchor text +- Links to related content +- No orphan pages + +### External Linking +- Cite authoritative sources +- Open in new tab for user experience +- Reasonable count (not excessive) + +## AI Content Assessment (Sept 2025 QRG addition) + +Google's raters now formally assess whether content appears AI-generated. + +### Acceptable AI Content +- Demonstrates genuine E-E-A-T +- Provides unique value +- Has human oversight and editing +- Contains original insights + +### Low-Quality AI Content Markers +- Generic phrasing, lack of specificity +- No original insight +- Repetitive structure across pages +- No author attribution +- Factual inaccuracies + +> **Helpful Content System (March 2024):** The Helpful Content System was merged into Google's core ranking algorithm during the March 2024 core update. It no longer operates as a standalone classifier. Helpfulness signals are now weighted within every core update. The same principles apply (people-first content, demonstrating E-E-A-T, satisfying user intent), but enforcement is continuous rather than through separate HCU updates. + +## AI Citation Readiness (GEO signals) + +Optimize for AI search engines (ChatGPT, Perplexity, Google AI Overviews): + +- Clear, quotable statements with statistics/facts +- Structured data (especially for data points) +- Strong heading hierarchy (H1->H2->H3 flow) +- Answer-first formatting for key questions +- Tables and lists for comparative data +- Clear attribution and source citations + +### AI Search Visibility & GEO (2025-2026) + +**Google AI Mode** is Google's conversational AI search surface — powered by **Gemini 3.5 Flash** since I/O 2026 (May 2026) and now past **1 billion monthly users** globally. Unlike AI Overviews (which appear above organic results), AI Mode is a fully conversational experience with **zero organic blue links**, making AI citation the only visibility mechanism. It is a *distinct citation engine* from AI Overviews — the two share only ~14% of cited URLs — so optimize for both surfaces, not one (see the `seo-geo` skill). + +**Key optimization strategies for AI citation:** +- **Structured answers:** Clear question-answer formats, definition patterns, and step-by-step instructions that AI systems can extract and cite +- **First-party data:** Original research, statistics, case studies, and unique datasets are highly cited by AI systems +- **Schema markup:** Article, FAQPage (Google retired FAQ *rich results* in May 2026, but the markup still aids AI parsing/entity resolution) or QAPage for genuine user Q&A, and structured content schemas help AI systems parse and attribute content +- **Topical authority:** AI systems preferentially cite sources that demonstrate deep expertise. Build content clusters, not isolated pages +- **Entity clarity:** Ensure brand, authors, and key concepts are clearly defined with structured data (Organization, Person schema) +- **Multi-platform tracking:** Monitor visibility across Google AI Overviews, AI Mode, ChatGPT, Perplexity, and Bing Copilot, not just traditional rankings. Treat AI citation as a standalone KPI alongside organic rankings and traffic. + +**Generative Engine Optimization (GEO):** +Per Google's AI optimization guide, "AEO" and "GEO" are rebranded labels for SEO — AI Overviews and AI Mode are grounded in the same ranking and quality systems as classic Search. The optimization signals that matter (quotability, attribution, heading hierarchy, freshness) are SEO fundamentals applied to AI-search surfaces, not a separate discipline. Cross-reference the `seo-geo` skill for detailed workflows; both surfaces share the primary-source synthesis in `skills/seo-geo/references/google-ai-optimization-guide.md`. + +## Content Freshness + +- Publication date visible +- Last updated date if content has been revised +- Flag content older than 12 months without update for fast-changing topics + +## Output + +### Content Quality Score: XX/100 + +### E-E-A-T Breakdown +| Factor | Score | Key Signals | +|--------|-------|-------------| +| Experience | XX/25 | ... | +| Expertise | XX/25 | ... | +| Authoritativeness | XX/25 | ... | +| Trustworthiness | XX/25 | ... | + +### AI Citation Readiness: XX/100 + +### Issues Found +### Recommendations + +## DataForSEO Integration (Optional) + +If DataForSEO credentials or optional tools are available, use direct DataForSEO calls for real keyword volume data, difficulty scores, intent classification, and content quality analysis. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess page content. Suggest the user verify the URL and try again. | +| Content behind paywall (402/403, login wall) | Report that the content is not publicly accessible. Analyze only the visible portion (meta tags, headers) and note the limitation. | +| Thin content (fewer than 100 words retrievable) | Report the findings as-is rather than guessing. Flag the page as potentially JavaScript-rendered or gated, and suggest the user provide the full text directly. | + +## FLOW Framework Integration + +For prompt-guided content optimization, use `/seo flow optimize ` and `/seo flow win ` — FLOW's optimize and win prompts provide structured E-E-A-T improvement and BOFU conversion workflows. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/SKILL.md new file mode 100644 index 00000000..eadf8dae --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/SKILL.md @@ -0,0 +1,405 @@ +--- +name: seo-dataforseo +description: > + Live SEO data via DataForSEO API credentials. SERP analysis (Google, Bing, Yahoo, + YouTube, Google Images), keyword research (volume, difficulty, intent, trends), + backlink profiles, on-page analysis (Lighthouse, content parsing), competitor + analysis, content analysis, business listings, AI visibility (ChatGPT scraper, + LLM mention tracking), and domain analytics. Uses DataForSEO credentials from the selected project `.env`; MCP tools are optional adapters when already available. Use when user says "dataforseo", "live SERP", "keyword volume", + "backlink data", "competitor data", "AI visibility check", "LLM mentions", + "image SERP", "google images", "image rankings", or "real search data". +user-invocable: true +argument-hint: "[command] [query]" +license: MIT +compatibility: "Uses DATAFORSEO_USERNAME or DATAFORSEO_LOGIN plus DATAFORSEO_PASSWORD from project .env; MCP optional" +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# DataForSEO: Live SEO Data (Extension) + +Live search data via DataForSEO API credentials. Provides real-time SERP results +(organic + images), keyword metrics, backlink profiles, on-page analysis, content +analysis, business listings, AI visibility checking, and LLM mention tracking +across 10 API modules. MCP tools may be used when already configured, but are not required. + +## Prerequisites + +Set credentials in the selected project `.env`: + +```bash +DATAFORSEO_USERNAME=your-login +DATAFORSEO_PASSWORD=your-password +``` + +`DATAFORSEO_LOGIN` is also accepted as an alias for `DATAFORSEO_USERNAME`. +The extension installer and MCP server are optional for users who already +prefer MCP. + +**Check availability:** First check for `DATAFORSEO_USERNAME` or `DATAFORSEO_LOGIN` plus `DATAFORSEO_PASSWORD` in the selected project environment. Use `python scripts/dataforseo_api.py ...` or specialized scripts for direct API calls. If an optional DataForSEO adapter is already available, you may use it quietly, but do not require MCP setup or spend context inventorying MCP servers unless the user asks. + +## API Credit Awareness + +DataForSEO charges per API call. Be efficient: +- Prefer bulk endpoints over multiple single calls +- Use default parameters (US, English) unless user specifies otherwise +- Cache results mentally within a session; don't re-fetch the same data +- Warn user before running expensive operations (full backlink crawls, large keyword lists) + +## Cost Guardrails + +**Before every DataForSEO API call**, run cost estimation: +``` +python3 scripts/dataforseo_costs.py check [--count N] +``` + +- If `"status": "approved"` → proceed with the API call +- If `"status": "needs_approval"` → show the cost estimate to the user and ask for confirmation before proceeding +- If `"status": "blocked"` → inform the user that the daily budget limit would be exceeded; do NOT proceed + +**After each API call completes**, log the cost: +``` +python3 scripts/dataforseo_costs.py log +``` + +**User commands for cost management:** +- `/seo dataforseo costs today` → show today's spending breakdown +- `/seo dataforseo costs summary` → show 7-day spending history +- `/seo dataforseo costs config --mode threshold --threshold 0.50` → configure approval mode + +Load `references/cost-tiers.md` for the full pricing table, budget presets, and cost reduction tips. + +## Quick Reference + +| Command | What it does | +|---------|-------------| +| `/seo dataforseo serp ` | Google organic SERP results | +| `/seo dataforseo serp-images ` | Google Images SERP results | +| `/seo dataforseo serp-youtube ` | YouTube search results | +| `/seo dataforseo youtube ` | YouTube video deep analysis | +| `/seo dataforseo keywords ` | Keyword ideas and suggestions | +| `/seo dataforseo volume ` | Search volume for keywords | +| `/seo dataforseo difficulty ` | Keyword difficulty scores | +| `/seo dataforseo intent ` | Search intent classification | +| `/seo dataforseo trends ` | Google Trends data | +| `/seo dataforseo backlinks ` | Full backlink profile | +| `/seo dataforseo competitors ` | Competitor domain analysis | +| `/seo dataforseo ranked ` | Ranked keywords for domain | +| `/seo dataforseo intersection ` | Keyword/backlink overlap | +| `/seo dataforseo traffic ` | Bulk traffic estimation | +| `/seo dataforseo subdomains ` | Subdomains with ranking data | +| `/seo dataforseo top-searches ` | Top queries mentioning domain | +| `/seo dataforseo onpage ` | On-page analysis (Lighthouse + parsing) | +| `/seo dataforseo tech ` | Technology stack detection | +| `/seo dataforseo whois ` | WHOIS registration data | +| `/seo dataforseo content ` | Content analysis and trends | +| `/seo dataforseo listings ` | Business listings search | +| `/seo dataforseo ai-scrape ` | ChatGPT web scraper for GEO | +| `/seo dataforseo ai-mentions ` | LLM mention tracking for GEO | + +--- + +## SERP Analysis + +### `/seo dataforseo serp ` + +Fetch live Google organic search results. + +**Direct API operation:** `serp_organic_live_advanced` + +**Default parameters:** location_code=2840 (US), language_code=en, device=desktop, depth=100 + +**Also supports:** The `serp_organic_live_advanced` tool supports Google, Bing, and Yahoo via the `se` parameter. Specify "bing" or "yahoo" to switch search engines. + +**Output:** Rank, URL, title, description, domain, featured snippets, AI overview references, People Also Ask. + +### `/seo dataforseo serp-youtube ` + +Fetch YouTube search results. Valuable for GEO. YouTube mentions correlate most strongly with AI citations. + +**Direct API operation:** `serp_youtube_organic_live_advanced` + +**Output:** Video title, channel, views, upload date, description, URL. + +### `/seo dataforseo youtube ` + +Deep analysis of a specific YouTube video: info, comments, and subtitles. YouTube mentions have the strongest correlation (0.737) with AI visibility, making this critical for GEO analysis. + +**Direct API operation:** `serp_youtube_video_info_live_advanced`, `serp_youtube_video_comments_live_advanced`, `serp_youtube_video_subtitles_live_advanced` + +**Parameters:** video_id (the YouTube video ID, e.g., "dQw4w9WgXcQ") + +**Output:** Video metadata (title, channel, views, likes, description), top comments with engagement, subtitle/transcript text. + +### `/seo dataforseo serp-images ` + +Fetch live Google Images search results. See which images rank for a keyword, +which domains dominate image results, and identify visual content opportunities. + +**Direct API operation:** `serp_google_images_live_advanced` + +**Default parameters:** location_code=2840 (US), language_code=en, device=desktop, depth=100 + +**Parameters:** keyword (required), depth (optional, max 700, billed per 100-result increment), search_param (optional, e.g. "site:example.com") + +**Cost warning:** Using `site:` or `filetype:` operators incurs **5x API cost**. Warn user before running filtered queries. + +**Output:** Position, title, alt text, source page URL, direct image URL, domain, encoded URL. + +**Analysis to provide:** +- Domain dominance: which sites own the most image positions (top 10 domains by count) +- Alt text patterns: common title/alt text patterns in top-ranking images +- Format distribution: WebP vs JPEG vs PNG in top results (infer from image_url extension) +- Opportunity identification: keywords where user has organic rankings but no image presence + +--- + +## Keyword Research + +### `/seo dataforseo keywords ` + +Generate keyword ideas, suggestions, and related terms from a seed keyword. + +**Direct API operation:** `dataforseo_labs_google_keyword_ideas`, `dataforseo_labs_google_keyword_suggestions`, `dataforseo_labs_google_related_keywords` + +**Default parameters:** location_code=2840 (US), language_code=en, limit=50 + +**Output:** Keyword, search volume, CPC, competition level, keyword difficulty, trend. + +### `/seo dataforseo volume ` + +Get search volume and metrics for a list of keywords. + +**Direct API operation:** `kw_data_google_ads_search_volume` + +**Parameters:** keywords (array, comma-separated), location_code, language_code + +**Output:** Keyword, monthly search volume, CPC, competition, monthly trend data. + +### `/seo dataforseo difficulty ` + +Calculate keyword difficulty scores for ranking competitiveness. + +**Direct API operation:** `dataforseo_labs_bulk_keyword_difficulty` + +**Parameters:** keywords (array), location_code, language_code + +**Output:** Keyword, difficulty score (0-100), interpretation (Easy/Medium/Hard/Very Hard). + +### `/seo dataforseo intent ` + +Classify keywords by user search intent. + +**Direct API operation:** `dataforseo_labs_search_intent` + +**Parameters:** keywords (array), location_code, language_code + +**Output:** Keyword, intent type (informational, navigational, commercial, transactional), confidence score. + +### `/seo dataforseo trends ` + +Analyze keyword trends over time using Google Trends data. + +**Direct API operation:** `kw_data_google_trends_explore` + +**Parameters:** keywords (array), location_code, date_from, date_to, language_code + +**Output:** Keyword, time series data, trend direction, seasonality signals. + +--- + +## Domain & Competitor Analysis + +### `/seo dataforseo backlinks ` + +Comprehensive backlink profile analysis. + +**Direct API operation:** `backlinks_summary`, `backlinks_backlinks`, `backlinks_anchors`, `backlinks_referring_domains`, `backlinks_bulk_spam_score`, `backlinks_timeseries_summary` + +**Default parameters:** limit=100 per sub-call + +**Output:** Total backlinks, referring domains, domain rank, spam score, top anchors, new/lost backlinks over time, dofollow ratio, top referring domains. + +### `/seo dataforseo competitors ` + +Identify competing domains and estimate traffic. + +**Direct API operation:** `dataforseo_labs_google_competitors_domain`, `dataforseo_labs_google_domain_rank_overview`, `dataforseo_labs_bulk_traffic_estimation` + +**Output:** Competitor domains, keyword overlap %, estimated traffic, domain rank, common keywords. + +### `/seo dataforseo ranked ` + +List keywords a domain ranks for with positions and page data. + +**Direct API operation:** `dataforseo_labs_google_ranked_keywords`, `dataforseo_labs_google_relevant_pages` + +**Default parameters:** limit=100, location_code=2840 + +**Output:** Keyword, position, URL, search volume, traffic share, SERP features. + +### `/seo dataforseo intersection [...]` + +Find shared keywords and backlink sources across 2-20 domains. + +**Direct API operation:** `dataforseo_labs_google_domain_intersection`, `backlinks_domain_intersection` + +**Parameters:** domains (2-20 array) + +**Output:** Shared keywords with positions per domain, shared backlink sources, unique keywords per domain. + +### `/seo dataforseo traffic ` + +Estimate organic search traffic for one or more domains. + +**Direct API operation:** `dataforseo_labs_bulk_traffic_estimation` + +**Parameters:** domains (array) + +**Output:** Domain, estimated organic traffic, estimated traffic cost, top keywords. + +### `/seo dataforseo subdomains ` + +Enumerate subdomains with their ranking data and traffic estimates. + +**Direct API operation:** `dataforseo_labs_google_subdomains` + +**Parameters:** target (domain), location_code, language_code + +**Output:** Subdomain, ranked keywords count, estimated traffic, organic cost. + +### `/seo dataforseo top-searches ` + +Find the most popular search queries that mention a specific domain in results. + +**Direct API operation:** `dataforseo_labs_google_top_searches` + +**Parameters:** target (domain), location_code, language_code + +**Output:** Query, search volume, domain position, SERP features, traffic share. + +--- + +## Technical / On-Page + +### `/seo dataforseo onpage ` + +Run on-page analysis including Lighthouse audit and content parsing. + +**Direct API operation:** `on_page_instant_pages`, `on_page_content_parsing`, `on_page_lighthouse` + +**Usage:** +- `on_page_instant_pages`:Quick page analysis (status codes, meta tags, content size, page timing, broken links, on-page checks) +- `on_page_content_parsing`:Extract and parse page content (plain text, word count, structure) +- `on_page_lighthouse`:Full Lighthouse audit (performance score, accessibility, best practices, SEO, Core Web Vitals) + +**Output:** Pages crawled, status codes, meta tags, titles, content size, load times, Lighthouse scores, broken links, resource analysis. + +### `/seo dataforseo tech ` + +Detect technologies used on a domain. + +**Direct API operation:** `domain_analytics_technologies_domain_technologies` + +**Output:** Technology name, version, category (CMS, analytics, CDN, framework, etc.). + +### `/seo dataforseo whois ` + +Retrieve WHOIS registration data. + +**Direct API operation:** `domain_analytics_whois_overview` + +**Output:** Registrar, creation date, expiration date, nameservers, registrant info (if public). + +--- + +## Content & Business Data + +### `/seo dataforseo content ` + +Analyze content quality, search for content by topic, and track phrase trends. + +**Direct API operation:** `content_analysis_search`, `content_analysis_summary`, `content_analysis_phrase_trends` + +**Parameters:** keyword (for search/trends) or URL (for summary) + +**Output:** Content matches with quality scores, sentiment analysis, readability metrics, phrase trend data over time. + +### `/seo dataforseo listings ` + +Search business listings for local SEO competitive analysis. + +**Direct API operation:** `business_data_business_listings_search` + +**Parameters:** keyword, location (optional) + +**Output:** Business name, description, category, address, phone, domain, rating, review count, claimed status. + +--- + +## AI Visibility / GEO + +### `/seo dataforseo ai-scrape ` + +Scrape what ChatGPT web search returns for a query. Real GEO visibility check: see which sources ChatGPT cites for your target keywords. + +**Direct API operation:** `ai_optimization_chat_gpt_scraper` + +**Parameters:** query, location_code (optional), language_code (optional). Use `ai_optimization_chat_gpt_scraper_locations` to look up available locations. + +**Output:** ChatGPT response content, cited sources/URLs, referenced domains. + +### `/seo dataforseo ai-mentions ` + +Track how LLMs mention brands, domains, and topics. Critical for GEO. Measures actual AI visibility across multiple LLM platforms. + +**Direct API operation:** `ai_opt_llm_ment_search`, `ai_opt_llm_ment_top_domains`, `ai_opt_llm_ment_top_pages`, `ai_opt_llm_ment_agg_metrics` + +**Parameters:** keyword, location_code (optional), language_code (optional). Use `ai_opt_llm_ment_loc_and_lang` for available locations/languages and `ai_optimization_llm_models` for supported LLM models. + +**Workflow:** +1. Search LLM mentions with `ai_opt_llm_ment_search` (find mentions of a brand/keyword across LLM responses) +2. Get top cited domains with `ai_opt_llm_ment_top_domains` (which domains are most cited for this topic) +3. Get top cited pages with `ai_opt_llm_ment_top_pages` (which specific pages are most cited) +4. Get aggregate metrics with `ai_opt_llm_ment_agg_metrics` (overall mention volume, trends) + +**Output:** LLM mention count, top cited domains with frequency, top cited pages, mention trends over time, cross-platform visibility scores. + +**Advanced:** Use `ai_opt_llm_ment_cross_agg_metrics` for cross-model comparison (how mentions differ across ChatGPT, Claude, Perplexity, etc.). + +--- + +## Available Utility Tools + +Additional DataForSEO API operations are available for internal use but do not have dedicated commands. Load `references/tool-catalog.md` when you need to find a specific utility tool (location lookups, bulk operations, historical data, filter options). + +## Cross-Skill Integration + +When DataForSEO credentials are available, other SEO Dungeon skills can leverage live data. Optional MCP tools can be used when already configured: + +- **seo-audit**:Spawn `seo-dataforseo` agent for real SERP, backlink, on-page, and listings data +- **seo-technical**:Use `on_page_instant_pages` / `on_page_lighthouse` for real crawl data, `domain_analytics_technologies_domain_technologies` for stack detection +- **seo-content**:Use `kw_data_google_ads_search_volume`, `dataforseo_labs_bulk_keyword_difficulty`, `dataforseo_labs_search_intent` for real keyword metrics, `content_analysis_summary` for content quality +- **seo-page**:Use `serp_organic_live_advanced` for real SERP positions, `backlinks_summary` for link data +- **seo-images**:Use `serp_google_images_live_advanced` for competitor image SERP data, cross-reference with on-page image audit +- **seo-geo**:Use `ai_optimization_chat_gpt_scraper` for real ChatGPT visibility, `ai_opt_llm_ment_search` for LLM mention tracking +- **seo-plan**:Use `dataforseo_labs_google_competitors_domain`, `dataforseo_labs_google_domain_intersection`, `dataforseo_labs_bulk_traffic_estimation` for real competitive intelligence + +## Error Handling + +- **Credentials not found**: Ask the user to add `DATAFORSEO_USERNAME` or `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` to the selected project `.env`. Do not block on MCP setup. +- **API authentication failed**: Report invalid credentials. Suggest checking DataForSEO login/password in the selected project `.env`. +- **Rate limit exceeded**: Report the limit hit and suggest waiting before retrying +- **No results returned**: Report "no data found" for the query rather than guessing. Suggest broadening the query or checking location/language codes +- **Invalid location code**: Report the error and suggest using the locations lookup tool to find the correct code + +## Output Formatting + +Match existing claude-seo output patterns: +- Use tables for comparative data +- Prioritize issues as Critical > High > Medium > Low +- Include specific, actionable recommendations +- Show scores as XX/100 where applicable +- Note data source as "DataForSEO (live)" to distinguish from static analysis diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/references/cost-tiers.md b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/references/cost-tiers.md new file mode 100644 index 00000000..ab13a51a --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/references/cost-tiers.md @@ -0,0 +1,60 @@ +# DataForSEO API Cost Reference + +## Pricing Tiers (USD per call, standard queue) + +| Category | Endpoint | Cost/Call | Notes | +|----------|----------|-----------|-------| +| **SERP** | `serp_*_live_advanced` | $0.002 | Per 100 results | +| **SERP** | `serp_*_live_regular` | $0.001 | Lightweight | +| **SERP Images** | `serp_google_images_live_*` | $0.002 | 5x with site:/filetype: operators | +| **Keywords** | `kw_data_google_ads_search_volume` | $0.05 | Per batch of keywords | +| **Keywords** | `kw_data_google_trends_explore` | $0.01 | Per query | +| **Labs** | `dataforseo_labs_*_keyword_*` | $0.05 | Ideas, suggestions, related | +| **Labs** | `dataforseo_labs_bulk_*` | $0.01 | Difficulty, traffic | +| **Labs** | `dataforseo_labs_*_domain_*` | $0.05 | Competitors, intersection | +| **On-Page** | `on_page_instant_pages` | $0.01 | Quick analysis | +| **On-Page** | `on_page_lighthouse` | $0.02 | Full Lighthouse | +| **Backlinks** | `backlinks_*` | $0.02 | Per sub-call | +| **Content** | `content_analysis_*` | $0.02 | Search, summary, trends | +| **Business** | `business_data_*` | $0.05 | Listings search | +| **AI/GEO** | `ai_optimization_*` | $0.05 | ChatGPT scraper, LLM mentions | +| **Merchant** | `merchant_*` | $0.02 | Google Shopping, Amazon | +| **Domain** | `domain_analytics_whois_*` | $0.005 | WHOIS data | +| **Domain** | `domain_analytics_technologies_*` | $0.01 | Tech stack | + +## Budget Presets + +| Preset | Daily Limit | Threshold | Mode | Best For | +|--------|------------|-----------|------|----------| +| **Conservative** | $2.00 | $0.10 | threshold | Learning, testing | +| **Standard** | $10.00 | $0.50 | threshold | Regular audits | +| **Aggressive** | $50.00 | $2.00 | threshold | Agency bulk work | +| **Unlimited** | $999.00 | -- | none | Trusted pipelines | + +Configure with: `python3 scripts/dataforseo_costs.py config --mode threshold --threshold 0.50 --daily-limit 10.00` + +## Cost Reduction Tips + +- Use `live_regular` instead of `live_advanced` when full SERP features aren't needed (50% savings) +- Batch keywords into single `search_volume` calls instead of individual SERP lookups +- Use `standard` task queue instead of `live` for non-urgent analysis (60-80% savings) +- Avoid `site:` and `filetype:` operators in image SERP queries (5x cost multiplier) +- Cache session results — don't re-fetch the same keyword/domain within a session + +## Approval Flow + +Before any DataForSEO MCP call: +1. Run `python3 scripts/dataforseo_costs.py check [--count N]` +2. If `status: "approved"` → proceed +3. If `status: "needs_approval"` → show cost to user, ask to confirm +4. If `status: "blocked"` → inform user daily limit would be exceeded +5. After call completes, log: `python3 scripts/dataforseo_costs.py log ` + +## Warn Endpoints + +These endpoints always require user confirmation regardless of approval mode: +- `backlinks_backlinks` (can generate large result sets) +- `backlinks_domain_intersection` (expensive multi-domain comparison) +- `ai_optimization_chat_gpt_scraper` (ChatGPT web scraping) +- `ai_opt_llm_ment_search` (LLM mention tracking) +- `merchant_amazon_products_search` (Amazon product data) diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/references/tool-catalog.md b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/references/tool-catalog.md new file mode 100644 index 00000000..59650071 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-dataforseo/references/tool-catalog.md @@ -0,0 +1,58 @@ +# DataForSEO MCP Tool Catalog + +> Load this reference when you need to find a specific DataForSEO MCP tool +> that is not covered by the main SKILL.md commands. These are utility tools +> available for internal use but without dedicated `/seo dataforseo` commands. + +## SERP Utilities + +- `serp_locations`: Location code lookups for SERP queries +- `serp_youtube_locations`: Location code lookups for YouTube queries + +## Keyword Data Utilities + +- `kw_data_google_ads_locations`: Location lookups for keyword data +- `kw_data_dfs_trends_demography`: Demographic data for trend analysis +- `kw_data_dfs_trends_subregion_interests`: Subregion interest data for trends +- `kw_data_dfs_trends_explore`: DFS proprietary trends data +- `kw_data_google_trends_categories`: Google Trends category lookups + +## DataForSEO Labs Utilities + +- `dataforseo_labs_google_keyword_overview`: Quick keyword metrics overview +- `dataforseo_labs_google_historical_serp`: Historical SERP results for a keyword +- `dataforseo_labs_google_serp_competitors`: Competitors for a specific SERP +- `dataforseo_labs_google_keywords_for_site`: Keywords a site ranks for (alternative to ranked) +- `dataforseo_labs_google_page_intersection`: Page-level intersection analysis +- `dataforseo_labs_google_historical_rank_overview`: Historical domain rank data +- `dataforseo_labs_google_historical_keyword_data`: Historical keyword metrics +- `dataforseo_labs_available_filters`: Available filter options for Labs endpoints + +## Backlinks Utilities + +- `backlinks_competitors`: Find domains with similar backlink profiles +- `backlinks_bulk_backlinks`: Bulk backlink counts for multiple targets +- `backlinks_bulk_new_lost_referring_domains`: Bulk new/lost referring domains +- `backlinks_bulk_new_lost_backlinks`: Bulk new/lost backlinks +- `backlinks_bulk_ranks`: Bulk rank overview for multiple targets +- `backlinks_bulk_referring_domains`: Bulk referring domain counts +- `backlinks_domain_pages_summary`: Summary of pages on a domain +- `backlinks_domain_pages`: List pages on a domain with backlink data +- `backlinks_page_intersection`: Shared backlink sources at page level +- `backlinks_referring_networks`: Referring network analysis +- `backlinks_timeseries_new_lost_summary`: Track new/lost backlinks over time +- `backlinks_bulk_pages_summary`: Bulk page summaries +- `backlinks_available_filters`: Available filter options for Backlinks endpoints + +## Domain Analytics Utilities + +- `domain_analytics_whois_available_filters`: WHOIS filter options +- `domain_analytics_technologies_available_filters`: Technology detection filter options + +## AI Optimization Utilities + +- `ai_opt_kw_data_loc_and_lang`: AI optimization keyword data locations/languages +- `ai_optimization_keyword_data_search_volume`: AI-specific keyword volume data +- `ai_optimization_llm_response`: Direct LLM response analysis +- `ai_optimization_llm_mentions_filters`: Available filters for LLM mentions +- `ai_optimization_chat_gpt_scraper_locations`: Available locations for ChatGPT scraper diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-drift/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-drift/SKILL.md new file mode 100644 index 00000000..fb46db5c --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-drift/SKILL.md @@ -0,0 +1,219 @@ +--- +name: seo-drift +description: > + SEO drift monitoring: capture baselines of SEO-critical elements, detect changes, + and track regressions over time. Git for SEO — baseline, diff, and track changes + to your on-page SEO. Use when user says "SEO drift", "baseline", "track changes", + "did anything break", "SEO regression", "compare SEO", "before and after", + "monitor SEO changes", or "deployment check". +user-invocable: true +argument-hint: "baseline|compare|history " +license: MIT +metadata: + author: AgriciDaniel + original_author: "Dan Colta (Pro Hub Challenge)" + version: "2.2.16" + category: seo +--- + +# SEO Drift Monitor (April 2026) + +Git for your SEO. Capture baselines, detect regressions, track changes over time. + +--- + +## Commands + +| Command | Purpose | +|---------|---------| +| `/seo drift baseline ` | Capture current SEO state as a "known good" snapshot | +| `/seo drift compare ` | Compare current page state to stored baseline | +| `/seo drift history ` | Show change history and past comparisons | + +--- + +## What It Captures + +Every baseline records these SEO-critical elements: + +| Element | Field | Source | +|---------|-------|--------| +| Title tag | `title` | `parse_html.py` | +| Meta description | `meta_description` | `parse_html.py` | +| Canonical URL | `canonical` | `parse_html.py` | +| Robots directives | `meta_robots` | `parse_html.py` | +| H1 headings | `h1` (array) | `parse_html.py` | +| H2 headings | `h2` (array) | `parse_html.py` | +| H3 headings | `h3` (array) | `parse_html.py` | +| JSON-LD schema | `schema` (array) | `parse_html.py` | +| Open Graph tags | `open_graph` (dict) | `parse_html.py` | +| Core Web Vitals | `cwv` (dict) | `pagespeed_check.py` | +| HTTP status code | `status_code` | `fetch_page.py` | +| HTML content hash | `html_hash` (SHA-256) | Computed | +| Schema content hash | `schema_hash` (SHA-256) | Computed | + +--- + +## How Comparison Works + +The comparison engine applies **17 rules across 3 severity levels**. Load +`references/comparison-rules.md` for the full rule set with thresholds, +recommended actions, and cross-skill references. + +### Severity Levels + +| Level | Meaning | Response Time | +|-------|---------|---------------| +| **CRITICAL** | SEO-breaking change, likely traffic loss | Immediate | +| **WARNING** | Potential impact, needs investigation | Within 1 week | +| **INFO** | Awareness only, may be intentional | Review at convenience | + +--- + +## Storage + +All data is stored locally in SQLite: + +``` +~/.cache/claude-seo/drift/baselines.db +``` + +### Tables + +- **baselines**: Captured snapshots with all SEO elements +- **comparisons**: Diff results with triggered rules and severities + +URL normalization ensures consistent matching: lowercase scheme/host, strip +default ports (80/443), sort query parameters, remove UTM parameters, strip +trailing slashes. + +--- + +## Command: `baseline` + +Captures the current state of a page and stores it. + +**Steps:** +1. Validate URL (SSRF protection via `google_auth.validate_url()`) +2. Fetch page via `scripts/fetch_page.py` +3. Parse HTML via `scripts/parse_html.py` +4. Optionally fetch CWV via `scripts/pagespeed_check.py` (use `--skip-cwv` to skip) +5. Hash HTML body and schema content (SHA-256) +6. Store snapshot in SQLite + +**Execution:** +```bash +python3 scripts/drift_baseline.py +python3 scripts/drift_baseline.py --skip-cwv +``` + +**Output:** JSON with baseline ID, timestamp, URL, and summary of captured elements. + +--- + +## Command: `compare` + +Fetches the current page state and diffs it against the most recent baseline. + +**Steps:** +1. Validate URL +2. Load most recent baseline from SQLite (or specific `--baseline-id`) +3. Fetch and parse current page state +4. Run all 17 comparison rules +5. Classify findings by severity +6. Store comparison result +7. Output JSON diff report + +**Execution:** +```bash +python3 scripts/drift_compare.py +python3 scripts/drift_compare.py --baseline-id 5 +python3 scripts/drift_compare.py --skip-cwv +``` + +**Output:** JSON with all triggered rules, old/new values, severity, and actions. + +After comparison, offer to generate an HTML report: +```bash +python3 scripts/drift_report.py --output drift-report.html +``` + +--- + +## Command: `history` + +Shows all baselines and comparisons for a URL. + +**Execution:** +```bash +python3 scripts/drift_history.py +python3 scripts/drift_history.py --limit 10 +``` + +**Output:** JSON array of baselines (newest first) with timestamps and comparison summaries. + +--- + +## Cross-Skill Integration + +When drift is detected, recommend the appropriate specialized skill: + +| Finding | Recommendation | +|---------|----------------| +| Schema removed or modified | Run `/seo schema ` for full validation | +| CWV regression | Run `/seo technical ` for performance audit | +| Title or meta description changed | Run `/seo page ` for content analysis | +| Canonical changed or removed | Run `/seo technical ` for indexability check | +| Noindex added | Run `/seo technical ` for crawlability audit | +| H1/heading structure changed | Run `/seo content ` for E-E-A-T review | +| OG tags removed | Run `/seo page ` for social sharing analysis | +| Status code changed to error | Run `/seo technical ` for full diagnostics | + +--- + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable | Report error from `fetch_page.py`. Do not guess state. Suggest user verify URL. | +| No baseline exists for URL | Inform user and suggest running `baseline` first. | +| SSRF blocked (private IP) | Report `validate_url()` rejection. Never bypass. | +| SQLite database missing | Auto-create on first use. No error. | +| CWV fetch fails (no API key) | Store `null` for CWV fields. Skip CWV rules during comparison. | +| Page returns 4xx/5xx | Still capture as baseline (status code IS a tracked field). | +| Multiple baselines exist | Use most recent unless `--baseline-id` specified. | + +--- + +## Security + +- **All URL fetching** goes through `scripts/fetch_page.py` which enforces SSRF protection + (blocks private IPs, loopback, reserved ranges, GCP metadata endpoints) +- **No curl, no subprocess HTTP calls** -- only the project's validated fetch pipeline +- **All SQLite queries** use parameterized placeholders (`?`), never string interpolation +- **TLS always verified** -- no `verify=False` anywhere in the pipeline + +--- + +## Typical Workflows + +### Pre/Post Deployment Check +``` +/seo drift baseline https://example.com # Before deploy +# ... deploy happens ... +/seo drift compare https://example.com # After deploy +``` + +### Ongoing Monitoring +``` +/seo drift baseline https://example.com # Initial capture +# ... weeks later ... +/seo drift compare https://example.com # Check for drift +/seo drift history https://example.com # Review all changes +``` + +### Investigating a Traffic Drop +``` +/seo drift compare https://example.com # What changed? +/seo drift history https://example.com # When did it change? +``` diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-drift/references/comparison-rules.md b/plugins/avalonreset/seo-dungeon/skills/seo-drift/references/comparison-rules.md new file mode 100644 index 00000000..70583e1d --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-drift/references/comparison-rules.md @@ -0,0 +1,124 @@ +# SEO Drift Comparison Rules + +17 rules across 3 severity levels. Each rule compares a specific SEO element +between the stored baseline and the current page state. + +--- + +## CRITICAL (Immediate Action Required) + +These changes typically cause measurable traffic loss within days. + +### Rule 1: Schema/JSON-LD Completely Removed +- **Compare**: Baseline `schema` array has items, current is empty +- **Threshold**: Any schema present before, none now +- **Action**: Restore structured data immediately. Rich results will be lost within hours. +- **Cross-ref**: `/seo schema ` + +### Rule 2: Canonical URL Changed +- **Compare**: Baseline `canonical` vs current `canonical` +- **Threshold**: Different non-null values (after normalization) +- **Action**: Verify the new canonical is intentional. Incorrect canonicals redirect ranking signals to wrong page. +- **Cross-ref**: `/seo technical ` + +### Rule 3: Canonical URL Removed +- **Compare**: Baseline `canonical` was set, current is `null` +- **Threshold**: Had value, now missing +- **Action**: Restore canonical tag. Google will guess, often incorrectly for pages with query parameters. +- **Cross-ref**: `/seo technical ` + +### Rule 4: Noindex Directive Added +- **Compare**: Baseline `meta_robots` did not contain "noindex", current does +- **Threshold**: "noindex" substring now present (case-insensitive) +- **Action**: If unintentional, remove immediately. Page will be dropped from index within days. +- **Cross-ref**: `/seo technical ` + +### Rule 5: H1 Tag Removed Entirely +- **Compare**: Baseline `h1` had entries, current is empty +- **Threshold**: One or more H1s before, zero now +- **Action**: Restore H1 heading. Primary page topic signal for search engines. +- **Cross-ref**: `/seo content ` + +### Rule 6: H1 Text Changed Significantly +- **Compare**: First H1 in baseline vs first H1 in current, SequenceMatcher ratio +- **Threshold**: Similarity ratio < 0.5 (>50% different) +- **Action**: Verify the H1 change aligns with target keyword strategy. +- **Cross-ref**: `/seo content ` + +### Rule 7: Title Tag Removed Entirely +- **Compare**: Baseline `title` was set, current is `null` or empty +- **Threshold**: Had value, now missing +- **Action**: Restore title tag immediately. Google will auto-generate one, often poorly. +- **Cross-ref**: `/seo page ` + +### Rule 8: HTTP Status Code Changed to Error +- **Compare**: Baseline `status_code` was 2xx, current is 4xx or 5xx +- **Threshold**: Status code class changed from success to client/server error +- **Action**: Investigate server error or missing page. Rankings will drop within days. +- **Cross-ref**: `/seo technical ` + +--- + +## WARNING (Investigate Within 1 Week) + +These changes may impact rankings or CTR but are sometimes intentional. + +### Rule 9: Title Text Changed +- **Compare**: Baseline `title` vs current `title` (trimmed) +- **Threshold**: Strings differ (case-sensitive, whitespace-normalized) +- **Action**: Verify new title includes target keywords. Monitor CTR in GSC over 2 weeks. +- **Cross-ref**: `/seo page ` + +### Rule 10: Meta Description Changed +- **Compare**: Baseline `meta_description` vs current `meta_description` +- **Threshold**: Strings differ (trimmed) +- **Action**: Verify new description includes call-to-action and target keywords. Monitor CTR. +- **Cross-ref**: `/seo page ` + +### Rule 11: Core Web Vitals Metric Regressed >20% +- **Compare**: Each CWV metric p75 value (LCP, INP, CLS) baseline vs current +- **Threshold**: Current value is >20% worse than baseline (higher for LCP/INP, higher for CLS) +- **Action**: Investigate performance regression. Check recent code changes or third-party scripts. +- **Cross-ref**: `/seo technical ` + +### Rule 12: CWV Performance Score Dropped 10+ Points +- **Compare**: Lighthouse performance score baseline vs current +- **Threshold**: Drop of 10 or more points (e.g., 85 to 74) +- **Action**: Run full PageSpeed analysis to identify new bottlenecks. +- **Cross-ref**: `/seo google psi ` + +### Rule 13: OG Tags Removed +- **Compare**: Baseline `open_graph` had entries, current is empty +- **Threshold**: One or more OG tags before, none now +- **Action**: Restore OG tags. Social sharing will show generic/missing previews. +- **Cross-ref**: `/seo page ` + +### Rule 14: Schema/JSON-LD Content Modified +- **Compare**: Baseline `schema_hash` vs current `schema_hash` +- **Threshold**: Hash differs AND schema still exists (removal is Rule 1) +- **Action**: Validate modified schema. Check for type changes, removed properties, or new validation errors. +- **Cross-ref**: `/seo schema ` + +--- + +## INFO (Awareness Only) + +These are tracked for completeness. Often positive or neutral changes. + +### Rule 15: New Schema/JSON-LD Added +- **Compare**: Baseline `schema` was empty, current has items +- **Threshold**: No schema before, schema now present +- **Action**: Positive change. Validate the new schema with `/seo schema `. +- **Cross-ref**: `/seo schema ` + +### Rule 16: H2 Structure Changed +- **Compare**: Baseline `h2` array vs current `h2` array +- **Threshold**: Different number of H2s, or different H2 text values +- **Action**: Review heading hierarchy. Ensure content sections still align with target topics. +- **Cross-ref**: `/seo content ` + +### Rule 17: Content Hash Changed +- **Compare**: Baseline `html_hash` vs current `html_hash` +- **Threshold**: Hash differs (catch-all for any body content change) +- **Action**: General content change detected. Review if no other rules triggered to understand what changed. +- **Cross-ref**: `/seo page ` diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/SKILL.md new file mode 100644 index 00000000..4f1f4649 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/SKILL.md @@ -0,0 +1,370 @@ +--- +name: seo-ecommerce +description: > + E-commerce SEO analysis: Google Shopping visibility, Amazon marketplace + intelligence, product schema validation, competitor pricing analysis, and + marketplace keyword gaps. Combines on-page product SEO with marketplace data + from DataForSEO Merchant API. Use when user says "ecommerce SEO", "product SEO", + "Google Shopping", "marketplace SEO", "product schema", "Amazon SEO", + "product listings", "shopping ads", or "merchant SEO". +user-invocable: true +argument-hint: "" +license: MIT +compatibility: "Enhanced with DataForSEO Merchant API (optional)" +metadata: + author: AgriciDaniel + original_author: "Matej Marjanovic (Pro Hub Challenge)" + version: "2.2.16" + category: seo +--- + +# E-commerce SEO Analysis + +Comprehensive product page optimization, marketplace intelligence, and +competitive pricing analysis. Works standalone (on-page + schema) and with +DataForSEO Merchant API for live Google Shopping and Amazon data. + +## Commands + +| Command | Purpose | DataForSEO? | +|---------|---------|-------------| +| `/seo ecommerce ` | Full e-commerce SEO analysis of a product page or store | Optional | +| `/seo ecommerce products ` | Google Shopping competitive analysis | Required | +| `/seo ecommerce gaps ` | Keyword gap: organic vs Shopping visibility | Required | +| `/seo ecommerce schema ` | Product schema validation and enhancement | No | + +--- + +## 1. Product Page Analysis (No DataForSEO Needed) + +Fetch and parse any product page for on-page SEO quality. + +### Workflow + +``` +1. python3 scripts/render_page.py --mode auto → raw/rendered HTML +2. python3 scripts/parse_html.py --url → SEO elements +3. Analyze product-specific signals (below) +``` + +### Product SEO Checklist + +#### Title Tag +- [ ] Contains primary product keyword +- [ ] Includes brand name +- [ ] Under 60 characters (no truncation in SERPs) +- [ ] Format: `[Product Name] - [Key Feature] | [Brand]` + +#### Meta Description +- [ ] Contains product keyword + benefit +- [ ] Includes price or "from $XX" (triggers rich snippet interest) +- [ ] Call-to-action present (Shop now, Buy, Free shipping) +- [ ] Under 155 characters + +#### Heading Structure +- [ ] Single H1 matching primary product name +- [ ] H2s for: Features, Specifications, Reviews, Related Products +- [ ] No duplicate H1 tags across product variants + +#### Product Images +- [ ] Alt text includes product name + distinguishing feature +- [ ] File names are descriptive (not `IMG_001.jpg`) +- [ ] WebP format served (with JPEG fallback) +- [ ] At least 3 images per product (hero, detail, lifestyle) +- [ ] Image dimensions >= 800px for Google Shopping eligibility +- [ ] Lazy loading on below-fold images only + +#### Internal Linking +- [ ] Breadcrumb navigation: Home > Category > Subcategory > Product +- [ ] Related products section (cross-sell / upsell) +- [ ] Link back to category page with keyword-rich anchor +- [ ] Reviews section links to full review page (if separate) + +#### Content Quality +- [ ] Unique product description (not manufacturer copy-paste) +- [ ] Word count >= 200 for product description body +- [ ] Specs table present (not just prose) +- [ ] User reviews on-page (UGC signals) + +### Scoring + +| Category | Weight | Criteria | +|----------|--------|----------| +| Schema completeness | 25% | Required + recommended Product fields | +| Title & meta | 15% | Keyword placement, length, format | +| Image optimization | 20% | Alt text, format, sizing, count | +| Content quality | 20% | Unique description, specs, reviews | +| Internal linking | 10% | Breadcrumbs, related products, categories | +| Technical | 10% | Page speed, mobile rendering, canonical | + +--- + +## 2. Google Shopping Intelligence (DataForSEO Merchant API) + +Live competitive analysis from Google Shopping results. + +### Cost Guardrail (MANDATORY) + +Before EVERY Merchant API call: +```bash +python3 scripts/dataforseo_costs.py check merchant_google_products_search +``` + +- `"status": "approved"` -- proceed +- `"status": "needs_approval"` -- show cost, ask user +- `"status": "blocked"` -- stop, inform user + +After each call: +```bash +python3 scripts/dataforseo_costs.py log merchant_google_products_search +``` + +### Workflow + +```bash +# Product search: who sells what at what price +python3 scripts/dataforseo_merchant.py search "" --marketplace google + +# Seller analysis: merchant ratings and dominance +python3 scripts/dataforseo_merchant.py sellers "" + +# Normalize results for analysis +python3 scripts/dataforseo_normalize.py results.json --module merchant +``` + +### Analysis Outputs + +#### Pricing Intelligence +- Price distribution: min, max, median, P25, P75 +- Price outliers (> 2 standard deviations from median) +- Price-to-rating correlation +- Currency normalization to USD (or user-specified) + +#### Seller Landscape +- Top 10 sellers by listing count +- Merchant rating distribution +- Free shipping prevalence +- New vs established sellers + +#### Product Listing Quality +- Title keyword patterns in top listings +- Average rating and review count benchmarks +- Image count per listing +- Availability status distribution + +Load `references/marketplace-endpoints.md` for full API parameter details. + +--- + +## 3. Amazon Marketplace (DataForSEO) + +Cross-marketplace intelligence comparing Google Shopping and Amazon. + +### Cost Guardrail (MANDATORY) + +```bash +python3 scripts/dataforseo_costs.py check merchant_amazon_products_search +``` + +Amazon endpoints are in the `warn_endpoints` set -- always requires user approval. + +### Workflow + +```bash +# Amazon product search +python3 scripts/dataforseo_merchant.py search "" --marketplace amazon + +# Cross-marketplace comparison +python3 scripts/dataforseo_merchant.py compare "" +``` + +### Cross-Marketplace Report + +| Metric | Google Shopping | Amazon | +|--------|---------------|--------| +| Avg price | $ | $ | +| Median rating | X.X | X.X | +| Avg review count | N | N | +| Top seller share | % | % | +| Free shipping % | % | % | + +--- + +## 4. Marketplace Keyword Gaps + +Identify mismatches between organic and Shopping visibility. + +### Workflow + +1. Fetch organic rankings via seo-dataforseo: + `dataforseo_labs_google_ranked_keywords` for domain +2. Fetch Google Shopping presence via Merchant API: + `merchant_google_products_search` for top organic keywords +3. Cross-reference results + +### Gap Types + +| Gap Type | Meaning | Action | +|----------|---------|--------| +| **Organic Only** | Ranks organically but no Shopping ads | Create Google Merchant Center feed, bid on these keywords | +| **Shopping Only** | Shopping visibility but weak/no organic | Create content (buying guides, comparison pages) for these keywords | +| **Both Present** | Visible in both channels | Optimize: ensure price consistency, enhance schema | +| **Neither** | No visibility in either | Low priority unless high volume | + +### Output Format + +``` +## Keyword Gap Analysis: example.com + +### Opportunities: Organic → Shopping (12 keywords) +| Keyword | Organic Pos | Volume | CPC | Recommended Action | +|---------|------------|--------|-----|-------------------| + +### Opportunities: Shopping → Organic (8 keywords) +| Keyword | Shopping Rank | Volume | CPC | Content Type Needed | +|---------|-------------|--------|-----|-------------------| +``` + +--- + +## 5. Product Schema Enhancement + +Validate and generate Product schema following Google's current requirements. + +### Required Properties (Google Merchant) + +```json +{ + "@context": "https://schema.org", + "@type": "Product", + "name": "", + "image": [""], + "description": "", + "brand": { "@type": "Brand", "name": "" }, + "offers": { + "@type": "Offer", + "url": "", + "priceCurrency": "USD", + "price": "0.00", + "availability": "https://schema.org/InStock", + "seller": { "@type": "Organization", "name": "" } + } +} +``` + +### Recommended Properties (Enhance Rich Results) + +- `sku` -- product identifier +- `gtin13` / `gtin14` / `mpn` -- global trade identifiers +- `aggregateRating` -- star rating + review count +- `review` -- individual reviews (minimum 1) +- `color`, `material`, `size` -- variant attributes +- `shippingDetails` -- ShippingDetails with rate and delivery time +- `hasMerchantReturnPolicy` -- MerchantReturnPolicy with type and days + +### Validation Rules + +1. `price` must be a number string, not "$29.99" (no currency symbol) +2. `availability` must use full Schema.org URL enum +3. `image` should be array with >= 1 high-res image URL +4. `priceCurrency` must be ISO 4217 (USD, EUR, GBP) +5. `brand.name` must not be empty or "N/A" +6. Dates in `priceValidUntil` must be ISO 8601 +7. If `aggregateRating` present: `ratingValue` and `reviewCount` required + +### Schema Scoring + +| Completeness | Score | +|-------------|-------| +| All required fields | 50/100 | +| + aggregateRating | 65/100 | +| + sku/gtin/mpn | 75/100 | +| + shippingDetails | 85/100 | +| + merchantReturnPolicy | 90/100 | +| + reviews (3+) | 100/100 | + +--- + +## Cross-Skill Integration + +| Skill | Integration Point | +|-------|------------------| +| **seo-schema** | Delegates Product schema generation; reuses validation logic | +| **seo-images** | Product image audit (alt text, format, dimensions) — plus `DigitalSourceType: TrainedAlgorithmicMedia` IPTC label for AI-generated product images (Merchant Center requirement) | +| **seo-content** | Product description E-E-A-T and uniqueness analysis | +| **seo-dataforseo** | Organic keyword rankings for gap analysis | +| **seo-technical** | Core Web Vitals for product pages (LCP on hero image) | +| **seo-google** | Google Merchant Center feed validation via GSC | + +## UCP — Universal Commerce Protocol (forward-looking) + +Google-led standard (co-developed with Shopify, Etsy, Walmart, Wayfair, Visa, +Mastercard, etc.) for letting AI agents discover, negotiate, and transact with +merchants without one-off integrations. Already powers direct buying from AI +Mode and Gemini. + +Merchants already on **Google Merchant Center** with clean Product schema can +declare a UCP profile at `/.well-known/ucp` listing capabilities +(`dev.ucp.shopping.checkout`, `.fulfillment`, `.discount`). See +`references/ucp-universal-commerce-protocol.md` for audit criteria, +capability examples, and the relationship to AP2 (Agent Payments Protocol). + +### Audit command + +```bash +# Discover and validate the UCP profile +python3 scripts/ucp_check.py https://store.example.com --json + +# With endpoint reachability probes (HEAD each declared capability) +python3 scripts/ucp_check.py https://store.example.com --probe-endpoints --json +``` + +The script returns: profile presence, version, declared capabilities, +structural issues (missing fields, unknown capability IDs), and (with +`--probe-endpoints`) per-endpoint reachability. SSRF-blocked endpoints are +reported explicitly. Missing profile is reported as opportunity, not failure +— UCP adoption is early. + +--- + +## Error Handling + +| Error | Cause | Response | +|-------|-------|----------| +| No Product schema found | Page lacks JSON-LD | Analyze page content, generate recommended schema | +| DataForSEO credentials missing | Env vars not set | Run analysis without marketplace data, note limitation | +| Cost check blocked | Daily budget exceeded | Inform user, offer free-only analysis | +| Empty Shopping results | No products for keyword | Suggest broader keyword, check location settings | +| Amazon API timeout | Network/rate limit | Retry with backoff, fall back to Google-only | +| Invalid URL | Malformed input | Validate via `google_auth.validate_url()`, show error | +| Non-product page | URL is category/homepage | Detect page type, suggest `/seo ecommerce schema` instead | + +--- + +## Output Template + +``` +## E-commerce SEO Report: [URL or Keyword] + +### Overall Score: XX/100 + +### Product Page SEO +- Schema Completeness: XX/100 +- Title & Meta: XX/100 +- Image Optimization: XX/100 +- Content Quality: XX/100 +- Internal Linking: XX/100 + +### Marketplace Intelligence (if DataForSEO available) +- Google Shopping Listings: N products found +- Price Range: $XX - $XX (median: $XX) +- Top Seller: [name] (XX% market share) +- Amazon Comparison: [available/not checked] + +### Top Recommendations +1. [Critical] ... +2. [High] ... +3. [Medium] ... + +Generate a PDF report? Use `/seo google report` +``` diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/references/marketplace-endpoints.md b/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/references/marketplace-endpoints.md new file mode 100644 index 00000000..7b32ea8d --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/references/marketplace-endpoints.md @@ -0,0 +1,119 @@ +# DataForSEO Merchant API Reference + +Endpoint details for Google Shopping and Amazon marketplace data. + +## Endpoints + +### Google Shopping Products + +| Field | Value | +|-------|-------| +| Endpoint | `merchant_google_products_search` | +| Method | POST (task) / GET (results) | +| Cost | $0.02 per call | +| Queue | Standard (60-80% savings vs live) | + +**Parameters:** +- `keyword` (required) -- search query +- `location_code` (default: 2840 = US) -- DataForSEO location ID +- `language_code` (default: "en") -- language +- `price_min` / `price_max` (optional) -- filter by price range +- `sort_by` (optional) -- "relevance", "price_low_to_high", "price_high_to_low", "rating" +- `depth` (optional, default: 100) -- number of results + +**Response fields:** +- `title` -- product listing title +- `price` -- numeric price value +- `currency` -- currency code (USD, EUR, etc.) +- `seller` -- merchant name +- `rating` -- product rating (float, 0-5) +- `reviews_count` -- number of reviews +- `url` -- product listing URL +- `image_url` -- product image URL +- `availability` -- "in_stock", "out_of_stock", "preorder" +- `delivery_info` -- shipping details text +- `product_id` -- Google Shopping product ID + +### Google Shopping Sellers + +| Field | Value | +|-------|-------| +| Endpoint | `merchant_google_sellers_search` | +| Method | POST (task) / GET (results) | +| Cost | $0.02 per call | + +**Parameters:** Same as products search. + +**Response fields:** +- `seller_name` -- merchant name +- `seller_rating` -- merchant rating (float) +- `seller_reviews_count` -- merchant review count +- `price` -- price offered by this seller +- `delivery_info` -- shipping and delivery text +- `url` -- seller listing URL + +### Amazon Products + +| Field | Value | +|-------|-------| +| Endpoint | `merchant_amazon_products_search` | +| Method | POST (task) / GET (results) | +| Cost | $0.02 per call | +| Note | In `warn_endpoints` -- always requires user approval | + +**Parameters:** +- `keyword` (required) -- search query +- `location_code` (default: 2840 = US) +- `language_code` (default: "en") +- `depth` (optional, default: 100) +- `sort_by` (optional) -- "relevance", "price_low_to_high", "price_high_to_low", "avg_customer_review" + +**Response fields:** +- `title` -- product title +- `price` -- numeric price +- `currency` -- currency code +- `seller` -- seller/brand name +- `rating` -- star rating (float, 0-5) +- `reviews_count` -- review count +- `url` -- Amazon product URL +- `image_url` -- product image +- `availability` -- stock status +- `asin` -- Amazon Standard Identification Number +- `is_prime` -- Prime eligibility (boolean) +- `is_best_seller` -- Best Seller badge (boolean) + +## Task/Poll Pattern + +All Merchant endpoints use the standard DataForSEO queue pattern: + +1. **POST** task with parameters to create endpoint +2. **Poll** for results with exponential backoff (2s, 4s, 8s, max 60s) +3. **GET** completed results by task ID + +This saves 60-80% compared to live endpoints. + +## Rate Limits + +- Max 2000 tasks per minute (across all endpoints) +- Max 30,000 tasks per day on standard plans +- Backoff on HTTP 429: wait 60 seconds, then retry + +## Data Normalization + +When consuming responses, normalize: + +| Field | Raw | Normalized | +|-------|-----|-----------| +| Price | String "$29.99" or float | Float `29.99` | +| Currency | Mixed formats | ISO 4217 code (USD, EUR, GBP) | +| Availability | Various strings | Enum: `in_stock`, `out_of_stock`, `preorder`, `unknown` | +| Rating | Integer or float | Float rounded to 1 decimal | +| Reviews | String or int | Integer | + +Use `scripts/dataforseo_normalize.py --module merchant` for automatic normalization. + +## Cost Reference + +See `skills/seo-dataforseo/references/cost-tiers.md` for the full pricing table, +budget presets, and cost reduction tips. All Merchant endpoints are $0.02/call +on standard queue. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/references/ucp-universal-commerce-protocol.md b/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/references/ucp-universal-commerce-protocol.md new file mode 100644 index 00000000..606277be --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-ecommerce/references/ucp-universal-commerce-protocol.md @@ -0,0 +1,120 @@ +# UCP — Universal Commerce Protocol (May 2026) + +UCP is a Google-led open standard, co-developed with Shopify and endorsed by +Etsy, Target, Walmart, Wayfair, plus payment partners (Stripe, Visa, +Mastercard, Adyen, Amex). Its purpose: let **AI agents discover, negotiate, +and transact with merchants without one-off integrations**. + +For commerce sites, UCP sits next to **Google Merchant Center feeds** and +**Google Business Profile** as the third leg of agent-era discovery. Adoption +is early but the cost of declaring a profile is low. + +**Primary source:** Google AI optimization guide references UCP; the spec +itself is co-published at developer.google.com / merchant.google.com (consult +Google for the current canonical URL — the standard is moving). + +## What UCP is and isn't + +| What it is | What it isn't | +|---|---| +| A capability-declaration + negotiation protocol | A new payment processor | +| Transport-agnostic (REST, MCP, A2A) | A replacement for Merchant Center feeds | +| Compatible with AP2 (Agent Payments Protocol) for cryptographic user-consent proof on autonomous purchases | A way to skip being merchant of record | +| Adopted by AI Mode in Search and Gemini today | A "ranking factor" — Google has not framed it that way | + +Merchants stay **Merchant of Record** under UCP — they keep customer +relationships and post-purchase ownership. + +## How to declare a UCP profile + +Publish a profile at `/.well-known/ucp` describing capabilities and versions. +The general shape (consult the live spec for exact field names): + +```jsonc +{ + "version": "1.0", + "capabilities": [ + { + "id": "dev.ucp.shopping.checkout", + "version": "1.0", + "endpoint": "https://api.example.com/ucp/checkout" + }, + { + "id": "dev.ucp.shopping.fulfillment", + "version": "1.0", + "endpoint": "https://api.example.com/ucp/fulfillment" + }, + { + "id": "dev.ucp.shopping.discount", + "version": "1.0", + "endpoint": "https://api.example.com/ucp/discount" + } + ], + "merchant": { + "name": "Example Co.", + "id": "merchant-center-id-here" + } +} +``` + +Platforms (AI Mode in Search, Gemini, and eventually others) auto-discover +the profile and negotiate. Google has built a reference implementation +powering direct buying from AI Mode and Gemini. + +## Common capabilities to declare + +| Capability ID (shape) | Purpose | +|---|---| +| `dev.ucp.shopping.checkout` | Initiate checkout, return totals + payment intent | +| `dev.ucp.shopping.fulfillment` | Quote shipping options and delivery windows | +| `dev.ucp.shopping.discount` | Apply promo codes / loyalty discounts at quote time | +| `dev.ucp.shopping.cart` | Add / remove / update items in agent-managed carts | + +Exact identifiers are governed by the live spec. The pattern is +`dev.ucp..` with semantic versioning. + +## What claude-seo audits + +`/seo ecommerce ` should report: + +1. **Presence:** does `/.well-known/ucp` resolve to a valid JSON document? +2. **Capability coverage:** which capabilities are declared? Flag missing + checkout / fulfillment / discount as opportunities, not failures (the + protocol is early). +3. **Endpoint reachability:** are declared endpoints HTTPS, valid TLS, not + returning 5xx? +4. **Version coherence:** does the declared protocol version match a known + release? Flag pre-release or unrecognized versions. + +The audit should **not** score the absence of UCP as a critical failure today +— adoption is early. Frame it as a forward-looking opportunity, especially +for merchants already on Google Merchant Center. + +## How UCP interacts with existing surfaces + +| Existing surface | Relationship to UCP | +|---|---| +| Google Merchant Center feed | Required upstream — UCP capabilities reference Merchant Center products by ID | +| Google Business Profile | Independent — UCP is product / order; GBP is store / location | +| Product schema (`hasMerchantReturnPolicy`, `shippingDetails`) | Complementary — UCP exposes the same data at the API layer; schema exposes it at the page layer | +| AP2 (Agent Payments Protocol) | Pair — UCP handles discovery + checkout structure; AP2 handles cryptographic proof of user consent | + +A merchant that already has clean Merchant Center feeds, complete Product +schema, and a checkout API can declare a UCP profile in a sprint. + +## Audit posture + +- **Tier 1 (e-commerce sites already on Merchant Center):** recommend + declaring a UCP profile as a forward-looking opportunity. +- **Tier 2 (DTC sites not on Merchant Center):** do not recommend UCP yet — + Merchant Center is the prerequisite to most flows. +- **Tier 3 (informational / B2B sites):** ignore UCP entirely. + +## Last verified + +2026-05-18. The standard is moving fast. Re-check when: + +- The canonical spec URL stabilizes (currently published on Google developer + docs, but exact path may change). +- AP2 reaches stable release. +- Additional platforms (beyond AI Mode + Gemini) announce UCP consumption. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/SKILL.md new file mode 100644 index 00000000..7314ee58 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/SKILL.md @@ -0,0 +1,136 @@ +--- +name: seo-flow +description: > + FLOW framework integration — evidence-led SEO using the Find → Leverage → + Optimize → Win loop. Surfaces stage-specific AI prompts from the FLOW + knowledge base (41 prompts, CC BY 4.0). Use when user says "FLOW", "FLOW + framework", "seo flow", "evidence-led SEO", "find leverage optimize win", + or wants stage-specific SEO prompts. +user-invocable: true +argument-hint: "[stage] [url|topic]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# FLOW Framework — Find · Leverage · Optimize · Win + +> Framework and prompts © Daniel Agrici, CC BY 4.0 — github.com/AgriciDaniel/flow + +FLOW is an evidence-led SEO operating model built for the AI-search era. Claude SEO +integrates the FLOW prompt library (41 prompts across 5 stages) so every analysis can +be driven by structured, evidence-backed AI prompts rather than improvised queries. + +**Runtime context:** Load `references/flow-framework.md` on every `/seo flow` activation. +Load prompt files on demand — only for the stage the user requests. + +--- + +## Commands + +| Command | What it does | +|---------|-------------| +| `/seo flow` | Show FLOW overview + stage menu | +| `/seo flow find [url\|topic]` | Find-stage: keyword research, gap analysis, SERP intent mapping (5 prompts) | +| `/seo flow leverage [url]` | Leverage-stage: backlink strategy, off-site authority (1 prompt) | +| `/seo flow optimize [url]` | Optimize-stage: select 2-3 most relevant of 21 prompts based on context | +| `/seo flow win [url]` | Win-stage: BOFU, conversion rate, dual-surface scorecard (3 prompts) | +| `/seo flow local [url]` | Local-stage: GBP optimization, meta, title tags, local audits (11 prompts) | +| `/seo flow prompts` | Full index of all 41 prompts — stage, name, trigger conditions | +| `/seo flow sync` | Pull latest prompt files from github.com/AgriciDaniel/flow | + +--- + +## Orchestration Logic + +### On `/seo flow` (no sub-command) +1. Read `references/flow-framework.md` +2. Show the FLOW stage overview with a one-line description of each stage +3. Ask: which stage matches the user's current situation? + +### On `/seo flow find [url|topic]` +1. Read all files in `references/prompts/find/` +2. Apply each prompt to the URL or topic +3. Cross-reference: "For deeper SERP clustering, see `/seo cluster `" + +### On `/seo flow leverage [url]` +1. Read the file in `references/prompts/leverage/` +2. Apply to the URL's current backlink context +3. Cross-reference: "For raw backlink data, see `/seo backlinks `" + +### On `/seo flow optimize [url]` +1. Read all file names in `references/prompts/optimize/` +2. Read prior analysis context (URL, industry vertical, any prior skill output in conversation) +3. Select 2-3 most relevant prompts; load only those files +4. Apply selected prompts; note the others are accessible via `/seo flow prompts` +5. Cross-reference: "For full content quality analysis, see `/seo content ` and `/seo geo `" + +### On `/seo flow win [url]` +1. Read all files in `references/prompts/win/` +2. Apply each prompt to the URL's conversion and BOFU context +3. Cross-reference: "For SXO persona scoring, see `/seo sxo `" + +### On `/seo flow local [url]` +1. Read all files in `references/prompts/local/` +2. Apply to the URL's local SEO context +3. Cross-reference: "For full local SEO analysis, see `/seo local ` and `/seo maps [command]`" + +### On `/seo flow prompts` +1. Read `references/prompts/README.md` +2. Display the full index: all 41 prompts with stage, name, trigger conditions + +### On `/seo flow sync` +1. Run: `python3 scripts/sync_flow.py` +2. Display the JSON summary (files added, updated, unchanged) +3. Show attribution notice after sync completes + +--- + +## Context Matching (Optimize stage) + +The optimize stage has 21 prompts. Dumping all 21 is noise. Select by priority: + +1. **Industry vertical** (SaaS → on-page + technical; local → citations + GBP; publisher → E-E-A-T + freshness) +2. **Prior skill output** (seo-technical flagged crawl issues → technical optimize prompts; seo-content flagged E-E-A-T gaps → content optimize prompts) +3. **URL signals** (product pages → conversion; blog → freshness + authority) + +Always surface exactly 2-3 prompts. State which prompts you chose and why. + +--- + +## Reference Files + +Load on-demand — do NOT load all at startup: +- `references/flow-framework.md` — FLOW operating model (load on every `/seo flow` activation) +- `references/bibliography.md` — Evidence sources; load when citing studies or statistics +- `references/prompts/README.md` — Prompt index; load for `/seo flow prompts` +- `references/prompts/find/` — 5 prompts; load for `/seo flow find` +- `references/prompts/leverage/` — 1 prompt; load for `/seo flow leverage` +- `references/prompts/optimize/` — 21 prompts; load selectively for `/seo flow optimize` +- `references/prompts/win/` — 3 prompts; load for `/seo flow win` +- `references/prompts/local/` — 11 prompts; load for `/seo flow local` + +--- + +## Attribution + +Every `/seo flow` activation (any sub-command) outputs before analysis: + +``` +Framework and prompts © Daniel Agrici, CC BY 4.0 — github.com/AgriciDaniel/flow +``` + +Do not omit or modify the attribution. + +--- + +## Error Handling + +| Scenario | Action | +|----------|--------| +| `references/flow-framework.md` missing | "FLOW reference files not synced. Run: `/seo flow sync`" | +| Prompt file missing | "Run `/seo flow sync` to pull the latest prompts from the FLOW repo." | +| `sync_flow.py` network error | Display the script's stderr. Check rate limits: `gh api rate_limit`. | +| `sync_flow.py` auth error | Run `gh auth login` then retry. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/bibliography.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/bibliography.md new file mode 100644 index 00000000..2e303313 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/bibliography.md @@ -0,0 +1,69 @@ + +--- +title: "Bibliography" +description: "Bibliography" +updated: 2026-04-25 +tags: + - references +--- + +# Bibliography + +This bibliography lists the sources used for public claims. Web sources include retrieval date. PDF sources include hash and page count from the canonical manifest. + +## Web Sources + +- https://ahrefs.com/blog/ai-overviews-reduce-clicks-update/ | retrieved 2026-04-25 | used for: 58% lower average CTR for position-one content when an AI Overview is present, using December 2025 Ahrefs data +- https://backlinko.com/google-user-behavior | retrieved 2026-04-25 | used for: 42% of local-query searchers click inside the Google Maps Pack +- https://gs.statcounter.com/search-engine-market-share/all/worldwide/2025 | retrieved 2026-04-25 | used for: Bing March 2026 share: 5.13% worldwide; 9.85% United States all-platform search share +- https://support.google.com/business/answer/10515606?hl=en | retrieved 2026-04-25 | used for: 70% more likely to visit; 50% more likely to consider purchasing +- https://www.brightlocal.com/resources/local-seo-statistics/ | retrieved 2026-04-25 | used for: 39% +- https://www.pewresearch.org/short-reads/2025/07/22/google-users-are-less-likely-to-click-on-links-when-an-ai-summary-appears-in-the-results/ | retrieved 2026-04-25 | used for: 8% with AI summary vs 15% without AI summary +- https://www.searchenginejournal.com/state-of-seo/ | retrieved 2026-04-25 | used for: 77.9% worry about AI reducing website clicks +- https://www.sec.gov/Archives/edgar/data/1652044/000165204426000018/goog-20251231.htm | retrieved 2026-04-25 | used for: 73.2% of FY2025 revenue from Google advertising: $294.691B / $402.836B +- https://www.semrush.com/blog/semrush-ai-overviews-study/ | retrieved 2026-04-25 | used for: 33.75% to 31.53% +- https://www.seoclarity.net/research/analysis-of-top-cited-pages-from-chatgpt | retrieved 2026-04-25 | used for: 25% of top 1,000 cited URLs have zero organic visibility in Google + +## PDF Sources + +- PPC_Trends_2026.pdf | tier A | pages 30 | sha256 `609cbad8786070cf40290a86bdc9c16d5c5530b0460b91eb9f82fc14fe4d8122` | action: extract-and-consider +- SEJ_LeveragingGenerativeAI_F.pdf | tier C | pages 86 | sha256 `26985b1ebdbd1b725b3a78bd4b26bd576c89dab7fdd19c4dfed06f8e697bda4c` | action: extract-and-consider +- SEJ_SEOInTheAgeOfAI_F.pdf | tier C | pages 78 | sha256 `a7142071e46c7461ef263ed5ac7da0e343f83d900e9c3ea74b18e05c8364311f` | action: extract-and-consider +- SEJ_State_of_AI_in_Marketing_F.pdf | tier C | pages 13 | sha256 `c099f7700d58b40f8c55e408c58f65f71ad5bc8981d266d3701363308cebb9af` | action: extract-and-consider +- SEJ_StateofSEO2026.pdf | tier A | pages 31 | sha256 `4cf17f9eb89a911ab17a9faf90f3d0069af8e4acc12a77d86023d0b318577791` | action: extract-and-consider +- SEJ_UX&SEO.pdf | tier C | pages 24 | sha256 `8ac6a00e5cc1763191d852072d0f8e4223598a7c61ce52b84834840ba02850b9` | action: extract-and-consider +- SEO Books/CallRail_X_SEJ_BetterLeadsMoreSales_2025.pdf | tier B | pages 20 | sha256 `1126aa175b8486dbe36bc6dcd83728cc2e93505545d11d6f16568ac90ef2e733` | action: extract-and-consider +- SEO Books/Hobo-Beginner-SEO-2025.pdf | tier B | pages 52 | sha256 `eb16d509a75235adc0bdb3bf6e49d4e57044053a409f657c219dacea10da3355` | action: extract-and-consider +- SEO Books/Hobo-Strategic-AiSEO-2025.pdf | tier B | pages 294 | sha256 `7885d7bd3cbe4e480c018b97640119f94d7f20744bcbfeb24ba9efee34f1442f` | action: extract-and-consider +- SEO Books/SEJ_B2B_Lead_Generation_F.pdf | tier C | pages 61 | sha256 `12bf9f5317fcc91bc94cf720f3a7522422526468c240691392054b408c7b9075` | action: extract-and-consider +- SEO Books/SEJ_PPC_Experts_Tips_2023.pdf | tier D | pages 57 | sha256 `4d3a4db69556115b25f5bda9afc1ccb5affbdfbd419691ec99f998510329fee8` | action: extract-and-consider +- SEO Books/SEJ_SEO_Audit_2023.pdf | tier D | pages 76 | sha256 `965ed0e620cd5624815530d8f7609d1d9ba44968da8189e3589f18224ebeab87` | action: extract-and-consider +- SEO Books/SEJ_TheDarkSideofLinkBuilding.pdf | tier C | pages 59 | sha256 `cfa4c81c58d431923dce81ce2b3afb4c5e6db0fdd3a7aca6117c49b7e1eb1d65` | action: extract-and-consider +- SEO Books/SEJ_The_Future_of_AI_Search_F.pdf | tier C | pages 17 | sha256 `4032124fd73160ae008e7d8598090c46b230641095fd2acb46c97b282c21bd43` | action: extract-and-consider +- SEO Press/10_tips_boost_site_speed-en.pdf | tier E | pages 11 | sha256 `f9e07b750e738362ea624f2485a5c767d8db0c7bae61e9cb0f53d79cd7054c6b` | action: skip-by-default +- SEO Press/ai-seo-copywriting-seopress-en.pdf | tier E | pages 59 | sha256 `89683c171d379c6e6305d34e83da12d4b67a9ff5a31675246cca9d0c2f7f244c` | action: skip-by-default +- SEO Press/ebook-seopress-beginners-guide-to-seo.pdf | tier E | pages 67 | sha256 `cee1d0948ad1f03f90ef35db3dc2948c455f74c847424bab28d0edd1336743db` | action: skip-by-default +- SEO Press/ebook-seopress-guide-local-seo-en.pdf | tier E | pages 37 | sha256 `bd27e4dfb7af6fcd9b68f3a99e6df502ca4f75d896ba0ef0fd05e70e27250199` | action: skip-by-default +- SEO Press/ebook-seopress-guide-schemas-en.pdf | tier E | pages 39 | sha256 `5a39a137e3a563ac73607fc8349d6f0dee7ffb1d5206f5583a28c4fc7213d076` | action: skip-by-default +- SEO Press/emergency-seo-en.pdf | tier E | pages 44 | sha256 `51bfb7eb0fc2cfb5fb4f77bea2493c21b3287a4c3edfb96c3d5c28a06244d39c` | action: skip-by-default +- SEO Press/first-site-seo-en.pdf | tier E | pages 58 | sha256 `0ac67cbc71193da57226f8be8b253d5d84519504cc47cb865424403509dd2399` | action: skip-by-default +- SEO Press/google-search-console-en-compress.pdf | tier E | pages 49 | sha256 `0a768cb025fba68afdea8786c35eec8f4c197d83f1516e926a3906dc99d45d65` | action: skip-by-default +- SEO Press/link_building_with_wp-en.pdf | tier E | pages 41 | sha256 `27b5378f29807705ae86e86908d66074316f9914ef0b69438619bd8250fea3f3` | action: skip-by-default +- SEO Press/more-visibility-with-image-seo-by-seopress.pdf | tier E | pages 51 | sha256 `71a1b9e05fc10a429e72f1aea579ed739664440d2d87cdf78bb30e4acd387f9b` | action: skip-by-default +- SEO Press/optimizing-wordpress-speed-en-2.pdf | tier E | pages 48 | sha256 `1e0d721836414e7e966b8bfa2622282547f8b85f4e54ea7d4cac6e586f1bc9ff` | action: skip-by-default +- SEO Press/seopress-2hours-seo-en.pdf | tier E | pages 54 | sha256 `7c98a0697cbe4e2b11e5eecddb2c5b742274858941e72346ef8814ee27526e6b` | action: skip-by-default +- SEO Press/seopress-creating-multilingual-wordpress-site.pdf | tier E | pages 46 | sha256 `2e09fb5ffead2935410b9d0244c7be89e5a0a9e1f20e4bcc89065648a8cccd99` | action: skip-by-default +- SEO Press/seopress-google-analytics-wordpress-en.pdf | tier E | pages 57 | sha256 `6b0d8c4f86c7f2b7690f561dded9d6826d00fe169084abf6ed088b712b70013c` | action: skip-by-default +- SEO Press/seopress-improve-your-ranking-with-on-page-seo.pdf | tier E | pages 42 | sha256 `f3fd25109604af02539ce656a20b50689710ba7f9298667d26c66cc4bfbc0b45` | action: skip-by-default +- SEO Press/seopress-insights-en.pdf | tier E | pages 39 | sha256 `6aec1450a8611164cf4f31cf98120b5afc220ceb828bdb97f4775f061863bdb5` | action: skip-by-default +- SEO Press/seopress-top-seo-tips-managing-multilingual-site.pdf | tier E | pages 9 | sha256 `82d2561dab03451983116aa261b909347982f1ed07e8ba1316ccb9c6143b1c3c` | action: skip-by-default +- SEO Press/wordpress-keyword-en.pdf | tier E | pages 54 | sha256 `be2ea81c03892ff37fe37b676a6f371b9a43cc00d9eaa5e714d9c3ef1da12ea2` | action: skip-by-default +- SEO-Trends-2026-SEJ.pdf | tier A | pages 34 | sha256 `fb75eda39dc31449e77fae22d1872f7d6338239209be5830fe438dcc6ebd14d4` | action: extract-and-consider +- SEO_Tools_2023_F.pdf | tier D | pages 124 | sha256 `5b4a17b1f2eb5e3cb88c748b7aff84b1d78544620be2a5251ee4c8c133abf744` | action: extract-and-consider + +## Source Policy + +- Public prose is freshly written from the Local SEO Knowledge Base, 2025-2026 PDFs, and verified web sources. +- Absolute local paths are intentionally omitted. +- Tier E PDFs are background by default unless a narrow operational gap requires them. +- Contradicted or unverifiable statistics are excluded from public guidance. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/flow-framework.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/flow-framework.md new file mode 100644 index 00000000..bef94e41 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/flow-framework.md @@ -0,0 +1,80 @@ + +--- +title: "FLOW Framework" +description: "FLOW Framework" +updated: 2026-04-25 +tags: + - framework +--- + +![Claude SEO 10-principle methodology: PERCEIVE, ANALYZE, VALIDATE, ACT](../../../assets/framework.svg) + +# FLOW Framework + +## What This Is + +FLOW is a search-and-conversion loop for 2026 discovery. It treats rankings, AI citations, +local visibility, and sales evidence as connected surfaces rather than separate channels. + +FLOW uses four plain stages: Find demand, Leverage distributed evidence, Optimize owned assets for extraction and trust, and Win with pages and measurements that connect discovery to revenue. This page applies that loop to the framework layer. + +## Why It Matters In 2026 + +Ahrefs found a 58% lower average CTR for position-one content when an AI Overview was +present in its December 2025 dataset. + +seoClarity found that 25% of top cited ChatGPT URLs had no Google organic visibility in its +cited-page sample. + +Search is no longer one result page and one click path. A useful SEO system has to survive classic rankings, AI summaries, local packs, business profiles, community references, and sales feedback. The practical goal is not to chase every surface equally; it is to decide which surface can change the next business outcome and then build evidence there. + +## How To Apply + +- Name the search surface before writing: organic result, AI answer, local pack, community discussion, paid landing page, or sales-assisted page. +- Separate observable evidence from assumptions. Claims with numbers must trace to the bibliography or be removed. +- Write from buyer language first, then add entity clarity, internal links, proof, and conversion next steps. +- Review the asset as an AI-readable document: clear headings, direct answers, concise tables where useful, source labels, and no hidden dependence on private examples. + +## Operating Workflow + +1. Define the business outcome before choosing tactics. A page meant to create a qualified call should not be judged only by impressions, and a profile meant to reconcile business facts should not be judged only by post frequency. +2. Inventory the evidence already available: customer language, query data, profile details, reviews, analytics, call notes, sales objections, and any public source that can support a claim. +3. Decide which FLOW stage is blocking progress. If demand language is unclear, return to Find. If the brand is not corroborated off-site, work on Leverage. If the owned asset is hard to extract or trust, Optimize. If traffic exists but business impact is weak, move to Win. +4. Rewrite or rebuild only after the evidence is organized. The strongest assets usually come from a clear source table, not from a blank-page brainstorm. +5. Review the finished work against three readers: the buyer, the search engine, and the AI agent that may summarize or compare the business later. + +## Measurement + +Use a balanced scorecard. Track visibility indicators such as rankings, impressions, local-pack presence, citations, and AI mentions, but connect them to business indicators such as qualified leads, calls, form completions, sales opportunities, assisted conversions, and recurring objections. If the page or profile cannot be measured, add the measurement event before judging performance. + +## Common Failure Modes + +- Publishing a statistic because it sounds familiar instead of because the source was loaded and dated. +- Treating AI visibility as a formatting trick while ignoring brand evidence, entity consistency, and off-site corroboration. +- Writing pages around company preferences instead of buyer questions and decision risk. +- Optimizing for traffic without defining the next qualified action. +- Reusing old examples when a generic or newly created example would be cleaner and more durable. + +## AI Agent Prompt + +```text +You are an SEO strategist using the FLOW model. For the asset named "FLOW Framework", analyze the target audience, search surface, evidence needed, entity facts, conversion goal, and risks. Return: priorities, page or profile changes, source requirements, internal links, measurement plan, and a list of claims that need verification before publication. +``` + +## Quality Bar + +- Public claims use verified sources or stay qualitative. +- Examples are generic or newly created for this repository. +- Private editorial notes are used only to identify candidate concepts, never as public prose. +- The page should make sense to a human reader and to an AI agent that only has this repository. + +## See Also + +- [Start Here](../SKILL.md) +- [Bibliography](bibliography.md) + +## Sources + +- Search Engine Journal, State of SEO 2026 PDF and public landing page, retrieved 2026-04-25. +- Ahrefs, AI Overviews CTR update, retrieved 2026-04-25. +- seoClarity, ChatGPT cited-page analysis, retrieved 2026-04-25. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/flow-prompts.lock b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/flow-prompts.lock new file mode 100644 index 00000000..7d29c24a --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/flow-prompts.lock @@ -0,0 +1,47 @@ +# flow-prompts.lock — SHA-256 baseline for synced FLOW prompts +# Ref: HEAD | format: (sha256sum-compatible) + +1f7e5d60194c252a6b38ba1eb78970cdf5bea2f096563c508bfad36f7e445f75 skills/seo-flow/references/bibliography.md +029c009e0fd5fc77763a530af24a83bf8cf21eb703158317bde8518446af0887 skills/seo-flow/references/flow-framework.md +26e434454595c47c63e3ef5c4c5d975a8a8208ca01887e51ab09a45eb679085a skills/seo-flow/references/prompts/README.md +0bab3257ca8c588ffe6e96adc97d2201fc1fb4cfd5a8674cfeb97a640ab78ce1 skills/seo-flow/references/prompts/find/content-planning-for-topical-relevance-prompt.md +e8d12ec0b02de03de7b0066a1b29b4e5523f49413bb276c3d936ca068f1645b0 skills/seo-flow/references/prompts/find/content-prioritization-prompt.md +3bd3c230f682c65c328324d37dada59a76ca85326bfe97fbf3acf6849e36525d skills/seo-flow/references/prompts/find/keyword-research-prompt.md +18b92580c0de1d0df6a8353efc0fd98864ed9e7090318cd4564cae84f79e2bd1 skills/seo-flow/references/prompts/find/keyword-variations-for-topical-relevance-prompt.md +450d58afe2499f7644f947725fcaaf9463931e09d8fdcb93765d25c6e0750d22 skills/seo-flow/references/prompts/find/prompt-audience-avatar.md +88b5a6aca87c0f5ad12ed0a9cec601c23e944db2ff1014502fe7218064249be4 skills/seo-flow/references/prompts/leverage/backlink-competition-prompt.md +d33e8918c05d99136baf476165a57a94b7cc0c93bf3585d49bb7212d93bb0455 skills/seo-flow/references/prompts/local/ai-homepage-rewrite-prompt.md +65a9876a959b4aba089e4aac9bb078eb2c487726285f0828535b9178f7410dcb skills/seo-flow/references/prompts/local/claude-deep-research-prompt.md +f365d29c9bc3be0aa692a4b0f38515a0d75061ace60603285dbd2aed4a180ec8 skills/seo-flow/references/prompts/local/gbp-categories-prompt.md +80c73c39f7240ba87bdefd19babdde7f15e6dfe0cdebfa490d62dad2c3dc8702 skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-1.md +d3ee5d748597d85cbd15b31a0e72a9d67a6f91d65f0f8a750ff7bd5ad0398f00 skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-2.md +3c1eaca3250b854b025729aee39df6593518595eb6d2ec1f9cc24bc927ae3845 skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-3.md +a82eebb02b5b5b9d2e02fd21f364dae9641aae69e9a8c2ddfd1ddd975d5ea0aa skills/seo-flow/references/prompts/local/gbp-services-prompt.md +82f9d16c7158978c50c7f2ee783d636e6e54c27bde4ae56aa4df0a729710fe6e skills/seo-flow/references/prompts/local/prompt-generating-a-meta-description.md +5db99be445c3d72fdaabf75ca92133981b586d6e48221e8df1bec06233ff62f7 skills/seo-flow/references/prompts/local/prompt-generating-a-title-tag.md +b0000ade4e79a06e65d568e17a06ec98ababae5b33d16f61f1e101dd3f0b5720 skills/seo-flow/references/prompts/local/prompt-rewriting-existing-homepage.md +6e24da4f82b486b614e9ca2b4ae4cd8554865aedd6043218334d9dfe245afed3 skills/seo-flow/references/prompts/local/prompt-rewriting-existing-service-page.md +23b75608644f51981e8421e307a1f9c51497587fe01a846828b9142525830fd0 skills/seo-flow/references/prompts/optimize/ai-detector-test-follow-up-prompt.md +92e0f8e7fded7438ed86ac58fa9f0c66122308e36903eb064125b0a2e8a10f87 skills/seo-flow/references/prompts/optimize/ai-supporting-pages-rewrite-prompt.md +5f8ddce6655b91e3bd23ff0174d0890d46db4c86b2074230793a834c51f87d34 skills/seo-flow/references/prompts/optimize/basic-prompt.md +4427a6ffbe45fbfa397cc3e7bb8ff2cc2d1e4652f2b2ddfff2e3ccd299ae79cc skills/seo-flow/references/prompts/optimize/blog-post-outline-prompt.md +e88b8781e6a1f69cc7043fbdd0b79365d87691daa1d0b910957fe61aa8a9964c skills/seo-flow/references/prompts/optimize/blog-post-writing-prompt.md +ae0f7460bf85ac666af355d4b3960f31a07beb2a009154c2c3c336de45b8afe9 skills/seo-flow/references/prompts/optimize/claude-prompt-1.md +881278d4c5872b2d2f03eef8df21fb1dbee499acab565d039531f96d455528c3 skills/seo-flow/references/prompts/optimize/claude-prompt-2.md +cfe26d1f07bd98f5a98a3e6a825d0127cf7b003519fdfb595c4761393ac143ea skills/seo-flow/references/prompts/optimize/ctr-audit-prompt.md +d35a7f848aab67df85391acf5f6208bdcea6f51bf454a4e87129446bc928f3f0 skills/seo-flow/references/prompts/optimize/follow-up-prompt-1.md +e8e55404737510c63080c93401a00097058eee7ef40f56f77659cccda29cc984 skills/seo-flow/references/prompts/optimize/follow-up-prompt-2.md +454d9b9f684f2dfa54530819e2505361b165d54e3d1fa92a1be61367ac5da072 skills/seo-flow/references/prompts/optimize/follow-up-prompt.md +770b5ba49150b2a48753a7c51d60d3b93c3091fb5aedc24a7c8f41c463517e55 skills/seo-flow/references/prompts/optimize/paa-question-rewording-prompt.md +b58c751c5552592b5e7f0e176c21fb0c509924a7a98bc635e32e1b93e8dff3fd skills/seo-flow/references/prompts/optimize/prompt-core-30-content-audit.md +4e7a894b86b03a20c4b9b06239fe97f224f680c6ab8d68d942a4e546182b7077 skills/seo-flow/references/prompts/optimize/property-content-with-authority-audit-prompt.md +be767e88a2b3b6c9a4bbbc4f2f2611e1606babdf9b18163cab8b5050966048ab skills/seo-flow/references/prompts/optimize/reddit-claude-prompt.md +a7b3f4fe17f7e0b5257b2cb940a00b005c44e21bfdb13de0d889b4a5cbd6fa09 skills/seo-flow/references/prompts/optimize/schema-prompt-1.md +45112ea78038130ff3d29d6e965401d234a4a2a540883e6c625a877defa46e24 skills/seo-flow/references/prompts/optimize/step-1-the-chatgpt-discovery-prompt.md +f08df22ed90c0ba1b7b7f529331309161a886fd2e12bf4ff3ec955bb10fd22ee skills/seo-flow/references/prompts/optimize/step-2-the-follow-up-qualifying-prompt.md +51274ab6e21a62892171c53397f935242f55c3726f3d2a11850985839b047ff4 skills/seo-flow/references/prompts/optimize/technical-audit-prompt.md +0a76f9075c783957d45ab58cec04f4701f01e235a65e9d97ab7b52f7c10f3201 skills/seo-flow/references/prompts/optimize/visibility-follow-up-prompt.md +769684b2895051491a7eed1eb1ff0e0065d2472cc395fee04fc99eed85df83de skills/seo-flow/references/prompts/optimize/visiblity-prompt.md +dbbe1d51ef93bdc1918bfab1b0948a0d87500410ea8d6727f088e5e4f937dadf skills/seo-flow/references/prompts/win/bofu-page-brief-generator.md +1fb96a2a2c0dcb096389992d14fc12738523c94e2559ebd71a46b8264f2049d7 skills/seo-flow/references/prompts/win/conversion-audit-prompt.md +9521283c3578d613a9a25f985d609995d92d284f982d0377160a646563fa7c18 skills/seo-flow/references/prompts/win/dual-surface-content-scorecard.md diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/README.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/README.md new file mode 100644 index 00000000..eb14341c --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/README.md @@ -0,0 +1,52 @@ + + +# Flow Prompt Index + +| Stage | Filename | Title | Description | +|---|---|---|---| +| find | content-planning-for-topical-relevance-prompt.md | Content planning for Topical Relevance Prompt | Content planning for Topical Relevance Prompt | +| find | content-prioritization-prompt.md | Content Prioritization Prompt | Content Prioritization Prompt | +| find | keyword-research-prompt.md | Keyword research prompt | Keyword research prompt | +| find | keyword-variations-for-topical-relevance-prompt.md | Keyword variations for topical relevance prompt | Keyword variations for topical relevance prompt | +| find | prompt-audience-avatar.md | Prompt: Audience Avatar | Prompt: Audience Avatar | +| leverage | backlink-competition-prompt.md | Backlink competition prompt | Backlink competition prompt | +| optimize | ai-detector-test-follow-up-prompt.md | AI detector test follow-up Prompt | AI detector test follow-up Prompt | +| optimize | ai-supporting-pages-rewrite-prompt.md | AI Supporting Pages Rewrite Prompt | AI Supporting Pages Rewrite Prompt | +| optimize | basic-prompt.md | Basic Prompt | Basic Prompt | +| optimize | blog-post-outline-prompt.md | Blog Post Outline Prompt | Blog Post Outline Prompt | +| optimize | blog-post-writing-prompt.md | Blog Post Writing Prompt | Blog Post Writing Prompt | +| optimize | claude-prompt-1.md | Claude Prompt 1 | Claude Prompt 1 | +| optimize | claude-prompt-2.md | Claude Prompt 2 | Claude Prompt 2 | +| optimize | ctr-audit-prompt.md | CTR AUDIT PROMPT | CTR AUDIT PROMPT | +| optimize | follow-up-prompt-1.md | Follow-up Prompt 1 | Follow-up Prompt 1 | +| optimize | follow-up-prompt-2.md | Follow-up Prompt 2 | Follow-up Prompt 2 | +| optimize | follow-up-prompt.md | Follow-up Prompt | Follow-up Prompt | +| optimize | paa-question-rewording-prompt.md | PAA Question Rewording Prompt | PAA Question Rewording Prompt | +| optimize | prompt-core-30-content-audit.md | Prompt: Core 30 Content Audit | Prompt: Core 30 Content Audit | +| optimize | property-content-with-authority-audit-prompt.md | Property content with authority audit prompt | Property content with authority audit prompt | +| optimize | reddit-claude-prompt.md | Reddit Claude Prompt | Reddit Claude Prompt | +| optimize | schema-prompt-1.md | Schema Prompt 1 | Schema Prompt 1 | +| optimize | step-1-the-chatgpt-discovery-prompt.md | Step 1: The ChatGPT Discovery Prompt | Step 1: The ChatGPT Discovery Prompt | +| optimize | step-2-the-follow-up-qualifying-prompt.md | Step 2: The Follow-Up Qualifying Prompt | Step 2: The Follow-Up Qualifying Prompt | +| optimize | technical-audit-prompt.md | Technical Audit Prompt | Technical Audit Prompt | +| optimize | visibility-follow-up-prompt.md | Visibility Follow Up Prompt | Visibility Follow Up Prompt | +| optimize | visiblity-prompt.md | Visiblity Prompt | Visiblity Prompt | +| win | bofu-page-brief-generator.md | BOFU Page Brief Generator | BOFU Page Brief Generator | +| win | conversion-audit-prompt.md | Conversion Audit Prompt | Conversion Audit Prompt | +| win | dual-surface-content-scorecard.md | Dual-Surface Content Scorecard | Dual-Surface Content Scorecard | +| local | ai-homepage-rewrite-prompt.md | AI Homepage Rewrite Prompt | AI Homepage Rewrite Prompt | +| local | claude-deep-research-prompt.md | Claude 'Deep Research' Prompt | Claude 'Deep Research' Prompt | +| local | gbp-categories-prompt.md | GBP Categories Prompt | GBP Categories Prompt | +| local | gbp-description-claude-prompt-1.md | GBP Description Claude Prompt 1 | GBP Description Claude Prompt 1 | +| local | gbp-description-claude-prompt-2.md | GBP Description Claude Prompt 2 | GBP Description Claude Prompt 2 | +| local | gbp-description-claude-prompt-3.md | GBP Description Claude Prompt 3 | GBP Description Claude Prompt 3 | +| local | gbp-services-prompt.md | GBP Services Prompt | GBP Services Prompt | +| local | prompt-generating-a-meta-description.md | Prompt: Generating a Meta Description | Prompt: Generating a Meta Description | +| local | prompt-generating-a-title-tag.md | Prompt: Generating a Title Tag | Prompt: Generating a Title Tag | +| local | prompt-rewriting-existing-homepage.md | Prompt: Rewriting Existing Homepage | Prompt: Rewriting Existing Homepage | +| local | prompt-rewriting-existing-service-page.md | Prompt : Rewriting Existing Service Page | Prompt : Rewriting Existing Service Page | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/content-planning-for-topical-relevance-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/content-planning-for-topical-relevance-prompt.md new file mode 100644 index 00000000..0dce88fe --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/content-planning-for-topical-relevance-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Content planning for Topical Relevance Prompt" +description: "Content planning for Topical Relevance Prompt" +updated: 2026-04-25 +tags: + - prompts + - find +--- + +# Content planning for Topical Relevance Prompt + +## Use This When + +Use this prompt when you need a structured find deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a find deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/content-prioritization-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/content-prioritization-prompt.md new file mode 100644 index 00000000..4928e2d6 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/content-prioritization-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Content Prioritization Prompt" +description: "Content Prioritization Prompt" +updated: 2026-04-25 +tags: + - prompts + - find +--- + +# Content Prioritization Prompt + +## Use This When + +Use this prompt when you need a structured find deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a find deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/keyword-research-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/keyword-research-prompt.md new file mode 100644 index 00000000..97bc8aab --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/keyword-research-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Keyword research prompt" +description: "Keyword research prompt" +updated: 2026-04-25 +tags: + - prompts + - find +--- + +# Keyword research prompt + +## Use This When + +Use this prompt when you need a structured find deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a find deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/keyword-variations-for-topical-relevance-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/keyword-variations-for-topical-relevance-prompt.md new file mode 100644 index 00000000..94fde2b8 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/keyword-variations-for-topical-relevance-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Keyword variations for topical relevance prompt" +description: "Keyword variations for topical relevance prompt" +updated: 2026-04-25 +tags: + - prompts + - find +--- + +# Keyword variations for topical relevance prompt + +## Use This When + +Use this prompt when you need a structured find deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a find deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/prompt-audience-avatar.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/prompt-audience-avatar.md new file mode 100644 index 00000000..13e92f69 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/find/prompt-audience-avatar.md @@ -0,0 +1,70 @@ + +--- +title: "Prompt: Audience Avatar" +description: "Prompt: Audience Avatar" +updated: 2026-04-25 +tags: + - prompts + - find +--- + +# Prompt: Audience Avatar + +## Use This When + +Use this prompt when you need a structured find deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a find deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/leverage/backlink-competition-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/leverage/backlink-competition-prompt.md new file mode 100644 index 00000000..d637b0b1 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/leverage/backlink-competition-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Backlink competition prompt" +description: "Backlink competition prompt" +updated: 2026-04-25 +tags: + - prompts + - leverage +--- + +# Backlink competition prompt + +## Use This When + +Use this prompt when you need a structured leverage deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a leverage deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/ai-homepage-rewrite-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/ai-homepage-rewrite-prompt.md new file mode 100644 index 00000000..1e45d535 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/ai-homepage-rewrite-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "AI Homepage Rewrite Prompt" +description: "AI Homepage Rewrite Prompt" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# AI Homepage Rewrite Prompt + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/claude-deep-research-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/claude-deep-research-prompt.md new file mode 100644 index 00000000..eadb9069 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/claude-deep-research-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Claude 'Deep Research' Prompt" +description: "Claude 'Deep Research' Prompt" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# Claude 'Deep Research' Prompt + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-categories-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-categories-prompt.md new file mode 100644 index 00000000..bd8fb8e3 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-categories-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "GBP Categories Prompt" +description: "GBP Categories Prompt" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# GBP Categories Prompt + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-1.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-1.md new file mode 100644 index 00000000..be043701 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-1.md @@ -0,0 +1,70 @@ + +--- +title: "GBP Description Claude Prompt 1" +description: "GBP Description Claude Prompt 1" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# GBP Description Claude Prompt 1 + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-2.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-2.md new file mode 100644 index 00000000..e1d4b6a2 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-2.md @@ -0,0 +1,70 @@ + +--- +title: "GBP Description Claude Prompt 2" +description: "GBP Description Claude Prompt 2" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# GBP Description Claude Prompt 2 + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-3.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-3.md new file mode 100644 index 00000000..e53e6244 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-description-claude-prompt-3.md @@ -0,0 +1,70 @@ + +--- +title: "GBP Description Claude Prompt 3" +description: "GBP Description Claude Prompt 3" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# GBP Description Claude Prompt 3 + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-services-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-services-prompt.md new file mode 100644 index 00000000..120706ad --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/gbp-services-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "GBP Services Prompt" +description: "GBP Services Prompt" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# GBP Services Prompt + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-generating-a-meta-description.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-generating-a-meta-description.md new file mode 100644 index 00000000..e071e725 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-generating-a-meta-description.md @@ -0,0 +1,70 @@ + +--- +title: "Prompt: Generating a Meta Description" +description: "Prompt: Generating a Meta Description" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# Prompt: Generating a Meta Description + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-generating-a-title-tag.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-generating-a-title-tag.md new file mode 100644 index 00000000..b0a7ce2e --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-generating-a-title-tag.md @@ -0,0 +1,70 @@ + +--- +title: "Prompt: Generating a Title Tag" +description: "Prompt: Generating a Title Tag" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# Prompt: Generating a Title Tag + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-rewriting-existing-homepage.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-rewriting-existing-homepage.md new file mode 100644 index 00000000..84a3d8cd --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-rewriting-existing-homepage.md @@ -0,0 +1,70 @@ + +--- +title: "Prompt: Rewriting Existing Homepage" +description: "Prompt: Rewriting Existing Homepage" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# Prompt: Rewriting Existing Homepage + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-rewriting-existing-service-page.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-rewriting-existing-service-page.md new file mode 100644 index 00000000..e50b960c --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/local/prompt-rewriting-existing-service-page.md @@ -0,0 +1,70 @@ + +--- +title: "Prompt : Rewriting Existing Service Page" +description: "Prompt : Rewriting Existing Service Page" +updated: 2026-04-25 +tags: + - prompts + - local +--- + +# Prompt : Rewriting Existing Service Page + +## Use This When + +Use this prompt when you need a structured local deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a local deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ai-detector-test-follow-up-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ai-detector-test-follow-up-prompt.md new file mode 100644 index 00000000..9dc0c6cf --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ai-detector-test-follow-up-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "AI detector test follow-up Prompt" +description: "AI detector test follow-up Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# AI detector test follow-up Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ai-supporting-pages-rewrite-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ai-supporting-pages-rewrite-prompt.md new file mode 100644 index 00000000..c13466aa --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ai-supporting-pages-rewrite-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "AI Supporting Pages Rewrite Prompt" +description: "AI Supporting Pages Rewrite Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# AI Supporting Pages Rewrite Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/basic-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/basic-prompt.md new file mode 100644 index 00000000..fa1302d5 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/basic-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Basic Prompt" +description: "Basic Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Basic Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/blog-post-outline-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/blog-post-outline-prompt.md new file mode 100644 index 00000000..cf93d697 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/blog-post-outline-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Blog Post Outline Prompt" +description: "Blog Post Outline Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Blog Post Outline Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/blog-post-writing-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/blog-post-writing-prompt.md new file mode 100644 index 00000000..3ff13932 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/blog-post-writing-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Blog Post Writing Prompt" +description: "Blog Post Writing Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Blog Post Writing Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/claude-prompt-1.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/claude-prompt-1.md new file mode 100644 index 00000000..efbfa455 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/claude-prompt-1.md @@ -0,0 +1,70 @@ + +--- +title: "Claude Prompt 1" +description: "Claude Prompt 1" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Claude Prompt 1 + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/claude-prompt-2.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/claude-prompt-2.md new file mode 100644 index 00000000..f90cab21 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/claude-prompt-2.md @@ -0,0 +1,70 @@ + +--- +title: "Claude Prompt 2" +description: "Claude Prompt 2" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Claude Prompt 2 + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ctr-audit-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ctr-audit-prompt.md new file mode 100644 index 00000000..9d7e8db4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/ctr-audit-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "CTR AUDIT PROMPT" +description: "CTR AUDIT PROMPT" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# CTR AUDIT PROMPT + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt-1.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt-1.md new file mode 100644 index 00000000..cccb5e70 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt-1.md @@ -0,0 +1,70 @@ + +--- +title: "Follow-up Prompt 1" +description: "Follow-up Prompt 1" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Follow-up Prompt 1 + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt-2.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt-2.md new file mode 100644 index 00000000..f7d32e77 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt-2.md @@ -0,0 +1,70 @@ + +--- +title: "Follow-up Prompt 2" +description: "Follow-up Prompt 2" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Follow-up Prompt 2 + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt.md new file mode 100644 index 00000000..3e931d13 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/follow-up-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Follow-up Prompt" +description: "Follow-up Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Follow-up Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/paa-question-rewording-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/paa-question-rewording-prompt.md new file mode 100644 index 00000000..42f77e38 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/paa-question-rewording-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "PAA Question Rewording Prompt" +description: "PAA Question Rewording Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# PAA Question Rewording Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/prompt-core-30-content-audit.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/prompt-core-30-content-audit.md new file mode 100644 index 00000000..0e310a2c --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/prompt-core-30-content-audit.md @@ -0,0 +1,70 @@ + +--- +title: "Prompt: Core 30 Content Audit" +description: "Prompt: Core 30 Content Audit" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Prompt: Core 30 Content Audit + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/property-content-with-authority-audit-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/property-content-with-authority-audit-prompt.md new file mode 100644 index 00000000..b6aafafa --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/property-content-with-authority-audit-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Property content with authority audit prompt" +description: "Property content with authority audit prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Property content with authority audit prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/reddit-claude-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/reddit-claude-prompt.md new file mode 100644 index 00000000..77bec325 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/reddit-claude-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Reddit Claude Prompt" +description: "Reddit Claude Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Reddit Claude Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/schema-prompt-1.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/schema-prompt-1.md new file mode 100644 index 00000000..76d47e31 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/schema-prompt-1.md @@ -0,0 +1,70 @@ + +--- +title: "Schema Prompt 1" +description: "Schema Prompt 1" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Schema Prompt 1 + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/step-1-the-chatgpt-discovery-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/step-1-the-chatgpt-discovery-prompt.md new file mode 100644 index 00000000..c6a3c33d --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/step-1-the-chatgpt-discovery-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Step 1: The ChatGPT Discovery Prompt" +description: "Step 1: The ChatGPT Discovery Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Step 1: The ChatGPT Discovery Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/step-2-the-follow-up-qualifying-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/step-2-the-follow-up-qualifying-prompt.md new file mode 100644 index 00000000..108bee0a --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/step-2-the-follow-up-qualifying-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Step 2: The Follow-Up Qualifying Prompt" +description: "Step 2: The Follow-Up Qualifying Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Step 2: The Follow-Up Qualifying Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/technical-audit-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/technical-audit-prompt.md new file mode 100644 index 00000000..d6591eac --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/technical-audit-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Technical Audit Prompt" +description: "Technical Audit Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Technical Audit Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/visibility-follow-up-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/visibility-follow-up-prompt.md new file mode 100644 index 00000000..e85b9e4e --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/visibility-follow-up-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Visibility Follow Up Prompt" +description: "Visibility Follow Up Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Visibility Follow Up Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/visiblity-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/visiblity-prompt.md new file mode 100644 index 00000000..c86fca17 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/optimize/visiblity-prompt.md @@ -0,0 +1,70 @@ + +--- +title: "Visiblity Prompt" +description: "Visiblity Prompt" +updated: 2026-04-25 +tags: + - prompts + - optimize +--- + +# Visiblity Prompt + +## Use This When + +Use this prompt when you need a structured optimize deliverable and want the model to separate observations, assumptions, recommended actions, and claims that need verification. + +## AI Compatibility + +Works with long-context reasoning models. For smaller models, provide narrower inputs and ask for one output section at a time. + +## Inputs + +- Business or website name. +- Target page, profile, query set, or campaign. +- Audience and geography where relevant. +- Existing evidence: analytics, search results, calls, reviews, profile facts, or source notes. +- Constraints, exclusions, and required sources. + +## Prompt + +```text +Act as a senior SEO strategist using the FLOW model. + +Task: create a optimize deliverable for: [BUSINESS OR ASSET]. + +Use only the supplied inputs and clearly label any assumption. Do not invent statistics. Do not reuse private examples. Build the answer around: +1. Searcher or buyer intent. +2. Evidence available now. +3. Gaps that block trust, extraction, or conversion. +4. Recommended changes in priority order. +5. Measurement events and review cadence. +6. Claims that require source verification before publication. + +Return a concise working document the team can execute. +``` + +## Output + +- Executive summary. +- Priority table. +- Recommended copy, structure, or audit findings. +- Evidence needed. +- Measurement plan. +- Verification checklist. + +## Example + +Input: a local service page with weak proof and inconsistent profile details. + +Expected output: a prioritized rewrite brief, facts to reconcile, internal links to add, and the conversion event to measure. + +## See Also + +- [Prompt Library](../README.md) +- [FLOW Framework](../../flow-framework.md) +- [Bibliography](../../bibliography.md) + +## Source Note + +Derived from the Local SEO Knowledge Base structure and rewritten for public use with the repository evidence standard. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/bofu-page-brief-generator.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/bofu-page-brief-generator.md new file mode 100644 index 00000000..c95ae8ab --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/bofu-page-brief-generator.md @@ -0,0 +1,69 @@ + +--- +title: "BOFU Page Brief Generator" +description: "BOFU Page Brief Generator" +updated: 2026-04-25 +tags: + - prompts + - win +--- + +# BOFU Page Brief Generator + +## Use This When + +Use this when you need a bottom-funnel page brief for a service, product, location, comparison, pricing, demo, or lead-capture page. + +## AI Compatibility + +Claude, GPT, Gemini, and other long-context models. Works best with current customer language and conversion evidence. + +## Inputs + +- Offer, service, or product. +- Target audience and segment. +- Buying-stage intent. +- Known objections or hesitation points. +- Customer language from calls, chats, reviews, or surveys. +- Conversion goal. +- Required proof points. +- Existing page text, if any. + +## Prompt + +```text +Create a bottom-funnel page brief for [offer] targeting [audience]. + +Use only the inputs provided. Build the brief around what this audience needs to decide. + +Analyze: +1. The immediate problem the visitor is trying to solve. +2. The decision factors they likely need before converting. +3. Objections, hesitation points, and missing clarity. +4. Customer-language phrases that should appear naturally. +5. Proof needed to support trust. +6. CTA angle and page sections needed to reduce friction. + +Return: page goal, search/conversion intent, primary audience, buyer questions, objections, recommended H1, section outline, proof points, CTA strategy, FAQ topics, and tracking notes for form, call, chat, and qualified-lead measurement. Flag missing inputs. +``` + +## Output + +- A structured Win-stage working document. +- Prioritized recommendations. +- Evidence and measurement gaps. +- Claims or assumptions that require verification. + +## Example + +Input: commercial repair page for facility managers with objections around response time, weekend availability, and pricing clarity. Output: a brief emphasizing urgency, service coverage, decision criteria, proof, FAQs, and call/form tracking. + +## See Also + +- [Prompt Library](../README.md) +- BOFU and Conversion Content +- Dual-Surface Scorecard + +## Source Note + +Derived from SEJ State of SEO 2026, SEJ B2B Lead Generation, and CallRail/SEJ Better Leads More Sales 2025. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/conversion-audit-prompt.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/conversion-audit-prompt.md new file mode 100644 index 00000000..6303eea6 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/conversion-audit-prompt.md @@ -0,0 +1,68 @@ + +--- +title: "Conversion Audit Prompt" +description: "Conversion Audit Prompt" +updated: 2026-04-25 +tags: + - prompts + - win +--- + +# Conversion Audit Prompt + +## Use This When + +Use this when a page, campaign, or funnel gets traffic but produces weak leads, low conversion rate, unclear attribution, or poor sales follow-up quality. + +## AI Compatibility + +Claude, GPT, Gemini, and other long-context models. Works best with current customer language and conversion evidence. + +## Inputs + +- Page or funnel copy. +- Traffic sources. +- Conversion goal. +- Analytics or conversion data. +- Call, chat, or form transcript samples. +- Known objections. +- Ad copy or campaign promise. +- Sales feedback, if available. + +## Prompt + +```text +Audit this conversion path for lead quality, friction, and measurement gaps. + +Use the supplied page, campaign, and first-party conversation data. Identify: +1. Where visitor expectations may not match the page or offer. +2. Common objections and hesitation points. +3. Missing decision-making information. +4. Language mismatches between customers and the page. +5. CTA friction. +6. Tracking gaps across form, phone, chat, and offline outcomes. +7. Whether reporting connects to qualified leads or sales, not only traffic. + +Return an executive summary, top blockers, lead-quality risks, messaging fixes, page/content fixes, tracking fixes, first-party data to collect next, and a ranked test backlog. Do not recommend more spend until content, offer clarity, and measurement gaps are assessed. +``` + +## Output + +- A structured Win-stage working document. +- Prioritized recommendations. +- Evidence and measurement gaps. +- Claims or assumptions that require verification. + +## Example + +Input: paid search landing page with many calls but few booked appointments. Output: an audit of pricing clarity, qualification, phone attribution, repeated objections, CTA mismatch, and test priorities. + +## See Also + +- [Prompt Library](../README.md) +- BOFU and Conversion Content +- Dual-Surface Scorecard + +## Source Note + +Derived from PPC Trends 2026, CallRail/SEJ Better Leads More Sales 2025, and SEJ State of SEO 2026. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/dual-surface-content-scorecard.md b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/dual-surface-content-scorecard.md new file mode 100644 index 00000000..17b95d40 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-flow/references/prompts/win/dual-surface-content-scorecard.md @@ -0,0 +1,67 @@ + +--- +title: "Dual-Surface Content Scorecard" +description: "Dual-Surface Content Scorecard" +updated: 2026-04-25 +tags: + - prompts + - win +--- + +# Dual-Surface Content Scorecard + +## Use This When + +Use this when you need to judge whether a page can perform in traditional search and AI-assisted discovery while still supporting conversion. + +## AI Compatibility + +Claude, GPT, Gemini, and other long-context models. Works best with current customer language and conversion evidence. + +## Inputs + +- Page copy. +- Target queries or topics. +- Intended conversion goal. +- Audience segment. +- Known first-party insights. +- Performance data, if available. +- Competing page examples, optional. + +## Prompt + +```text +Score this content for two discovery surfaces: traditional search and AI-assisted answer environments. + +Evaluate: +1. Original usefulness and specificity. +2. Alignment with audience needs and decision stage. +3. Evidence, examples, data, or firsthand insight. +4. Clear answers to buyer questions. +5. Conversion support: CTA, proof, objection handling, and next step. +6. Refresh or update need. +7. Measurement readiness: traffic, engagement, qualified leads, sales conversions, and ROI indicators. + +Return traditional search score, AI-assisted discovery score, conversion-readiness score, evidence strengths, gaps, risks, recommended updates, and the highest-impact next three actions. Use business-impact language, not traffic-only language. +``` + +## Output + +- A structured Win-stage working document. +- Prioritized recommendations. +- Evidence and measurement gaps. +- Claims or assumptions that require verification. + +## Example + +Input: existing service page with traffic but low form submissions. Output: scores showing whether the page lacks buyer proof, direct answers, customer language, CTA clarity, or measurable conversion paths. + +## See Also + +- [Prompt Library](../README.md) +- BOFU and Conversion Content +- Dual-Surface Scorecard + +## Source Note + +Derived from SEJ State of SEO 2026, verified AI-search evidence, and SEJ B2B Lead Generation. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-geo/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-geo/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-geo/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-geo/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-geo/SKILL.md new file mode 100644 index 00000000..bc916e39 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-geo/SKILL.md @@ -0,0 +1,286 @@ +--- +name: seo-geo +description: > + Optimize content for AI Overviews (formerly SGE), ChatGPT web search, + Perplexity, and other AI-powered search experiences. Generative Engine + Optimization (GEO) analysis including brand mention signals, AI crawler + accessibility, llms.txt compliance, passage-level citability scoring, and + platform-specific optimization. Use when user says "AI Overviews", "SGE", + "GEO", "AI search", "LLM optimization", "Perplexity", "AI citations", + "ChatGPT search", or "AI visibility". +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# AI Search / GEO Optimization (May 2026) + +## Primary Source: Google's AI Optimization Guide + +Google's official position, published under Search Central docs: + +> "Optimizing for generative AI search is **still SEO** from Google's +> perspective. AEO and GEO are rebranded labels for the same work." + +Read `references/google-ai-optimization-guide.md` for the full synthesis, +myth-busting list (`llms.txt`, chunking, AI-rephrasing, mention-farming — +all rejected by Google as ineffective), and the Who/How/Why test for +content quality. + +Audits should frame GEO findings as **SEO fundamentals applied to AI-search +surfaces**, not as a separate optimization discipline. When community +recommendations contradict Google's primary source, defer to Google and note +the contradiction in the report. + +## Key Statistics + +| Metric | Value | Source | +|--------|-------|--------| +| AI Overviews reach | 1.5 billion users/month across 200+ countries | Google | +| AI Overviews query coverage | 50%+ of all queries | Industry data | +| AI Mode monthly users | 1B+ (surpassed May 2026) | Google | +| AI Mode model | Gemini 3.5 Flash (default, global, since I/O 2026) | Google | +| AI-referred sessions growth | 527% (Jan-May 2025) | SparkToro | +| ChatGPT weekly active users | 900 million | OpenAI | +| Perplexity monthly queries | 500+ million | Perplexity | + +## Critical Insight: Brand Mentions > Backlinks + +**Brand mentions correlate 3x more strongly with AI visibility than backlinks.** +(Ahrefs December 2025 study of 75,000 brands) + +| Signal | Correlation with AI Citations | +|--------|------------------------------| +| YouTube mentions | ~0.737 (strongest) | +| Reddit mentions | High | +| Wikipedia presence | High | +| LinkedIn presence | Moderate | +| Domain Rating (backlinks) | ~0.266 (weak) | + +**Only 11% of domains** are cited by both ChatGPT and Google AI Overviews for the same query, so platform-specific optimization is essential. + +--- + +## GEO Analysis Criteria (Updated) + +### 1. Citability Score (25%) + +**Optimal passage length: 134-167 words** for AI citation. And **~44% of AI +citations come from the first 30% of a page** (SE Ranking study) — front-load +your most citable, self-contained answer rather than burying it below the fold. + +**Strong signals:** +- Clear, quotable sentences with specific facts/statistics +- Self-contained answer blocks (can be extracted without context) +- Direct answer in first 40-60 words of section +- Claims attributed with specific sources +- Definitions following "X is..." or "X refers to..." patterns +- Unique data points not found elsewhere + +**Weak signals:** +- Vague, general statements +- Opinion without evidence +- Buried conclusions +- No specific data points + +### 2. Structural Readability (20%) + +**92% of AI Overview citations come from top-10 ranking pages**, but 47% come from pages ranking below position 5, demonstrating different selection logic. + +**Strong signals:** +- Clean H1->H2->H3 heading hierarchy +- Question-based headings (matches query patterns) +- Short paragraphs (2-4 sentences) +- Tables for comparative data +- Ordered/unordered lists for step-by-step or multi-item content +- FAQ sections with clear Q&A format + +**Weak signals:** +- Wall of text with no structure +- Inconsistent heading hierarchy +- No lists or tables +- Information buried in paragraphs + +### 3. Multi-Modal Content (15%) + +Content with multi-modal elements sees **156% higher selection rates**. + +**Check for:** +- Text + relevant images +- Video content (embedded or linked) +- Infographics and charts +- Interactive elements (calculators, tools) +- Structured data supporting media + +### 4. Authority & Brand Signals (20%) + +**Strong signals:** +- Author byline with credentials +- Publication date and last-updated date +- **Recency** — content under 3 months old is ~3x more likely to be cited in AI answers; pages left stale 6+ months lose citation eligibility (SE Ranking, 1.3M-citation study). A scheduled refresh program is one of the highest-leverage GEO plays. +- Citations to primary sources (studies, official docs, data) +- Organization credentials and affiliations +- Expert quotes with attribution +- Entity presence in Wikipedia, Wikidata +- Mentions on Reddit, YouTube, LinkedIn + +**Weak signals:** +- Anonymous authorship +- No dates +- No sources cited +- No brand presence across platforms + +### 5. Technical Accessibility (20%) + +**AI crawlers do NOT execute JavaScript.** Server-side rendering is critical. + +**Check for:** +- Server-side rendering (SSR) vs client-only content +- AI crawler access in robots.txt +- llms.txt file presence and configuration +- RSL 1.0 licensing terms + +--- + +## AI Crawler Detection + +Check `robots.txt` for these AI crawlers: + +| Crawler | Owner | Purpose | +|---------|-------|---------| +| GPTBot | OpenAI | ChatGPT web search | +| OAI-SearchBot | OpenAI | OpenAI search features | +| ChatGPT-User | OpenAI | ChatGPT browsing | +| ClaudeBot | Anthropic | Claude web features | +| PerplexityBot | Perplexity | Perplexity AI search | +| CCBot | Common Crawl | Training data (often blocked) | +| anthropic-ai | Anthropic | Claude training | +| Bytespider | ByteDance | TikTok/Douyin AI | +| cohere-ai | Cohere | Cohere models | + +**Recommendation:** Allow GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot for AI search visibility. Block CCBot and training crawlers if desired. + +--- + +## llms.txt Standard + +Read `references/llmstxt-evidence.md` for the primary-source evidence (Mueller, Illyes, SE Ranking 300k-domain study, OtterlyAI server-log audit) on why `/llms.txt` is not currently a citation lever for major AI search systems. claude-seo reports presence but assigns no citation-ranking weight. + +The emerging **llms.txt** standard provides AI crawlers with structured content guidance. + +**Location:** `/llms.txt` (root of domain) + +**Format:** +``` +# Title of site +> Brief description + +## Main sections +- [Page title](url): Description +- [Another page](url): Description + +## Optional: Key facts +- Fact 1 +- Fact 2 +``` + +**Check for:** +- Presence of `/llms.txt` +- Structured content guidance +- Key page highlights +- Contact/authority information + +--- + +## RSL 1.0 (Really Simple Licensing) + +New standard (December 2025) for machine-readable AI licensing terms. + +**Backed by:** Reddit, Yahoo, Medium, Quora, Cloudflare, Akamai, Creative Commons + +**Check for:** RSL implementation and appropriate licensing terms. + +--- + +## Platform-Specific Optimization + +| Platform | Key Citation Sources | Optimization Focus | +|----------|---------------------|-------------------| +| **Google AI Overviews** | Strongly ranking-correlated — cites pages that already rank well | Traditional SEO + passage optimization | +| **Google AI Mode** (Gemini 3.5 Flash) | Weakly ranking-correlated; broader pool (~9 domains cited/query, Ahrefs) | Distinct surface: freshness, entity authority, citable passages beyond position 5 | +| **ChatGPT** | Wikipedia (47.9%), Reddit (11.3%) | Entity presence, authoritative sources | +| **Perplexity** | Reddit (46.7%), Wikipedia | Community validation, discussions | +| **Bing Copilot** | Bing index, authoritative sites | Bing SEO, IndexNow | + +> **Two Google citation engines, not one.** AI Mode and AI Overviews reach the +> same conclusion ~86% of the time but cite the same URLs only **13.7%** of the +> time (Ahrefs study, 540K query pairs). Treat them as separate surfaces: ranking +> well in classic Search feeds AI Overviews, but AI Mode draws from a broader pool +> where freshness and entity authority outweigh raw position. Score both. + +--- + +## Output + +Generate `GEO-ANALYSIS.md` with: + +1. **GEO Readiness Score: XX/100** +2. **Platform breakdown** (Google AIO, ChatGPT, Perplexity scores) +3. **AI Crawler Access Status** (which crawlers allowed/blocked) +4. **llms.txt Status** (present, missing, recommendations) +5. **Brand Mention Analysis** (presence on Wikipedia, Reddit, YouTube, LinkedIn) +6. **Passage-Level Citability** (optimal 134-167 word blocks identified) +7. **Server-Side Rendering Check** (JavaScript dependency analysis) +8. **Top 5 Highest-Impact Changes** +9. **Schema Recommendations** (for AI discoverability) +10. **Content Reformatting Suggestions** (specific passages to rewrite) + +--- + +## Quick Wins + +1. Add "What is [topic]?" definition in first 60 words +2. Create 134-167 word self-contained answer blocks +3. Add question-based H2/H3 headings +4. Include specific statistics with sources +5. Add publication/update dates +6. Implement Person schema for authors +7. Allow key AI crawlers in robots.txt + +## Medium Effort + +1. Create `/llms.txt` file +2. Add author bio with credentials + Wikipedia/LinkedIn links +3. Ensure server-side rendering for key content +4. Build entity presence on Reddit, YouTube +5. Add comparison tables with data +6. Implement FAQ sections (structured, not schema for commercial sites) + +## High Impact + +1. Create original research/surveys (unique citability) +2. Build Wikipedia presence for brand/key people +3. Establish YouTube channel with content mentions +4. Implement comprehensive entity linking (sameAs across platforms) +5. Develop unique tools or calculators + +## DataForSEO Integration (Optional) + +If DataForSEO credentials or optional tools are available, use direct DataForSEO calls to check what ChatGPT web search returns for target queries (real GEO visibility check) and to run LLM mention tracking across AI platforms. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site content. Suggest the user verify the URL and try again. | +| AI crawlers blocked by robots.txt | Report exactly which crawlers are blocked and which are allowed. Provide specific robots.txt directives to add for enabling AI search visibility. | +| No llms.txt found | Note the absence and provide a ready-to-use llms.txt template based on the site's content structure. | +| No structured data detected | Report the gap and provide specific schema recommendations (Article, Organization, Person) for improving AI discoverability. | + +## FLOW Framework Integration + +For prompt-guided AI content optimization, use `/seo flow optimize ` — FLOW's 21 optimize-stage prompts complement GEO's citability and structure analysis with evidence-led AI prompts. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-geo/references/google-ai-optimization-guide.md b/plugins/avalonreset/seo-dungeon/skills/seo-geo/references/google-ai-optimization-guide.md new file mode 100644 index 00000000..adea8baf --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-geo/references/google-ai-optimization-guide.md @@ -0,0 +1,125 @@ +# Google AI Optimization Guide — primary-source synthesis (May 2026) + +Google published a dedicated **AI optimization guide** under Search Central +docs. Its position is the most-cited primary source for how AI Overviews and +AI Mode interact with Search ranking. Every claude-seo audit that touches GEO +should treat this doc as the canonical reference and reject community claims +that contradict it. + +**Primary source:** +https://developers.google.com/search/docs/fundamentals/ai-optimization-guide + +## TL;DR + +> "Optimizing for generative AI search is **still SEO** from Google's +> perspective. AEO and GEO are rebranded labels for the same work." +> — Google, AI optimization guide + +AI Overviews and AI Mode are grounded in the same ranking and quality systems +as classic Search. Two AI techniques layer on top: + +1. **RAG / grounding** — retrieves indexed pages, generates a response with + clickable source links. +2. **Query fan-out** — issues multiple related sub-queries and pulls in + additional results before answering. + +**Eligibility floor:** a page must be **indexed and eligible to be shown with +a snippet in Google Search** to appear in any AI feature. There is no separate +"AI index". Everything that follows is SEO fundamentals applied through this +lens. + +## The myth-busting section (most important) + +Google explicitly says you **do NOT need to**: + +| Claim Google rejects | Source | +|---|---| +| Create `llms.txt` or AI-specific markup files | AI optimization guide §"Myths" | +| "Chunk" your content into small pieces for AI | Same | +| Rewrite content for AI with specific phrasings or long-tail keyword variations | Same | +| Chase inauthentic mentions across blogs / forums / videos | Same | +| Over-invest in structured data specifically for AI features | Same | + +What **does** matter, per Google: unique, non-commodity, first-hand content. +Their example contrasts "7 Tips for First-Time Homebuyers" (commodity) with +"Why We Waived the Inspection & Saved Money: A Look Inside the Sewer Line" +(lived experience). + +> **Cross-reference:** the llms.txt myth is independently confirmed by +> [[llmstxt-evidence]] (Mueller, Illyes, SE Ranking 300k-domain study, +> OtterlyAI server-log audit). Both files must stay aligned. + +## The "creating helpful content" companion guide + +The AI optimization guide links to Google's E-E-A-T guidance: + +**Primary source:** +https://developers.google.com/search/docs/fundamentals/creating-helpful-content + +Key actionable test — **Who / How / Why**: + +- **Who** created it — bylines expected where readers expect them; author + background pages required for YMYL. +- **How** it was created — especially for AI-assisted content; disclose + process where readers would reasonably ask. +- **Why** it exists — "to help people," not "to attract search clicks." + +YMYL ("Your Money or Your Life") topics get extra weight: health, finance, +safety. Sept 2025 QRG expanded YMYL to include political / social topics. + +Google's listed warning signs to self-audit against: + +- Writing to a target word count (there isn't one) +- Entering niches with no expertise just for traffic +- Faking publication-date freshness +- Mass content churn for "freshness" signals + +## AI content policy + +**Primary source:** +https://developers.google.com/search/blog/2023/02/google-search-and-ai-content +(plus the Search Essentials spam policies) + +Generative AI content is fine if it meets Search Essentials. It crosses into +spam when used to **scale low-value pages** (QRG §4.6.5 scaled content abuse, +§4.6.6 low-effort main content). + +Two operational requirements with concrete enforcement surfaces: + +1. **Merchant Center — AI-generated product images:** must carry IPTC + `DigitalSourceType: TrainedAlgorithmicMedia` metadata. See + `skills/seo-images/SKILL.md` for the audit + injection pattern. +2. **AI-generated product titles and descriptions:** must be separately + specified and labeled as AI-generated in the merchant feed. + +## Forward-looking: agent-friendly pages and WebMCP + +The AI optimization guide pivots near the end to **AI agents** — not just +summarizers. Agents interact with sites through three channels: screenshots +plus a vision model, raw HTML/DOM, and the browser accessibility tree. + +Full audit criteria: `skills/seo-technical/references/agent-friendly-pages.md`. + +The guide also name-drops **WebMCP** (proposed standard for direct +site↔agent interaction) and **UCP** (Universal Commerce Protocol — Google + +Shopify + Etsy + Walmart + Visa/Mastercard). UCP audit criteria: +`skills/seo-ecommerce/references/ucp-universal-commerce-protocol.md`. + +## How claude-seo treats this guide + +1. `seo-geo` audits cite this URL as the authoritative source whenever the + user asks about AEO/GEO frameworks. +2. The myth-busting list above gates community-sourced AI-SEO recommendations + — if a recommendation contradicts Google's stated position, flag it. +3. Where a third-party claim and Google contradict, claude-seo defers to + Google and notes the contradiction explicitly. +4. `seo-ecommerce` and `seo-images` enforce the two operational requirements + above for sites using AI to generate product content. + +## Last verified + +2026-05-18. Re-check the source doc each quarter. Update this file whenever: + +- Google publishes new myth-busting / clarification. +- Any of the linked policy docs revise eligibility or enforcement language. +- The UCP / WebMCP standards advance (currently early stage). diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-geo/references/llmstxt-evidence.md b/plugins/avalonreset/seo-dungeon/skills/seo-geo/references/llmstxt-evidence.md new file mode 100644 index 00000000..43981aa9 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-geo/references/llmstxt-evidence.md @@ -0,0 +1,51 @@ +# `/llms.txt` — evidence-based reframe (May 2026) + +## TL;DR + +`/llms.txt` is **not currently consumed by any major AI search system**. +Generate one anyway as low-cost optionality, but do not present it as a +ranking or citation lever in any claude-seo report. + +## Primary-source evidence + +| Source | Date | What they said | +|---|---|---| +| **John Mueller** (Google) — Reddit + Bluesky | 2025 | "No AI system currently uses llms.txt." Compared the file to deprecated meta keywords. | +| **Gary Illyes** (Google) — Search Central Live | July 2025 | Google has no plans to support llms.txt. | +| **SE Ranking** — 300k-domain study | November 2025 | Among the 50 most AI-cited domains, **only one** had an `/llms.txt`. | +| **OtterlyAI** — server-log audit | 2025 | **0.1%** of AI-bot traffic targets `/llms.txt` (84 of 62,100 requests). | +| **Anthropic, Stripe, Cloudflare, NVIDIA** — published files | 2024–2025 | All publish `llms.txt`. **None** have stated their crawlers consume third-party `llms.txt` files. | + +## Where it does matter + +`llms.txt` is increasingly consumed by **AI coding agents** (Cursor, +Continue, Cline, Claude Code) when loading per-library documentation. +Mintlify auto-generates `/llms.txt` and `/llms-full.txt` for thousands +of developer-docs sites. For a developer-tooling site, publishing +`llms.txt` is a net win — it helps agents quote the docs accurately. + +For a non-developer business site, the value is purely defensive: zero +cost, possible future-optionality if a major AI provider eventually +adopts it. + +## How claude-seo treats `llms.txt` + +- `seo-geo` audits **report presence** of `/llms.txt` and `/llms-full.txt`. +- The audit notes whether the file is well-formed (Mintlify-style markdown). +- The audit explicitly does **not** assign citation-ranking weight to it. +- If the user asks to generate one, claude-seo produces a minimal valid + example and a banner stating "no major LLM provider has confirmed + consumption as of May 2026; ship for optionality, not for citation". + +## When this guidance changes + +Update this file (and the seo-geo audit copy) when: + +- Any major AI search system (Google AI Overviews, ChatGPT Search, + Perplexity, Bing Copilot) publishes documentation confirming + `llms.txt` consumption. +- OtterlyAI or SE Ranking publish a follow-up study showing a measurable + inflection in `/llms.txt` request rate. +- John Mueller / Gary Illyes / equivalent retract their 2025 statements. + +Last verified: 2026-05-17. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-google/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/SKILL.md new file mode 100644 index 00000000..a685c9bf --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/SKILL.md @@ -0,0 +1,350 @@ +--- +name: seo-google +description: > + Google SEO APIs: Search Console (Search Analytics, URL Inspection, Sitemaps), + PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3, + and GA4 organic traffic. Provides real Google field data for Core Web Vitals, + indexation status, search performance, and organic traffic trends. Use when + user says "search console", "GSC", "PageSpeed", "CrUX", "field data", + "indexing API", "GA4 organic", "URL inspection", "google api setup", + "real CWV data", "impressions", "clicks", "CTR", "position data", + "LCP", "INP", "CLS", "FCP", "TTFB", or "Lighthouse scores". +user-invocable: true +argument-hint: "[command] [url|property]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Google SEO APIs + +Direct access to Google's own SEO data. Bridges the gap between crawl-based +analysis (existing claude-seo skills) and Google's real-time field data: actual +Chrome user metrics, real indexation status, search performance, and organic traffic. + +All APIs are free. Setup requires a Google Cloud project with API key and/or +service account -- run `/seo google setup` for step-by-step instructions. + +## Prerequisites + +Before executing any command, check credentials: +```bash +python3 scripts/google_auth.py --check --json +``` + +Config file: `~/.config/claude-seo/google-api.json` +```json +{ + "service_account_path": "/path/to/service_account.json", + "api_key": "", + "default_property": "sc-domain:example.com", + "ga4_property_id": "properties/123456789" +} +``` + +If missing, read `references/auth-setup.md` and walk the user through setup. + +### Credential Tiers + +| Tier | Detection | Available Commands | +|------|-----------|-------------------| +| **0** (API Key) | `api_key` present | `pagespeed`, `crux`, `crux-history`, `youtube`, `nlp` | +| **1** (OAuth/SA) | + OAuth token or service account | Tier 0 + `gsc`, `inspect`, `sitemaps`, `index` | +| **2** (Full) | + `ga4_property_id` configured | Tier 1 + `ga4`, `ga4-pages` | +| **3** (Ads) | + `ads_developer_token` + `ads_customer_id` | Tier 2 + `keywords`, `volume` | + +Always communicate the detected tier before running commands. + +## Quick Reference + +| Command | What it does | Tier | +|---------|-------------|------| +| `/seo google setup` | Check/configure API credentials | -- | +| `/seo google pagespeed ` | PSI Lighthouse + CrUX field data | 0 | +| `/seo google crux ` | CrUX field data only (p75 metrics) | 0 | +| `/seo google crux-history ` | 25-week CWV trend analysis | 0 | +| `/seo google gsc ` | Search Console: clicks, impressions, CTR, position | 1 | +| `/seo google inspect ` | URL Inspection: index status, canonical, crawl info | 1 | +| `/seo google inspect-batch ` | Batch URL Inspection from file | 1 | +| `/seo google sitemaps ` | GSC sitemap status | 1 | +| `/seo google index ` | Submit URL to Indexing API | 1 | +| `/seo google index-batch ` | Batch submit up to 200 URLs | 1 | +| `/seo google ga4 [property-id]` | GA4 organic traffic report | 2 | +| `/seo google ga4-pages [property-id]` | Top organic landing pages | 2 | +| `/seo google youtube ` | YouTube video search (views, likes, duration) | 0 | +| `/seo google youtube-video ` | YouTube video details + top comments | 0 | +| `/seo google nlp ` | NLP entity extraction + sentiment + classification | 0 | +| `/seo google entities ` | Entity analysis only (for E-E-A-T) | 0 | +| `/seo google keywords ` | Keyword ideas from Google Ads Keyword Planner | 3 | +| `/seo google volume ` | Search volume lookup from Keyword Planner | 3 | +| `/seo google entity ` | Knowledge Graph entity check | 0 | +| `/seo google safety ` | Web Risk URL safety check | 0 | +| `/seo google quotas` | Show rate limits for all APIs | -- | + +--- + +## PageSpeed + CrUX + +### `/seo google pagespeed ` + +Combined Lighthouse lab data + CrUX field data. + +**Script:** `python3 scripts/pagespeed_check.py --json` +**Reference:** `references/pagespeed-crux-api.md` +**Default:** Both mobile + desktop strategies, all Lighthouse categories. + +Output merges lab scores (point-in-time Lighthouse) with field data (28-day +Chrome user metrics). CrUX tries URL-level first, falls back to origin-level. + +### `/seo google crux ` + +CrUX field data only (no Lighthouse run). Faster. + +**Script:** `python3 scripts/pagespeed_check.py --crux-only --json` + +### `/seo google crux-history ` + +25-week CrUX History trends. Shows whether CWV metrics are improving, stable, or degrading. + +**Script:** `python3 scripts/crux_history.py --json` +**Reference:** `references/pagespeed-crux-api.md` + +Output includes per-metric trend direction, percentage change, and weekly p75 values. + +--- + +## Search Console + +### `/seo google gsc ` + +Search Analytics: clicks, impressions, CTR, position for last 28 days. + +**Script:** `python3 scripts/gsc_query.py --property --json` +**Reference:** `references/search-console-api.md` +**Default:** 28 days, dimensions=query,page, type=web, limit=1000. + +Includes quick-win detection: queries at position 4-10 with high impressions. + +### `/seo google inspect ` + +URL Inspection: real indexation status from Google. + +**Script:** `python3 scripts/gsc_inspect.py --json` + +Returns: verdict (PASS/FAIL), coverage state, robots.txt status, indexing state, +page fetch state, canonical selection, mobile usability, rich results. + +### `/seo google inspect-batch ` + +Batch inspection from a file (one URL per line). Rate limited to 2,000/day per site. + +**Script:** `python3 scripts/gsc_inspect.py --batch --json` + +### `/seo google sitemaps ` + +List submitted sitemaps with status, errors, warnings. Sitemap contents report +submitted counts only; URL Inspection API is the indexation truth for whether +specific URLs are indexed. + +**Script:** `python3 scripts/gsc_query.py sitemaps --property --json` + +--- + +## Indexing API + +### `/seo google index ` + +Notify Google of a URL update. + +**Script:** `python3 scripts/indexing_notify.py --json` +**Reference:** `references/indexing-api.md` + +The Indexing API is officially for JobPosting and BroadcastEvent/VideoObject pages. +Always inform the user of this restriction. Daily quota: 200 publish requests. + +### `/seo google index-batch ` + +Batch submit URLs from a file. Tracks quota usage. + +**Script:** `python3 scripts/indexing_notify.py --batch --json` + +--- + +## GA4 Traffic + +### `/seo google ga4 [property-id]` + +Organic traffic report: daily sessions, users, pageviews, bounce rate, engagement. + +**Script:** `python3 scripts/ga4_report.py --property --json` +**Reference:** `references/ga4-data-api.md` +**Consent diagnostics:** Read `references/dma-consent-mode-v2.md` when GA4 +organic traffic looks under-reported after March 2024 or when EU/EEA consent +mode may affect attribution. +**Default:** 28 days, filtered to Organic Search channel group. + +### `/seo google ga4-pages [property-id]` + +Top organic landing pages ranked by sessions. + +**Script:** `python3 scripts/ga4_report.py --property --report top-pages --json` + +--- + +## YouTube (Video SEO) + +YouTube mentions have the strongest AI visibility correlation (0.737). Free, API key only. + +### `/seo google youtube ` + +Search YouTube for videos. Returns title, channel, views, likes, duration. + +**Script:** `python3 scripts/youtube_search.py search "" --json` +**Reference:** `references/youtube-api.md` +**Quota:** 100 units per search (10,000 units/day free). + +### `/seo google youtube-video ` + +Detailed video info + tags + top 10 comments. + +**Script:** `python3 scripts/youtube_search.py video --json` +**Quota:** 2 units (video details + comments). + +--- + +## NLP Content Analysis + +Google's own entity/sentiment analysis. Enhances E-E-A-T scoring. + +### `/seo google nlp ` + +Full NLP analysis: entities, sentiment, content classification. + +**Script:** `python3 scripts/nlp_analyze.py --url --json` or `--text "..."` +**Reference:** `references/nlp-api.md` +**Free tier:** 5,000 units/month. Requires billing enabled on GCP project. + +### `/seo google entities ` + +Entity extraction only (faster, less quota). + +**Script:** `python3 scripts/nlp_analyze.py --url --features entities --json` + +--- + +## Keyword Research (Google Ads) + +Gold-standard keyword volume data. Requires Google Ads account. + +### `/seo google keywords ` + +Generate keyword ideas from seed terms. + +**Script:** `python3 scripts/keyword_planner.py ideas "" --json` +**Reference:** `references/keyword-planner-api.md` +**Requires:** Ads developer token + customer ID in config (Tier 3). + +### `/seo google volume ` + +Search volume for specific keywords (comma-separated). + +**Script:** `python3 scripts/keyword_planner.py volume "," --json` + +--- + +## Supplementary + +### `/seo google entity ` + +Knowledge Graph entity check. Verifies brand presence. + +**Reference:** `references/supplementary-apis.md` +Uses Knowledge Graph Search API with API key. + +### `/seo google safety ` + +Web Risk API check for malware/social engineering flags. + +**Reference:** `references/supplementary-apis.md` + +### `/seo google quotas` + +Display rate limits table. Read `references/rate-limits-quotas.md`. + +--- + +## Reports + +After any analysis command, offer to generate a PDF/HTML report. + +### `/seo google report ` + +Generate a professional PDF report with charts and analytics. + +**Script:** `python3 scripts/google_report.py --type --data --domain --format pdf` + +| Type | Input | Output | +|------|-------|--------| +| `cwv-audit` | PSI + CrUX + CrUX History data | Core Web Vitals audit with gauges, timelines, distributions | +| `gsc-performance` | GSC query data | Search Console report with query tables, quick wins | +| `indexation` | Batch inspection data | Indexation status with coverage donut chart | +| `full` | All data combined | Comprehensive Google SEO report (all sections) | + +**Workflow:** +1. Run data collection commands (pagespeed, gsc, inspect-batch, etc.) +2. Save JSON output to file: `python3 scripts/pagespeed_check.py --json > data.json` +3. Generate report: `python3 scripts/google_report.py --type cwv-audit --data data.json --domain ` + +**Convention:** After completing analysis, suggest: "Generate a report? Use `/seo google report `" + +--- + +## Rate Limits + +| API | Per-Minute | Per-Day | Auth | +|-----|-----------|---------|------| +| PSI v5 | 240 QPM | 25,000 QPD | API Key | +| CrUX + History | 150 QPM (shared) | Unlimited | API Key | +| GSC Search Analytics | 1,200 QPM/site | 30M QPD | Service Account | +| GSC URL Inspection | 600 QPM | 2,000 QPD/site | Service Account | +| Indexing API | 380 RPM | 200 publish/day | Service Account | +| GA4 Data API | 10 concurrent | ~25K tokens/day | Service Account | + +## Cross-Skill Integration + +- **seo-audit**: Spawns `seo-google` agent for live CWV + indexation data (conditional) +- **seo-technical**: Uses pagespeed_check.py for real CWV field data +- **seo-performance**: CrUX field data supplements Lighthouse lab data +- **seo-sitemap**: GSC sitemap status shows submitted counts, errors, and warnings; use URL Inspection for indexation truth +- **seo-content**: GSC query data informs keyword targeting +- **seo-geo**: GSC search appearance data includes AI Overview references + +## Output Format + +- CWV metrics: traffic-light rating (Good / Needs Improvement / Poor) +- Performance reports: tables with sortable columns +- Always include data freshness note +- Save reports as `GOOGLE-API-REPORT-{domain}.md` +- Use templates from `assets/templates/` for structured output + +## Technical Notes + +- INP replaced FID on March 12, 2024. Never reference FID. +- CLS values from CrUX are string-encoded (e.g., "0.05"). Scripts handle parsing. +- CrUX 404 = insufficient traffic, not an auth error. +- Search Analytics data has 2-3 day lag. +- `round_trip_time` replaced `effectiveConnectionType` in CrUX (Feb 2025). +- Custom Search JSON API is closed to new customers (2025). + +## Error Handling + +| Scenario | Action | +|----------|--------| +| No credentials configured | Run `/seo google setup`. List Tier 0 commands that work with just an API key. | +| Service account lacks GSC access | Report error. Instruct: add `client_email` to GSC > Settings > Users > Add. | +| CrUX data unavailable (404) | Report insufficient Chrome traffic. Suggest PSI lab data as fallback. | +| GA4 property not found | Report error. Show how to find property ID in GA4 Admin > Property Details. | +| Indexing API quota exceeded | Report 200/day limit. Suggest prioritizing most important URLs. | +| Rate limit (429) | Wait and retry with exponential backoff. Report which API hit the limit. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/assets/templates/gsc-performance-report.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/assets/templates/gsc-performance-report.md new file mode 100644 index 00000000..9a19a80a --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/assets/templates/gsc-performance-report.md @@ -0,0 +1,44 @@ +# Google Search Console Performance Report + +**Property:** {property} +**Date Range:** {start_date} — {end_date} +**Search Type:** {search_type} + +## Summary + +| Metric | Value | +|--------|-------| +| Total Clicks | {total_clicks} | +| Total Impressions | {total_impressions} | +| Average CTR | {avg_ctr}% | +| Average Position | {avg_position} | + +## Top Queries + +| # | Query | Clicks | Impressions | CTR | Position | +|---|-------|--------|-------------|-----|----------| +{queries_table} + +## Top Pages + +| # | Page | Clicks | Impressions | CTR | Position | +|---|------|--------|-------------|-----|----------| +{pages_table} + +## Quick Wins (Position 4-10, High Impressions) + +These queries rank on page 1 but below position 3. A small ranking improvement could yield significant traffic gains. + +| Query | Position | Impressions | Clicks | CTR | Opportunity | +|-------|----------|-------------|--------|-----|-------------| +{quick_wins_table} + +## Device Breakdown + +| Device | Clicks | Impressions | CTR | Position | +|--------|--------|-------------|-----|----------| +{device_table} + +--- +*Data freshness: Search Analytics has a 2-3 day lag. Data available for ~16 months.* +*Generated {timestamp} via Google Search Console API.* diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/assets/templates/indexation-status-report.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/assets/templates/indexation-status-report.md new file mode 100644 index 00000000..c7d2ec09 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/assets/templates/indexation-status-report.md @@ -0,0 +1,43 @@ +# URL Indexation Status Report + +**Property:** {property} +**URLs Inspected:** {total_urls} + +## Summary + +| Status | Count | Percentage | +|--------|-------|-----------| +| Indexed (PASS) | {pass_count} | {pass_pct}% | +| Not Indexed (FAIL) | {fail_count} | {fail_pct}% | +| Neutral | {neutral_count} | {neutral_pct}% | +| Errors | {error_count} | {error_pct}% | + +## Detailed Results + +| URL | Verdict | Coverage State | Fetch State | Google Canonical | Last Crawl | +|-----|---------|---------------|-------------|-----------------|------------| +{results_table} + +## Canonical Mismatches + +URLs where Google selected a different canonical than declared: + +| URL | User Canonical | Google Canonical | +|-----|---------------|-----------------| +{canonical_mismatches_table} + +## Common Issues + +| Issue | Count | Priority | Action | +|-------|-------|----------|--------| +{issues_table} + +## Rich Results Detected + +| URL | Rich Result Type | Status | +|-----|-----------------|--------| +{rich_results_table} + +--- +*URL Inspection API: 2,000 inspections/day per site, 600/min.* +*Generated {timestamp} via Google Search Console URL Inspection API.* diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/auth-setup.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/auth-setup.md new file mode 100644 index 00000000..16e1267f --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/auth-setup.md @@ -0,0 +1,154 @@ +# Google API Authentication Setup + +## Overview + +Three credential types serve different APIs: + +| Type | Used By | Cost | +|------|---------|------| +| **API Key** | PageSpeed Insights, CrUX, CrUX History, Knowledge Graph | Free | +| **Service Account** | Search Console, Indexing API, GA4 | Free | +| **Both** | Full seo-google skill | Free | + +## Step 1: Create a Google Cloud Project + +1. Go to [console.cloud.google.com](https://console.cloud.google.com) +2. Click **Select a project** > **New Project** +3. Name it (e.g., "Claude SEO") and note the project ID +4. Select the project after creation + +## Step 2: Enable APIs + +Navigate to **APIs & Services > Library** and enable: + +| API | Required For | +|-----|-------------| +| Google Search Console API | GSC Search Analytics, URL Inspection, Sitemaps | +| PageSpeed Insights API | PSI Lighthouse lab data | +| Chrome UX Report API | CrUX field data + History | +| Web Search Indexing API | Indexing API v3 | +| Google Analytics Data API | GA4 organic traffic | +| Knowledge Graph Search API | Entity verification (optional) | + +## Step 3: Create an API Key + +1. **APIs & Services > Credentials > Create Credentials > API key** +2. Click **Restrict key**: + - Under **API restrictions**, select: PageSpeed Insights API, Chrome UX Report API, Knowledge Graph Search API +3. Copy the generated API key and store it securely + +## Step 4: Create a Service Account + +1. **IAM & Admin > Service Accounts > Create Service Account** +2. Name: `claude-seo` (or similar) +3. Skip optional permissions steps +4. Click on the created service account > **Keys > Add Key > Create new key > JSON** +5. Download the JSON file and store it securely (e.g., `~/.config/claude-seo/service_account.json`) + +The JSON file looks like: +```json +{ + "type": "service_account", + "project_id": "your-project-id", + "private_key_id": "...", + "private_key": "", + "client_email": "claude-seo@your-project.iam.gserviceaccount.com", + "client_id": "...", + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token" +} +``` + +The `client_email` field is what you add to GSC and GA4. + +## Step 5: Grant Search Console Access + +1. Go to [Google Search Console](https://search.google.com/search-console) +2. Select your property +3. **Settings > Users and permissions > Add user** +4. Paste the service account `client_email` +5. Set permission level: + - **Full** for read-only (Search Analytics, URL Inspection, Sitemaps) + - **Owner** if you also need the Indexing API + +## Step 6: Grant GA4 Access + +1. Go to [Google Analytics](https://analytics.google.com) +2. **Admin > Property Access Management > Add users** (the + icon) +3. Paste the service account `client_email` +4. Set role: **Viewer** (minimum for read-only reporting) +5. Note the numeric property ID from **Admin > Property Details** (e.g., `123456789`) + +## Step 7: Create Config File + +```bash +mkdir -p ~/.config/claude-seo +``` + +Save to `~/.config/claude-seo/google-api.json`: + +```json +{ + "service_account_path": "~/.config/claude-seo/service_account.json", + "api_key": "", + "default_property": "sc-domain:example.com", + "ga4_property_id": "properties/123456789" +} +``` + +### Property URL Formats + +| Format | Example | When to Use | +|--------|---------|-------------| +| Domain property | `sc-domain:example.com` | Covers all URLs on the domain (recommended) | +| URL-prefix property | `https://example.com/` | Covers only that specific prefix | + +## Step 8: Verify Setup + +```bash +python3 scripts/google_auth.py --check +``` + +Expected output at Tier 2 (full): +``` +Credential Tier: 2 -- Full (API key + Service Account + GA4) + + [OK] PageSpeed Insights v5 + [OK] Chrome UX Report (CrUX) API + [OK] CrUX History API + [OK] Google Search Console API + Service account: claude-seo@your-project.iam.gserviceaccount.com + [OK] Google Indexing API v3 + [OK] GA4 Data API v1beta +``` + +## Environment Variable Alternatives + +Instead of (or in addition to) the config file: + +| Variable | Purpose | +|----------|---------| +| `GOOGLE_API_KEY` | API key for PSI/CrUX | +| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON | +| `GA4_PROPERTY_ID` | GA4 property (e.g., `properties/123456789`) | +| `GSC_PROPERTY` | Default GSC property (e.g., `sc-domain:example.com`) | + +## OAuth Scopes Used + +| Scope | APIs | +|-------|------| +| `https://www.googleapis.com/auth/webmasters.readonly` | GSC (read) | +| `https://www.googleapis.com/auth/webmasters` | GSC (read/write, needed for sitemap submission) | +| `https://www.googleapis.com/auth/indexing` | Indexing API | +| `https://www.googleapis.com/auth/analytics.readonly` | GA4 (read) | + +## Troubleshooting + +| Error | Fix | +|-------|-----| +| `403 Forbidden` on GSC | Service account email not added to GSC property, or wrong permission level | +| `403 Forbidden` on GA4 | Service account email not added to GA4 property as Viewer | +| `404 Not Found` on GSC | Wrong property URL format. Use `sc-domain:` or include trailing slash for URL-prefix | +| `404 Not Found` on CrUX | Site has insufficient Chrome traffic. Not a credentials issue. | +| `429 Rate Limit` | Wait and retry. See rate-limits-quotas.md for per-API limits | +| `API not enabled` | Enable the specific API in GCP Console > APIs & Services > Library | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/dma-consent-mode-v2.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/dma-consent-mode-v2.md new file mode 100644 index 00000000..5986294f --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/dma-consent-mode-v2.md @@ -0,0 +1,60 @@ +# DMA + Consent Mode v2 — click-through impact diagnostic + +EU traffic flowing through Google Search has been subject to the +**Digital Markets Act** since 2024-03-07. The DMA limits how Google +can use behavioural data and forces consent-mode v2 compliance for +GA4 + Ads in EU. The operational effect for SEO audits: + +- EU click-through-rate (CTR) data from Search Console is materially + noisier after the DMA enforcement date. Year-over-year CTR + comparisons across that boundary are not apples-to-apples. +- GA4 organic-traffic reports for EU users show systematic + under-reporting when consent-mode v2 is configured as "denied for + ad_storage, granted for analytics_storage" (the typical EU default). + Conversion modelling fills the gap, but the raw counts are lower + than pre-2024. + +## What the seo-google skill should do + +1. **When pulling GSC search analytics for an EU-targeted property**, + note: "EU CTR comparisons before/after 2024-03-07 are not + apples-to-apples (DMA + consent-mode v2 took effect)." +2. **When pulling GA4 organic traffic**, surface the consent-mode + configuration if the GA4 admin API exposes it. If the property + has `eu_data_collection_disabled` or denies ad_storage by default, + note "EU traffic counts are conservative; conversion-modelled + uplift may apply." +3. **Do not lecture the user on cookie consent UX** — that's a legal + team / engineering concern outside SEO scope. Just attach the + diagnostic note. + +## Required GA4 / Consent Mode setup the audit should check for + +- GA4 4.x consent-mode v2 wired up (`gtag('consent', 'default', ...)` + before any pageview). +- `ads_data_redaction` flag set on EU traffic. +- Server-side tagging at consent transitions (recommended pattern; + not legally required). + +## Softening cookieless-attribution warnings + +Google **abandoned** third-party cookie deprecation in July 2024 and +confirmed in April 2025 that Chrome will not ship a standalone cookie +prompt. The "cookieless future" framing is no longer urgent. + +For audits as of May 2026: + +- Do NOT recommend "switch to cookieless attribution" as a priority. +- DO recommend "implement consent-mode v2 + server-side tagging" for + EU compliance + signal-loss recovery. +- Privacy Sandbox APIs are still available, but optional. Mention + only if the audit subject is consumer-facing and has heavy + retargeting dependence. + +## Primary sources + +- DMA enforcement: https://digital-markets-act.ec.europa.eu/ +- Google's third-party cookie reversal: https://privacysandbox.com/news/privacy-sandbox-update-jul-2024 +- Consent Mode v2 spec: https://support.google.com/google-ads/answer/14411014 + +Last verified: 2026-05-17. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/ga4-data-api.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/ga4-data-api.md new file mode 100644 index 00000000..870a9afd --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/ga4-data-api.md @@ -0,0 +1,184 @@ +# GA4 Data API v1beta Reference + +## Overview + +The Google Analytics Data API v1beta provides programmatic access to GA4 report data. For SEO, the primary use case is organic traffic analysis. + +**Base URL:** `https://analyticsdata.googleapis.com/v1beta` + +## Key Methods + +| Method | Description | +|--------|-------------| +| `properties.runReport` | Run a standard report | +| `properties.batchRunReports` | Up to 5 reports in one call | +| `properties.runRealtimeReport` | Last 30 minutes of data | +| `properties.getMetadata` | Available dimensions and metrics | +| `properties.checkCompatibility` | Verify dimension/metric combinations | + +## runReport Request + +```json +{ + "property": "properties/123456789", + "dimensions": [ + { "name": "date" }, + { "name": "landingPage" } + ], + "metrics": [ + { "name": "sessions" }, + { "name": "totalUsers" } + ], + "dateRanges": [ + { "startDate": "28daysAgo", "endDate": "yesterday" } + ], + "dimensionFilter": { + "filter": { + "fieldName": "sessionDefaultChannelGroup", + "stringFilter": { + "matchType": "EXACT", + "value": "Organic Search" + } + } + }, + "orderBys": [ + { "metric": { "metricName": "sessions" }, "desc": true } + ], + "limit": 100, + "returnPropertyQuota": true +} +``` + +## SEO-Relevant Dimensions + +| Dimension | Description | +|-----------|-------------| +| `date` | Date in YYYYMMDD format | +| `pagePath` | Page path (e.g., `/blog/post`) | +| `landingPage` | Entry page path | +| `landingPagePlusQueryString` | Entry page with query params | +| `fullPageUrl` | Full page URL | +| `pageTitle` | Page title | +| `sessionSource` | Traffic source (e.g., `google`) | +| `sessionMedium` | Traffic medium (e.g., `organic`) | +| `sessionDefaultChannelGroup` | Channel grouping (e.g., `Organic Search`) | +| `country` | User country | +| `deviceCategory` | `desktop`, `mobile`, `tablet` | +| `hostName` | Domain name | +| `pageReferrer` | Referrer URL | + +## SEO-Relevant Metrics + +| Metric | Description | +|--------|-------------| +| `sessions` | Number of sessions | +| `totalUsers` | Total unique users | +| `newUsers` | First-time users | +| `activeUsers` | Users with engagement | +| `screenPageViews` | Page views | +| `bounceRate` | Bounce rate (0-1, multiply by 100 for %) | +| `averageSessionDuration` | Avg duration in seconds | +| `engagementRate` | Engaged session rate (0-1) | +| `keyEvents` | Key events (replaced deprecated `conversions`) | +| `eventCount` | Total event count | + +## Filter Expressions + +### String Filter + +```json +{ + "filter": { + "fieldName": "sessionDefaultChannelGroup", + "stringFilter": { + "matchType": "EXACT", + "value": "Organic Search" + } + } +} +``` + +Match types: `EXACT`, `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, `FULL_REGEXP`, `PARTIAL_REGEXP` + +### Combining Filters + +```json +{ + "andGroup": { + "expressions": [ + { "filter": { "fieldName": "country", "stringFilter": { "matchType": "EXACT", "value": "US" }}}, + { "filter": { "fieldName": "deviceCategory", "stringFilter": { "matchType": "EXACT", "value": "mobile" }}} + ] + } +} +``` + +Also supports `orGroup` and `notExpression`. + +## Date Range Shortcuts + +| Value | Meaning | +|-------|---------| +| `today` | Current day | +| `yesterday` | Previous day | +| `NdaysAgo` | N days ago (e.g., `28daysAgo`) | +| `YYYY-MM-DD` | Specific date | + +Up to 4 date ranges per request (for period-over-period comparison). + +## Token-Based Quotas + +| Quota | Limit | Scope | +|-------|-------|-------| +| Daily tokens | 25,000 | Per property per project | +| Hourly tokens | 5,000 | Per property per project | +| Concurrent requests | 10 | Per property per project | +| Hourly tokens (project-wide) | 1,250 | Per project per property per hour | + +Set `returnPropertyQuota: true` to monitor consumption. Simple reports cost ~1-10 tokens; complex ones up to ~100. + +## Python Example + +```python +from google.analytics.data_v1beta import BetaAnalyticsDataClient +from google.analytics.data_v1beta.types import ( + DateRange, Dimension, Filter, FilterExpression, + Metric, OrderBy, RunReportRequest, +) +from google.oauth2 import service_account + +credentials = service_account.Credentials.from_service_account_file( + "service_account.json", + scopes=["https://www.googleapis.com/auth/analytics.readonly"], +) + +client = BetaAnalyticsDataClient(credentials=credentials) + +request = RunReportRequest( + property="properties/123456789", + dimensions=[Dimension(name="landingPage")], + metrics=[Metric(name="sessions"), Metric(name="totalUsers")], + date_ranges=[DateRange(start_date="28daysAgo", end_date="yesterday")], + dimension_filter=FilterExpression( + filter=Filter( + field_name="sessionDefaultChannelGroup", + string_filter=Filter.StringFilter( + match_type=Filter.StringFilter.MatchType.EXACT, + value="Organic Search", + ), + ) + ), + order_bys=[OrderBy(metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True)], + limit=50, + return_property_quota=True, +) + +response = client.run_report(request) +for row in response.rows: + print(f"{row.dimension_values[0].value}: {row.metric_values[0].value} sessions") +``` + +## Authentication +- **Scope:** `https://www.googleapis.com/auth/analytics.readonly` +- Service account must have **Viewer** role in GA4 property +- Add via GA4 Admin > Property Access Management diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/indexing-api.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/indexing-api.md new file mode 100644 index 00000000..ef23cae8 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/indexing-api.md @@ -0,0 +1,107 @@ +# Google Indexing API v3 Reference + +## Overview + +The Indexing API allows you to notify Google when pages are added or removed. + +**IMPORTANT:** Officially restricted to pages with **JobPosting** or **BroadcastEvent/VideoObject** structured data. Google may process other page types, but provides no guarantees. Always inform users of this limitation. + +## Endpoints + +### Publish Notification + +**`POST https://indexing.googleapis.com/v3/urlNotifications:publish`** + +```json +{ + "url": "https://example.com/jobs/software-engineer", + "type": "URL_UPDATED" +} +``` + +| Field | Values | +|-------|--------| +| `url` | The fully qualified URL | +| `type` | `URL_UPDATED` (page added/changed), `URL_DELETED` (page removed) | + +**Response:** +```json +{ + "urlNotificationMetadata": { + "url": "https://example.com/jobs/software-engineer", + "latestUpdate": { + "url": "https://example.com/jobs/software-engineer", + "type": "URL_UPDATED", + "notifyTime": "2026-03-27T10:00:00Z" + } + } +} +``` + +### Get Notification Metadata + +**`GET https://indexing.googleapis.com/v3/urlNotifications/metadata?url={ENCODED_URL}`** + +Returns `latestUpdate` and `latestRemove` timestamps for the URL. + +### Batch Requests + +**`POST https://indexing.googleapis.com/batch`** + +Up to **100 URLs** per batch request using `multipart/mixed` format: + +``` +POST /batch HTTP/1.1 +Content-Type: multipart/mixed; boundary=batch_boundary + +--batch_boundary +Content-Type: application/http +Content-ID: + +POST /v3/urlNotifications:publish HTTP/1.1 +Content-Type: application/json + +{"url": "https://example.com/jobs/1", "type": "URL_UPDATED"} +--batch_boundary +Content-Type: application/http +Content-ID: + +POST /v3/urlNotifications:publish HTTP/1.1 +Content-Type: application/json + +{"url": "https://example.com/jobs/2", "type": "URL_UPDATED"} +--batch_boundary-- +``` + +## Authentication + +- **Scope:** `https://www.googleapis.com/auth/indexing` +- **Auth type:** Service account (OAuth 2.0) +- The service account must be **Owner** in Google Search Console for the target domain + +## Quotas + +| Limit | Value | Scope | +|-------|-------|-------| +| Publish requests | **200/day** (default) | Per project | +| Read-only requests | 180/min | Per project | +| Total requests | 380/min | Per project | + +Request a quota increase: [Indexing API Quota Increase Form](https://developers.google.com/search/apis/indexing-api/v3/quota-increase) + +## Error Codes + +| Code | Meaning | Action | +|------|---------|--------| +| 400 | Malformed URL or request body | Check URL format | +| 403 | Permission denied or quota exceeded | Add service account as Owner in GSC, or check quota | +| 429 | Rate limit exceeded | Back off and retry with exponential delay | +| 500/503 | Server error | Retry with exponential backoff | + +## Best Practices + +1. Submit only URLs with actual content changes (don't spam updates) +2. Use `URL_DELETED` only when a page is permanently removed (returns 404/410) +3. Track daily quota usage -- the 200/day limit resets at midnight Pacific Time +4. For large-scale indexing, use XML sitemaps + Search Console instead +5. Batch requests count individually against the daily quota (100 batch = 100 quota) diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/keyword-planner-api.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/keyword-planner-api.md new file mode 100644 index 00000000..bd065aa7 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/keyword-planner-api.md @@ -0,0 +1,66 @@ +# Google Ads API - Keyword Planner Reference + +Gold-standard source for keyword search volume. DataForSEO gets its volume data from Google Ads -- this cuts out the middleman. + +## Prerequisites (More Complex Than Other Google APIs) + +1. **Google Ads Manager Account** -- create at ads.google.com (free to create) +2. **Developer Token** -- apply at Google Ads API Center (requires Basic access approval) +3. **OAuth 2.0 credentials** -- reuse existing OAuth client from seo-google config +4. **For exact volumes**: Run a minimal campaign (~$5-10/day). Without spend, volumes are bucketed ranges ("1K-10K") + +## Key Methods + +### GenerateKeywordIdeas +Generate keyword suggestions from seed terms. + +**Returns per keyword:** +- `text`: Keyword string +- `avg_monthly_searches`: Average monthly volume (exact if spending, bucketed if not) +- `competition`: LOW / MEDIUM / HIGH (for ads, not organic) +- `competition_index`: 0-100 competition score +- `low_top_of_page_bid_micros`: ~20th percentile CPC in micros +- `high_top_of_page_bid_micros`: ~80th percentile CPC in micros +- `monthly_search_volumes[]`: Per-month volume for last 12 months + +### GenerateKeywordHistoricalMetrics +Get volume data for specific keywords. + +Same return fields as above but for exact keyword list instead of suggestions. + +### GenerateKeywordForecastMetrics +Predict clicks, impressions, and cost for keywords. + +## Configuration + +Add to `~/.config/claude-seo/google-api.json`: + +```json +{ + "ads_developer_token": "YOUR_DEV_TOKEN", + "ads_customer_id": "123-456-7890", + "ads_login_customer_id": "123-456-7890" +} +``` + +## Rate Limits + +- Keyword Planning requests are more strictly rate-limited than other Ads API services +- Exact QPM/QPS not publicly documented +- Google recommends caching results + +## Python Library + +```bash +pip install google-ads +``` + +Uses `google-ads` library (separate from `google-api-python-client`). + +## Important Notes + +- **Volume accuracy**: Without active ad spend, Google returns bucketed ranges ("1K-10K", "10K-100K") instead of exact numbers like "14,800" +- **Competition score**: Measures advertiser competition for ads, NOT organic ranking difficulty +- **CPC bids**: Reflect what advertisers pay, useful for estimating keyword commercial value +- **Location targeting**: Use location IDs (2840 = United States, 2826 = United Kingdom) +- **Language targeting**: Use language IDs (1000 = English, 1003 = Spanish) diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/nlp-api.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/nlp-api.md new file mode 100644 index 00000000..c10fa2e6 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/nlp-api.md @@ -0,0 +1,59 @@ +# Google Cloud Natural Language API Reference + +NLP analysis enhances E-E-A-T scoring by measuring entity coverage, content sentiment, and topic classification using Google's own taxonomy. + +## Endpoint + +Entities use `POST https://language.googleapis.com/v1/documents:analyzeEntities`. +Sentiment, classification, and moderation use +`POST https://language.googleapis.com/v2/documents:annotateText`. + +Send the API key in the `X-Goog-Api-Key` header, not in the URL. + +## Features + +| Feature | What It Does | SEO Use | +|---------|-------------|---------| +| `extractEntities` | Extract people, orgs, places, events with salience scores | Topic coverage depth, entity optimization | +| `extractDocumentSentiment` | Document + sentence-level sentiment score/magnitude | Content tone assessment | +| `classifyText` | Map content to 700+ Google categories | Topic relevance verification | +| `moderateText` | Content safety/moderation categories | Content quality flags | + +## Entity Types + +PERSON, LOCATION, ORGANIZATION, EVENT, WORK_OF_ART, CONSUMER_GOOD, OTHER, PHONE_NUMBER, ADDRESS, DATE, NUMBER, PRICE + +Each entity includes: +- `name`: Entity text +- `type`: Entity type +- `salience`: Importance score (0-1, higher = more relevant) +- `sentiment`: Per-entity sentiment (score + magnitude) +- `metadata`: Wikipedia URL, MID (Knowledge Graph ID) +- `mentions`: Occurrences in the text + +## Sentiment Scoring + +- **Score**: -1.0 (negative) to +1.0 (positive) +- **Magnitude**: 0 to infinity (emotional intensity, higher = more emotional) +- Neutral content: score ~0, low magnitude +- Mixed content: score ~0, HIGH magnitude (both positive and negative) + +## Pricing + +| Feature | Free/month | Paid (per 1K chars) | +|---------|-----------|-------------------| +| Entity Analysis | 5,000 units | $0.001 | +| Sentiment Analysis | 5,000 units | $0.001 | +| Content Classification | 30,000 units | $0.002 | +| Text Moderation | 50,000 units | $0.0005 | + +One "unit" = 1,000 characters. Free tier resets monthly. + +## Enable the API + +1. Go to [console.cloud.google.com/apis/library](https://console.cloud.google.com/apis/library) +2. Search for "Cloud Natural Language API" +3. Click Enable +4. **Billing must be enabled** on the project (free tier still applies) + +Uses the same API key as PSI/CrUX. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/pagespeed-crux-api.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/pagespeed-crux-api.md new file mode 100644 index 00000000..720f69d3 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/pagespeed-crux-api.md @@ -0,0 +1,208 @@ +# PageSpeed Insights v5 + CrUX API Reference + +## Table of Contents +1. [PageSpeed Insights v5](#pagespeed-insights-v5) +2. [CrUX API (Daily)](#crux-api-daily) +3. [CrUX History API (Weekly)](#crux-history-api-weekly) +4. [Core Web Vitals Thresholds](#core-web-vitals-thresholds) + +--- + +## PageSpeed Insights v5 + +**Endpoint:** `GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed` + +### Parameters + +| Param | Type | Description | +|-------|------|-------------| +| `url` | string | Required. URL to analyze. | +| `category` | string | `ACCESSIBILITY`, `BEST_PRACTICES`, `PERFORMANCE`, `SEO`. Can specify multiple. | +| `strategy` | string | `DESKTOP` or `MOBILE` (default). | +| `locale` | string | Locale for text (e.g., `en`). | +| `key` | string | API key. Optional but recommended for quota. | + +### Response Structure + +``` +{ + "id": "https://example.com/", + "loadingExperience": { ... }, // URL-level CrUX data + "originLoadingExperience": { ... }, // Origin-level CrUX data + "lighthouseResult": { + "categories": { + "performance": { "score": 0.85 }, + "accessibility": { "score": 0.92 }, + "best-practices": { "score": 0.88 }, + "seo": { "score": 0.95 } + }, + "audits": { ... } // Individual audit results + }, + "analysisUTCTimestamp": "2026-03-27T..." +} +``` + +### Field Data Metrics (in loadingExperience) + +| PSI Key | CrUX Metric | Unit | +|---------|-------------|------| +| `LARGEST_CONTENTFUL_PAINT_MS` | LCP | ms | +| `INTERACTION_TO_NEXT_PAINT` | INP | ms | +| `CUMULATIVE_LAYOUT_SHIFT_SCORE` | CLS | unitless | +| `FIRST_CONTENTFUL_PAINT_MS` | FCP | ms | +| `EXPERIMENTAL_TIME_TO_FIRST_BYTE` | TTFB | ms | + +Each metric contains: `percentile` (p75), `distributions[]` ({min, max, proportion}), `category` (FAST/AVERAGE/SLOW/NONE). + +### Key Lighthouse Audit IDs + +`first-contentful-paint`, `largest-contentful-paint`, `total-blocking-time`, `cumulative-layout-shift`, `speed-index`, `interactive` + +### Rate Limits +- 25,000 QPD with API key +- 240 QPM +- Free, no billing required + +### Note on Field Data Migration +Google is migrating CrUX field data out of PSI. For field data, prefer the CrUX API directly. Use PSI primarily for Lighthouse lab data. + +--- + +## CrUX API (Daily) + +**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryRecord` + +Send the API key in the `X-Goog-Api-Key` header, not in the URL. + +### Request + +```json +{ + "origin": "https://example.com", + "formFactor": "PHONE", + "metrics": ["largest_contentful_paint", "interaction_to_next_paint", "cumulative_layout_shift"] +} +``` + +| Field | Description | +|-------|-------------| +| `origin` | Origin URL (mutually exclusive with `url`) | +| `url` | Specific page URL (mutually exclusive with `origin`) | +| `formFactor` | `DESKTOP`, `PHONE`, `TABLET` (optional, omit for all) | +| `metrics` | Array of metric names (optional, omit for all) | + +### Available Metrics + +| Metric | Type | Notes | +|--------|------|-------| +| `largest_contentful_paint` | int (ms) | Core Web Vital | +| `interaction_to_next_paint` | int (ms) | Core Web Vital (replaced FID) | +| `cumulative_layout_shift` | **string** | Core Web Vital. **String-encoded!** Parse carefully. | +| `first_contentful_paint` | int (ms) | | +| `experimental_time_to_first_byte` | int (ms) | | +| `round_trip_time` | int (ms) | Replaced effectiveConnectionType (Feb 2025) | +| `navigation_types` | fractions | navigate, navigate_cache, reload, etc. | +| `form_factors` | fractions | desktop/phone/tablet distribution | + +### Response + +```json +{ + "record": { + "key": { "origin": "https://example.com" }, + "metrics": { + "largest_contentful_paint": { + "histogram": [ + { "start": 0, "end": 2500, "density": 0.72 }, + { "start": 2500, "end": 4000, "density": 0.18 }, + { "start": 4000, "density": 0.10 } + ], + "percentiles": { "p75": 2100 } + }, + "cumulative_layout_shift": { + "percentiles": { "p75": "0.05" } + } + }, + "collectionPeriod": { + "firstDate": { "year": 2026, "month": 2, "day": 27 }, + "lastDate": { "year": 2026, "month": 3, "day": 26 } + } + } +} +``` + +### Important +- **CLS p75 is a string** (e.g., `"0.05"` not `0.05`). Always parse as float from string. +- Last histogram bin has **no `end`** (extends to infinity). +- Densities sum to approximately 1.0. +- **404** = no data (insufficient Chrome traffic). Not an auth error. +- Updated daily ~04:00 UTC with ~2 day lag. + +### Rate Limits +- 150 QPM shared between CrUX and CrUX History APIs +- Free, no paid increase available + +--- + +## CrUX History API (Weekly) + +**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord` + +Send the API key in the `X-Goog-Api-Key` header, not in the URL. + +Same request format as CrUX API. Returns up to **25 weekly collection periods**. + +### Response Differences from CrUX API + +Instead of single values, returns timeseries: + +```json +{ + "record": { + "metrics": { + "largest_contentful_paint": { + "histogramTimeseries": [ + { "start": 0, "end": 2500, "densities": [0.70, 0.71, 0.72, ...] }, + { "start": 2500, "end": 4000, "densities": [0.19, 0.18, 0.18, ...] }, + { "start": 4000, "densities": [0.11, 0.11, 0.10, ...] } + ], + "percentilesTimeseries": { + "p75s": [2200, 2150, 2100, ...] + } + } + }, + "collectionPeriods": [ + { + "firstDate": { "year": 2025, "month": 9, "day": 29 }, + "lastDate": { "year": 2025, "month": 10, "day": 26 } + }, + ... + ] + } +} +``` + +### NaN Handling +- `"NaN"` string for densities in ineligible periods +- `null` for percentile values in ineligible periods +- Always check for these before numeric operations + +### Update Schedule +- Updated **Mondays** ~04:00 UTC +- Each period = 28-day rolling average ending on a Sunday + +--- + +## Core Web Vitals Thresholds + +Current as of March 2026. INP replaced FID on March 12, 2024. + +| Metric | Good | Needs Improvement | Poor | +|--------|------|-------------------|------| +| **LCP** | ≤ 2,500ms | 2,500–4,000ms | > 4,000ms | +| **INP** | ≤ 200ms | 200–500ms | > 500ms | +| **CLS** | ≤ 0.1 | 0.1–0.25 | > 0.25 | +| **FCP** | ≤ 1,800ms | 1,800–3,000ms | > 3,000ms | +| **TTFB** | ≤ 800ms | 800–1,800ms | > 1,800ms | + +FID was fully removed from Chrome tools (CrUX, PSI, Lighthouse) on September 9, 2024. Never reference FID in outputs. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/rate-limits-quotas.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/rate-limits-quotas.md new file mode 100644 index 00000000..dc6b6da4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/rate-limits-quotas.md @@ -0,0 +1,75 @@ +# Google API Rate Limits & Quotas + +## Consolidated Quota Table + +| API | Per-Minute | Per-Day | Cost | Auth Type | Scope | +|-----|-----------|---------|------|-----------|-------| +| GSC Search Analytics | 1,200 QPM/user, 1,200 QPM/site | 30M QPD/project | Free | Service Account | Per user + per site | +| GSC URL Inspection | 600 QPM/site | 2,000 QPD/site | Free | Service Account | Per site | +| GSC Sitemaps | Standard | Standard | Free | Service Account | Per site | +| PageSpeed Insights v5 | 240 QPM | 25,000 QPD | Free | API Key | Per project | +| CrUX API | 150 QPM (shared) | Unlimited | Free | API Key | Per project | +| CrUX History API | 150 QPM (shared with CrUX) | Unlimited | Free | API Key | Per project | +| Indexing API | 380 RPM total, 180 read/min | 200 publish/day | Free | Service Account | Per project | +| GA4 Data API | 10 concurrent | ~25K tokens/day | Free | Service Account | Per property/project | +| Knowledge Graph | -- | 100,000 QPD | Free | API Key | Per project | +| Custom Search | -- | 10,000 QPD max | 100 free, $5/1K | API Key | Per project | +| Web Risk | 6,000 QPM | 100K/month | Free tier | API Key | Per project | + +**Key distinction:** "Per site" quotas are scoped to a specific GSC property. "Per project" quotas are shared across all properties in a GCP project. "Per user" quotas are per authenticated user (service account). + +## Exponential Backoff Strategy + +When receiving 429 or 5xx errors: + +``` +Attempt 1: wait 1 second +Attempt 2: wait 2 seconds +Attempt 3: wait 4 seconds +Attempt 4: wait 8 seconds +Attempt 5: wait 16 seconds +Max: give up after 5 retries +``` + +Add random jitter (0-500ms) to each wait to avoid thundering herd. + +## Common Error Codes + +| Code | Meaning | Applies To | Action | +|------|---------|------------|--------| +| 400 | Bad request | All | Check URL format, request body | +| 401 | Unauthorized | Service Account APIs | Refresh credentials | +| 403 | Forbidden | GSC, GA4, Indexing | Check permissions (service account access) | +| 404 | Not found | CrUX, GSC | Insufficient traffic (CrUX) or invalid property (GSC) | +| 429 | Rate limited | All | Backoff and retry. Check Retry-After header. | +| 500 | Server error | All | Retry with backoff | +| 503 | Service unavailable | All | Retry with backoff | + +## Retry-After Header + +Some Google APIs return a `Retry-After` header with 429 responses. When present, use this value (in seconds) instead of exponential backoff. + +## GA4 Token Budgeting + +GA4 uses a token system rather than simple request counts: +- Simple 1-dimension, 1-metric report: ~1-5 tokens +- Complex multi-dimension, multi-metric: ~10-100 tokens +- Set `returnPropertyQuota: true` to monitor consumption +- Daily limit: 25,000 tokens per property per project +- Hourly limit: 5,000 tokens per property per project +- Concurrent: max 10 simultaneous requests + +## CrUX Shared Quota + +The CrUX API and CrUX History API share the same 150 QPM quota per project. Plan accordingly if querying both APIs in the same workflow. + +## Cost Summary + +**All APIs used by seo-google are free** at normal usage levels. No billing is required for: +- PSI, CrUX, CrUX History (API key, unlimited free) +- GSC (service account, 30M QPD) +- Indexing API (service account, 200 publish/day) +- GA4 Data API (service account, 25K tokens/day) +- Knowledge Graph (API key, 100K QPD) + +Only Custom Search and Web Risk have paid tiers at high volumes. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/search-console-api.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/search-console-api.md new file mode 100644 index 00000000..59eb0f7c --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/search-console-api.md @@ -0,0 +1,156 @@ +# Google Search Console API Reference + +## Table of Contents +1. [Search Analytics API](#search-analytics-api) +2. [URL Inspection API](#url-inspection-api) +3. [Sitemaps API](#sitemaps-api) +4. [Sites API](#sites-api) + +--- + +## Search Analytics API + +**Endpoint:** `POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query` + +### Request Body + +| Field | Type | Description | +|-------|------|-------------| +| `startDate` | string | Required. YYYY-MM-DD format. | +| `endDate` | string | Required. YYYY-MM-DD format. | +| `dimensions` | string[] | `query`, `page`, `country`, `device`, `date`, `searchAppearance` | +| `type` | string | `web` (default), `image`, `video`, `news`, `discover`, `googleNews` | +| `dimensionFilterGroups` | object[] | Array of filter groups (see below) | +| `aggregationType` | string | `auto` (default), `byPage`, `byProperty`, `byNewsShowcasePanel` | +| `rowLimit` | int | 1-25000 (default: 1000) | +| `startRow` | int | Pagination offset (default: 0) | +| `dataState` | string | `final` (default), `all`, `hourly_all` | + +### Dimension Filters + +```json +{ + "dimensionFilterGroups": [{ + "filters": [{ + "dimension": "query", + "operator": "contains", + "expression": "seo" + }] + }] +} +``` + +**Operators:** `contains`, `equals`, `notContains`, `notEquals`, `includingRegex`, `excludingRegex` +- Regex uses RE2 syntax, max 4096 characters + +### Response + +```json +{ + "rows": [ + { + "keys": ["seo tools", "https://example.com/tools"], + "clicks": 150, + "impressions": 5000, + "ctr": 0.03, + "position": 4.2 + } + ], + "responseAggregationType": "byPage" +} +``` + +### Important Notes +- Data has a **2-3 day lag**. Available for approximately 16 months. +- `discover` and `googleNews` types do not support `query` dimension or `position` metric. +- Country codes are **ISO 3166-1 alpha-3** (e.g., `USA`, `GBR`, `DEU`). +- Pagination: increment `startRow` by `rowLimit` until fewer rows returned. + +### Rate Limits +- 1,200 QPM per user +- 1,200 QPM per site +- 40,000 QPM / 30,000,000 QPD per project + +--- + +## URL Inspection API + +**Endpoint:** `POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect` + +### Request + +```json +{ + "inspectionUrl": "https://example.com/page", + "siteUrl": "sc-domain:example.com", + "languageCode": "en" +} +``` + +### Response Fields + +**`indexStatusResult`:** + +| Field | Values | +|-------|--------| +| `verdict` | `PASS`, `FAIL`, `NEUTRAL`, `PARTIAL`, `VERDICT_UNSPECIFIED` | +| `coverageState` | Human-readable coverage description | +| `robotsTxtState` | `ALLOWED`, `DISALLOWED` | +| `indexingState` | `INDEXING_ALLOWED`, `BLOCKED_BY_META_TAG`, `BLOCKED_BY_HTTP_HEADER` | +| `pageFetchState` | `SUCCESSFUL`, `SOFT_404`, `BLOCKED_ROBOTS_TXT`, `NOT_FOUND`, `ACCESS_DENIED`, `SERVER_ERROR`, `REDIRECT_ERROR`, `ACCESS_FORBIDDEN`, `BLOCKED_4XX`, `INTERNAL_CRAWL_ERROR`, `INVALID_URL` | +| `lastCrawlTime` | ISO 8601 timestamp | +| `googleCanonical` | URL Google selected as canonical | +| `userCanonical` | URL declared canonical by the page | +| `crawledAs` | `DESKTOP`, `MOBILE` | + +**`richResultsResult`:** Verdict + detected rich result types (FAQPage, HowTo, etc.) + +### Rate Limits +- 2,000 QPD / 600 QPM per site +- 10,000,000 QPD / 15,000 QPM per project + +--- + +## Sitemaps API + +**Base:** `https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/sitemaps` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/sitemaps` | List all sitemaps | +| `GET` | `/sitemaps/{feedpath}` | Get specific sitemap | +| `PUT` | `/sitemaps/{feedpath}` | Submit a sitemap | +| `DELETE` | `/sitemaps/{feedpath}` | Delete a sitemap | + +### Sitemap Resource + +| Field | Description | +|-------|-------------| +| `path` | URL of the sitemap | +| `lastSubmitted` | Last submission timestamp | +| `isPending` | Whether processing is incomplete | +| `isSitemapsIndex` | Whether this is a sitemap index | +| `type` | `sitemap`, `atomFeed`, `rssFeed`, `urlList`, `notSitemap` | +| `warnings` | Warning count | +| `errors` | Error count | +| `contents[]` | Array with `type` (web, image, video, news) and `submitted` count | + +--- + +## Sites API + +**Base:** `https://www.googleapis.com/webmasters/v3/sites` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/sites` | List all verified properties | +| `GET` | `/sites/{siteUrl}` | Get property info | +| `PUT` | `/sites/{siteUrl}` | Add a property | +| `DELETE` | `/sites/{siteUrl}` | Remove a property | + +### Property Resource + +| Field | Values | +|-------|--------| +| `siteUrl` | Property URL (e.g., `sc-domain:example.com`) | +| `permissionLevel` | `siteOwner`, `siteFullUser`, `siteRestrictedUser`, `siteUnverifiedUser` | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/supplementary-apis.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/supplementary-apis.md new file mode 100644 index 00000000..2662f4b3 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/supplementary-apis.md @@ -0,0 +1,99 @@ +# Supplementary Google APIs for SEO + +## Knowledge Graph Search API + +Verify brand/entity presence in Google's Knowledge Graph. + +**Endpoint:** `GET https://kgsearch.googleapis.com/v1/entities:search` + +| Param | Description | +|-------|-------------| +| `query` | Search query | +| `ids` | Specific entity IDs (e.g., `/m/0d6lp`) | +| `languages` | Language codes (e.g., `en`) | +| `types` | Schema.org types to filter (e.g., `Organization`, `Person`) | +| `limit` | Max results (1-500) | +| `key` | API key (required) | + +**Response:** +```json +{ + "itemListElement": [{ + "result": { + "@id": "kg:/m/0d6lp", + "name": "Google", + "@type": ["Organization", "Corporation"], + "description": "Technology company", + "detailedDescription": { + "articleBody": "Google LLC is an American...", + "url": "https://en.wikipedia.org/wiki/Google" + }, + "image": { "url": "..." }, + "url": "https://www.google.com" + }, + "resultScore": 4892.5 + }] +} +``` + +**Use for SEO:** Verify if a brand has a Knowledge Panel, check entity disambiguation, find related entities. + +**Quota:** 100,000 reads/day. Free. API key only. + +--- + +## Custom Search JSON API + +Programmatic Google search results (limited). + +**Endpoint:** `GET https://customsearch.googleapis.com/customsearch/v1` + +| Param | Description | +|-------|-------------| +| `key` | API key (required) | +| `cx` | Programmable Search Engine ID (required) | +| `q` | Search query | +| `num` | Results per page (1-10) | +| `start` | Start index (max 91) | +| `dateRestrict` | Date restriction (e.g., `d30` for 30 days) | +| `gl` | Country (e.g., `us`) | +| `lr` | Language restriction | +| `searchType` | `image` for image search | +| `siteSearch` | Restrict to a domain | + +**Limitations:** +- Max 100 total results per query (10 pages x 10 results) +- **CLOSED to new customers as of 2025.** Existing customers must migrate by January 2027. +- 100 queries/day free, $5 per 1,000 up to 10,000/day + +**For SERP data, prefer DataForSEO** (`/seo dataforseo serp`) which has no such limitations. + +--- + +## Web Risk API + +Check if URLs are flagged as unsafe by Google Safe Browsing. + +**Endpoint:** `GET https://webrisk.googleapis.com/v1/uris:search` + +| Param | Description | +|-------|-------------| +| `threatTypes` | `MALWARE`, `SOCIAL_ENGINEERING`, `UNWANTED_SOFTWARE`, `SOCIAL_ENGINEERING_EXTENDED_COVERAGE` | +| `uri` | URL to check | +| `key` | API key (required) | + +**Response (clean URL):** Empty threat object. + +**Response (flagged URL):** +```json +{ + "threat": { + "threatTypes": ["MALWARE"], + "expireTime": "2026-04-01T00:00:00Z" + } +} +``` + +**Use for SEO:** Check if pages are flagged (could explain deindexing), verify competitor safety, audit outbound links. + +**Quota:** 6,000 QPM. 100,000/month free tier. Requires billing enabled on GCP project. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-google/references/youtube-api.md b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/youtube-api.md new file mode 100644 index 00000000..5d29fee5 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-google/references/youtube-api.md @@ -0,0 +1,49 @@ +# YouTube Data API v3 Reference + +YouTube mentions have the strongest correlation with AI visibility (0.737 per GEO research). This API provides authoritative YouTube data directly from Google. + +## Endpoints Used + +| Method | Quota Cost | Description | +|--------|-----------|-------------| +| `search.list` | 100 units | Search for videos matching a query | +| `videos.list` | 1 unit | Get video details, statistics, content | +| `channels.list` | 1 unit | Get channel info, subscriber count | +| `commentThreads.list` | 1 unit | Get top comments on a video | + +## Daily Quota + +Default: **10,000 units/day** (free). This allows: +- ~100 searches per day, OR +- ~10,000 video/channel lookups per day + +## Data Available + +### Video Search +- Title, channel, channel ID, published date +- Description (first 300 chars), thumbnail URL +- Views, likes, comments count, duration + +### Video Details +- Full description, tags, category ID +- Duration, definition (HD/SD), has captions +- Topic categories (Wikipedia URLs) +- Views, likes, comments, favorites +- Top 10 relevant comments with likes + +### Channel Info +- Title, description, custom URL +- Subscriber count, video count, total views +- Country, published date, thumbnail + +## Authentication + +**API key only** (read-only public data). No OAuth needed. + +## Enable the API + +1. Go to [console.cloud.google.com/apis/library](https://console.cloud.google.com/apis/library) +2. Search for "YouTube Data API v3" +3. Click Enable + +No billing required. The API key you already have for PSI/CrUX works. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/SKILL.md new file mode 100644 index 00000000..84c458b1 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/SKILL.md @@ -0,0 +1,257 @@ +--- +name: seo-hreflang +description: > + Hreflang and international SEO audit, validation, and generation. Detects + common mistakes, validates language/region codes, and generates correct + hreflang implementations. Use when user says "hreflang", "i18n SEO", + "international SEO", "multi-language", "multi-region", or "language tags". +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Hreflang & International SEO + +Validate existing hreflang implementations or generate correct hreflang tags +for multi-language and multi-region sites. Supports HTML, HTTP header, and +XML sitemap implementations. + +## Validation Checks + +### 1. Self-Referencing Tags +- Every page must include an hreflang tag pointing to itself +- The self-referencing URL must exactly match the page's canonical URL +- Missing self-referencing tags cause Google to ignore the entire hreflang set + +### 2. Return Tags +- If page A links to page B with hreflang, page B must link back to page A +- Every hreflang relationship must be bidirectional (A→B and B→A) +- Missing return tags invalidate the hreflang signal for both pages +- Check all language versions reference each other (full mesh) + +### 3. x-default Tag +- Required: designates the fallback page for unmatched languages/regions +- Typically points to the language selector page or English version +- Only one x-default per set of alternates +- Must also have return tags from all other language versions + +### 4. Language Code Validation +- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`) +- Common errors: + - `eng` instead of `en` (ISO 639-2, not valid for hreflang) + - `jp` instead of `ja` (incorrect code for Japanese) + - `zh` without region qualifier (ambiguous; use `zh-Hans` or `zh-Hant`) + +### 5. Region Code Validation +- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., `en-US`, `en-GB`, `pt-BR`) +- Format: `language-REGION` (lowercase language, uppercase region) +- Common errors: + - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 code) + - `es-LA` (Latin America is not a country; use specific countries) + - Region without language prefix + +### 6. Canonical URL Alignment +- Hreflang tags must only appear on canonical URLs +- If a page has `rel=canonical` pointing elsewhere, hreflang on that page is ignored +- The canonical URL and hreflang URL must match exactly (including trailing slashes) +- Non-canonical pages should not be in any hreflang set + +### 7. Protocol Consistency +- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP) +- Mixed HTTP/HTTPS in hreflang sets causes validation failures +- After HTTPS migration, update all hreflang tags to HTTPS + +### 8. Cross-Domain Support +- Hreflang works across different domains (e.g., example.com and example.de) +- Cross-domain hreflang requires return tags on both domains +- Verify both domains are verified in Google Search Console +- Sitemap-based implementation recommended for cross-domain setups + +## Common Mistakes + +| Issue | Severity | Fix | +|-------|----------|-----| +| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL | +| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates | +| Missing x-default | High | Add x-default pointing to fallback/selector page | +| Invalid language code (e.g., `eng`) | High | Use ISO 639-1 two-letter codes | +| Invalid region code (e.g., `en-uk`) | High | Use ISO 3166-1 Alpha-2 codes | +| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only | +| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS | +| Trailing slash inconsistency | Medium | Match canonical URL format exactly | +| Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) | +| Language without region when needed | Low | Add region qualifier for geo-targeted content | + +## Implementation Methods + +### Method 1: HTML Link Tags +Best for: Sites with <50 language/region variants per page. + +```html + + + + +``` + +Place in `` section. Every page must include all alternates including itself. + +### Method 2: HTTP Headers +Best for: Non-HTML files (PDFs, documents). + +``` +Link: ; rel="alternate"; hreflang="en-US", + ; rel="alternate"; hreflang="fr", + ; rel="alternate"; hreflang="x-default" +``` + +Set via server configuration or CDN rules. + +### Method 3: XML Sitemap (Recommended for large sites) +Best for: Sites with many language variants, cross-domain setups, or 50+ pages. + +See Hreflang Sitemap Generation section below. + +### Method Comparison +| Method | Best For | Pros | Cons | +|--------|----------|------|------| +| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats ``, hard to maintain at scale | +| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML | +| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance | + +## Hreflang Generation + +### Process +1. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute) +2. **Map page equivalents**: Match corresponding pages across languages/regions +3. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-1 +4. **Generate tags**: Create hreflang tags for each page including self-referencing +5. **Verify return tags**: Confirm all relationships are bidirectional +6. **Add x-default**: Set fallback for each page set +7. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML) + +## Hreflang Sitemap Generation + +### Sitemap with Hreflang +```xml + + + + https://example.com/page + + + + + + + https://example.com/fr/page + + + + + + +``` + +Key rules: +- Include the `xmlns:xhtml` namespace declaration +- Every `` entry must include ALL language alternates (including itself) +- Each alternate must appear as a separate `` entry with its own full set +- Split at 50,000 URLs per sitemap file + +## Output + +### Hreflang Validation Report + +#### Summary +- Total pages scanned: XX +- Language variants detected: XX +- Issues found: XX (Critical: X, High: X, Medium: X, Low: X) + +#### Validation Results +| Language | URL | Self-Ref | Return Tags | x-default | Status | +|----------|-----|----------|-------------|-----------|--------| +| en-US | https://... | ✅ | ✅ | ✅ | ✅ | +| fr | https://... | ❌ | ⚠️ | ✅ | ❌ | +| de | https://... | ✅ | ❌ | ✅ | ❌ | + +### Generated Hreflang Tags +- HTML `` tags (if HTML method chosen) +- HTTP header values (if header method chosen) +- `hreflang-sitemap.xml` (if sitemap method chosen) + +### Recommendations +- Missing implementations to add +- Incorrect codes to fix +- Method migration suggestions (e.g., HTML to sitemap for scale) + +## Cultural Adaptation Assessment + +When analyzing a multi-language site, go beyond technical hreflang validation to assess +whether the content is culturally adapted for each target market. + +Load `references/cultural-profiles.md` for pre-built profiles (DACH, Francophone, Hispanic, Japanese). + +**Assessment steps:** +1. Identify all language versions and their target markets +2. Load the relevant cultural profile(s) +3. Check CTAs match cultural expectations (direct vs indirect) +4. Check trust signals are locale-appropriate (certifications, legal pages) +5. Check for foreign brand references on localized pages +6. Check number/date/currency formatting consistency +7. Flag cultural adaptation issues as Medium severity + +**Output:** Cultural Adaptation Score per language version (0-100) with specific findings. + +## Content Parity Audit + +**Command:** `/seo hreflang audit ` + +Audit content parity across all language versions of a site or local content directory. + +Load `references/content-parity.md` for the full parity matrix and scoring methodology. + +**What it checks:** +- Page existence across all declared languages +- Section structure equivalence (H2/H3 count) +- SEO element parity (title, meta, schema localization) +- Word count ratio validation (DE should be 25-35% longer than EN, JA 10-25% shorter) +- Freshness tracking (stale translations detected via timestamps) +- Cultural marker scanning (foreign brands, wrong legal references, untranslated elements) + +**Output:** Parity matrix table with per-page scores and prioritized action items. + +## Locale Format Validation + +Load `references/locale-formats.md` for number, date, currency, address, and phone format +reference tables per locale. + +**Checks:** +- Number format consistency (e.g., "1,000.00" should be "1.000,00" on de-DE pages) +- Date format matches locale expectations +- Currency symbols and placement correct for target market +- Phone numbers use international format with correct country code + +## Reference Files + +Load on-demand as needed (do NOT load all at startup): +- `references/cultural-profiles.md`: DACH, Francophone, Hispanic, Japanese cultural adaptation profiles +- `references/locale-formats.md`: Number, date, currency, address, phone format tables per locale +- `references/content-parity.md`: Content parity audit methodology and scoring +- `references/machine-translation-qa.md`: QA flags for machine-translated pages + that lack human review or localized substance + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. | +| No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. | +| Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. | +| Cultural profile not available for language | Use the Default Profile checklist from cultural-profiles.md. Note that assessment is based on general guidelines, not a pre-built profile. | +| Content parity directory empty | Report that no content files were found. Suggest verifying the directory path or providing a URL for live site analysis. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/content-parity.md b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/content-parity.md new file mode 100644 index 00000000..e2bea02c --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/content-parity.md @@ -0,0 +1,87 @@ +# Content Parity Audit for Multi-Language Sites + +Load this reference when auditing content parity across language versions of a site. +Content parity ensures all language versions provide equivalent value and SEO signals. + +Original concept: Chris Muller (Pro Hub Challenge) + +## Content Parity Matrix + +For each page that exists in multiple languages, check: + +| Dimension | What to Compare | Acceptable Variance | Severity if Failing | +|-----------|----------------|--------------------|--------------------| +| Page existence | Does equivalent page exist in all declared languages? | 0% — all declared languages must have the page | High | +| Section structure | Same number of H2/H3 sections? | ±1 section allowed | Medium | +| FAQ items | Same number of FAQ questions? | ±2 items allowed | Medium | +| Images | Same number of images with localized alt text? | Must match exactly | Medium | +| Charts/SVGs | Charts present in all versions? | Must match exactly | Low | +| Word count | Proportional to language expansion ratio? | ±30% of expected ratio | Low | +| Schema markup | JSON-LD present and localized in all versions? | Must match type and key properties | High | +| Title tag | Localized with target keyword in local language? | Must be localized, not English | High | +| Meta description | Localized and within character limits? | Must be localized | Medium | + +## Freshness Tracking + +Detect stale translations by comparing: +1. **File modification timestamps**: If EN version was updated after DE version, DE may be stale +2. **Frontmatter dates**: Compare `date_modified` or `lastmod` across language versions +3. **Content hash comparison**: If the source language content hash changed since last translation + +Freshness delta thresholds: +- **Fresh**: Translated within 7 days of source update → OK +- **Aging**: 8-30 days since source update → Low priority update +- **Stale**: 31-90 days since source update → Medium priority update +- **Outdated**: 90+ days since source update → High priority update + +## Word Count Ratio Validation + +Expected word count ratios vs English source: + +| Target Language | Expected Ratio | Acceptable Range | +|----------------|---------------|-----------------| +| German (DE) | 1.25-1.35x | 1.10-1.50x | +| French (FR) | 1.15-1.25x | 1.00-1.40x | +| Spanish (ES) | 1.15-1.25x | 1.00-1.40x | +| Japanese (JA) | 0.75-0.90x | 0.60-1.00x | +| Chinese (ZH) | 0.70-0.80x | 0.55-0.95x | + +A German translation that is shorter than the English original likely has missing content. +A Japanese translation that is longer than English likely has unnecessary padding. + +## Cultural Adaptation Quality Gates + +Beyond direct translation, check for cultural markers that indicate proper localization: + +| Check | What to Look For | Severity | +|-------|-----------------|----------| +| Foreign brand references | US-specific brands on non-US pages (e.g., "Walmart" on de-DE) | Medium | +| Foreign statistics | US-only data cited on localized pages (e.g., "80% of Americans") | Medium | +| CTA aggressiveness | Aggressive CTAs on formal-culture pages (e.g., "BUY NOW!" on ja-JP) | Low | +| Legal references | Wrong jurisdiction laws cited (e.g., CCPA on de-DE instead of DSGVO) | High | +| Currency/unit mismatch | USD prices on EUR pages, imperial units on metric pages | High | +| Untranslated elements | English text remaining in navigation, buttons, alt text, schema | Medium | + +## Parity Score Calculation + +Score out of 100: +- Page existence parity: 30 points +- SEO element parity (title, meta, schema): 30 points +- Content structure parity (sections, images, FAQ): 25 points +- Freshness parity: 15 points + +Interpretation: +- 90-100: Excellent parity across all language versions +- 70-89: Good parity with minor gaps to address +- 50-69: Significant parity issues affecting some language versions +- Below 50: Major parity failures requiring immediate attention + +## Output Format + +Present as a matrix table: +``` +| Page | EN | DE | FR | ES | JA | Parity Score | +|------|----|----|----|----|----| -------------| +| /about | ✅ | ✅ | ✅ | ❌ | ✅ | 80/100 | +| /pricing | ✅ | ✅ | ⚠️ | ❌ | ❌ | 45/100 | +``` diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/cultural-profiles.md b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/cultural-profiles.md new file mode 100644 index 00000000..361e4809 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/cultural-profiles.md @@ -0,0 +1,91 @@ +# Cultural Adaptation Profiles for International SEO + +Load this reference when analyzing multi-language sites or generating hreflang +implementations. Profiles guide cultural assessment beyond technical validation. + +Original concept: Chris Muller (Pro Hub Challenge) + +## DACH Region (DE, AT, CH) + +| Dimension | Guideline | +|-----------|-----------| +| Formality | High. Use "Sie" (formal you). Professional tone expected. | +| Humor | Conservative. Avoid sarcasm and wordplay in CTAs. | +| CTA Style | Indirect preferred. "Jetzt entdecken" over "Jetzt kaufen". | +| Trust Signals | Certifications (TUV, ISO), "Datenschutz" (privacy), Impressum required by law. | +| Legal | Impressum page mandatory. DSGVO (GDPR). Widerrufsrecht (right of withdrawal). | +| Number Format | 1.000,00 (dot for thousands, comma for decimal) | +| Date Format | DD.MM.YYYY | +| Currency | EUR (DE/AT), CHF (CH) | +| Color Symbolism | Blue = trust, Green = eco/nature, Red = caution (not urgency) | +| Brand Substitution | Walmart → MediaMarkt, Home Depot → Hornbach, Amazon → Otto/Zalando | +| Word Expansion | +25-35% vs English (plan for longer headlines and button text) | + +## Francophone (FR, BE, CA-FR, CH-FR) + +| Dimension | Guideline | +|-----------|-----------| +| Formality | Medium-high. "Vous" default. "Tu" only for youth/casual brands. | +| Humor | Appreciated when sophisticated. Avoid blunt/direct humor. | +| CTA Style | Elegant phrasing. "Decouvrir nos solutions" over "Achetez maintenant". | +| Trust Signals | "Fabrique en France" (made in France), professional certifications, press mentions. | +| Legal | Mentions legales required. CNIL (data protection). CGV (terms). | +| Number Format | 1 000,00 (space for thousands, comma for decimal) | +| Date Format | DD/MM/YYYY | +| Currency | EUR (FR/BE), CAD (CA-FR), CHF (CH-FR) | +| Color Symbolism | Blue = stability, White = purity/luxury, Red = passion | +| Brand Substitution | Walmart → Carrefour, Amazon → Fnac/Cdiscount, Target → Leclerc | +| Word Expansion | +15-25% vs English | + +## Hispanic (ES, LATAM) + +| Dimension | Guideline | +|-----------|-----------| +| Formality | Varies by country. Spain: "Usted" formal. LATAM: mixed. | +| Humor | Warm and relational. Self-deprecating humor accepted. | +| CTA Style | Warm, personal. "Empieza tu viaje" over "Comprar ahora". | +| Trust Signals | Community proof, family/relationship themes, celebrity endorsements popular. | +| Legal | LOPD (Spain data protection). Each LATAM country has own regulations. | +| Number Format | Spain: 1.000,00 / LATAM: varies by country | +| Date Format | DD/MM/YYYY (most), DD-MM-YYYY (some LATAM) | +| Currency | EUR (ES), regional currencies (MXN, ARS, COP, CLP, PEN) | +| Color Symbolism | Red = energy/passion, Yellow = warmth, Blue = trust | +| Brand Substitution | Walmart → Mercadona (ES) / Coppel (MX), Amazon → MercadoLibre | +| Word Expansion | +15-25% vs English | + +## Japanese (JA) + +| Dimension | Guideline | +|-----------|-----------| +| Formality | Very high. Keigo (honorific language) expected in business. | +| Humor | Subtle. Avoid direct humor in B2B. Kawaii (cute) elements acceptable in B2C. | +| CTA Style | Subtle and polite. "Otoiawase" (inquire) over direct "buy now". | +| Trust Signals | Company longevity, ISO certifications, endorsements from recognized institutions. | +| Legal | APPI (Act on Protection of Personal Information). Tokutei Shotorihiki law. | +| Number Format | 1,000 (comma for thousands, no decimal in most contexts) | +| Date Format | YYYY/MM/DD or YYYY年MM月DD日 | +| Currency | JPY (no decimals) | +| Color Symbolism | White = purity, Red = vitality/celebration, Black = formality | +| Brand Substitution | Amazon → Rakuten, Google Shopping → Yahoo! Shopping Japan | +| Word Contraction | -10-25% vs English (Japanese is more compact) | + +## Default Profile (Unlisted Languages) + +When analyzing a locale without a pre-built profile above: + +1. **Research formality norms**: Check if the language has formal/informal registers (e.g., Korean has 7 speech levels) +2. **Check text direction**: LTR vs RTL (Arabic, Hebrew, Farsi, Urdu) +3. **Verify number/date formats**: Use CLDR (Unicode Common Locale Data Repository) +4. **Research legal requirements**: Privacy law, business registration, consumer protection +5. **Check word expansion ratio**: Germanic/Slavic languages expand, CJK languages contract +6. **Verify currency and payment preferences**: Local payment methods may need mention +7. **Research color meanings**: Colors have different cultural associations globally + +## How to Use in Analysis + +When running `/seo hreflang` on a multi-language site: +1. Identify all language versions and their target markets +2. Load the relevant cultural profile(s) +3. Check that CTAs, trust signals, and legal pages match the cultural expectations +4. Flag mismatches as "Cultural Adaptation" findings (Medium severity) +5. Check number/date/currency formatting consistency within each locale version diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/locale-formats.md b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/locale-formats.md new file mode 100644 index 00000000..6bfb511a --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/locale-formats.md @@ -0,0 +1,100 @@ +# Locale Format Reference for International SEO + +Load this reference when validating content parity or generating localized content. +Mismatched formats (e.g., US date format on a German page) signal poor localization +and reduce user trust. + +Original concept: Chris Muller (Pro Hub Challenge) + +## Number Formats + +| Locale | Thousands | Decimal | Example | +|--------|-----------|---------|---------| +| en-US | , | . | 1,234.56 | +| en-GB | , | . | 1,234.56 | +| de-DE | . | , | 1.234,56 | +| de-AT | . | , | 1.234,56 | +| de-CH | ' | . | 1'234.56 | +| fr-FR | (space) | , | 1 234,56 | +| fr-CA | (space) | , | 1 234,56 | +| es-ES | . | , | 1.234,56 | +| es-MX | , | . | 1,234.56 | +| ja-JP | , | . | 1,234 | +| pt-BR | . | , | 1.234,56 | +| it-IT | . | , | 1.234,56 | +| nl-NL | . | , | 1.234,56 | +| ko-KR | , | . | 1,234 | +| zh-CN | , | . | 1,234.56 | + +## Date Formats + +| Locale | Format | Example | +|--------|--------|---------| +| en-US | MM/DD/YYYY | 04/14/2026 | +| en-GB | DD/MM/YYYY | 14/04/2026 | +| de-DE | DD.MM.YYYY | 14.04.2026 | +| fr-FR | DD/MM/YYYY | 14/04/2026 | +| es-ES | DD/MM/YYYY | 14/04/2026 | +| ja-JP | YYYY/MM/DD or YYYY年MM月DD日 | 2026/04/14 | +| pt-BR | DD/MM/YYYY | 14/04/2026 | +| ko-KR | YYYY.MM.DD | 2026.04.14 | +| zh-CN | YYYY年MM月DD日 | 2026年04月14日 | + +## Currency Formats + +| Locale | Symbol | Placement | Example | +|--------|--------|-----------|---------| +| en-US | $ | Before | $1,234.56 | +| en-GB | £ | Before | £1,234.56 | +| de-DE | € | After (space) | 1.234,56 € | +| fr-FR | € | After (space) | 1 234,56 € | +| es-ES | € | After (space) | 1.234,56 € | +| ja-JP | ¥ | Before | ¥1,234 | +| pt-BR | R$ | Before | R$ 1.234,56 | +| ko-KR | ₩ | Before | ₩1,234 | +| zh-CN | ¥ | Before | ¥1,234.56 | +| de-CH | CHF | Before | CHF 1'234.56 | + +## Address Formats + +| Region | Order | Example | +|--------|-------|---------| +| US/CA | Street, City, State ZIP | 123 Main St, Austin, TX 78701 | +| UK | Street, City, Postcode | 10 Downing St, London, SW1A 2AA | +| DE/AT | Street Nr, PLZ City | Hauptstr. 1, 10115 Berlin | +| FR | Street, Code Postal City | 1 Rue de Rivoli, 75001 Paris | +| JP | Postal City District Street | 〒100-0001 東京都千代田区千代田1-1 | + +## Phone Formats + +| Region | Format | Example | +|--------|--------|---------| +| US | +1 (XXX) XXX-XXXX | +1 (512) 555-0123 | +| UK | +44 XXXX XXXXXX | +44 2071 234567 | +| DE | +49 XXX XXXXXXX | +49 30 12345678 | +| FR | +33 X XX XX XX XX | +33 1 23 45 67 89 | +| JP | +81 X-XXXX-XXXX | +81 3-1234-5678 | + +## Text Expansion Ratios (vs English) + +| Language | Expansion | Impact | +|----------|-----------|--------| +| German | +25-35% | Longer headlines, buttons, navigation labels | +| French | +15-25% | Moderate expansion | +| Spanish | +15-25% | Moderate expansion | +| Italian | +15-25% | Moderate expansion | +| Portuguese | +15-25% | Moderate expansion | +| Dutch | +10-20% | Slight expansion | +| Japanese | -10-25% | Contraction (more compact) | +| Korean | -10-20% | Contraction | +| Chinese | -20-30% | Significant contraction | + +## Validation Rules + +When checking locale format consistency: +1. Scan for number patterns on the page (prices, statistics, measurements) +2. Compare against the expected format for the page's declared language +3. Flag US-format numbers on non-US pages (e.g., "$1,234.56" on a de-DE page) +4. Check date formats in blog posts, copyright notices, update timestamps +5. Verify currency symbols match the target market +6. Check that phone numbers use international format with correct country code diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/machine-translation-qa.md b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/machine-translation-qa.md new file mode 100644 index 00000000..75ff2937 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-hreflang/references/machine-translation-qa.md @@ -0,0 +1,53 @@ +# Machine-translation QA flag (Jan 2025 QRG) + +Google's January 23, 2025 Quality Rater Guidelines update added +explicit language about **machine-translated content with no human +review** as a form of scaled content abuse (§4.6.5). + +> "Using automated tools (generative AI or otherwise) as a low-effort +> way to produce many pages that add little-to-no value." + +Machine-translated content is fine **when reviewed by a human +speaker and corrected**. Untranslated MT — or "lightly post-edited" +output that still contains hallucinated terms, wrong gender/number +agreement, or untranslated proper nouns — is treated as scaled +content abuse. + +## Signals the seo-hreflang audit should surface + +| Signal | Severity | Notes | +|---|---|---| +| Multiple `hreflang` alternates point to URLs whose content is identical except for header chrome | Critical | Indicates the body wasn't translated; just template wrapped. | +| `lang="xx"` attribute on `` doesn't match the body language | High | Translation pipeline output without a final QA step. | +| Auto-translated `` longer than 160 chars (untrimmed) | Medium | The translator overran the snippet limit — no human reviewer caught it. | +| `lang` attribute is `auto` or missing entirely | Medium | Pages that don't declare their language confuse hreflang + AI crawlers. | +| Untranslated proper nouns or product names sprinkled in body | Low (heuristic) | Common MT failure mode; hard to detect automatically. | +| Schema.org `inLanguage` field absent or wrong | Medium | Multi-language audits should cross-check `inLanguage` vs. body. | + +## What the audit should NOT flag + +- Sites that have a few MT pages clearly labelled as MT (a + human-translation-fallback pattern). Google's QRG explicitly + permits MT *when honestly labelled and clearly scoped*. +- Machine-translated UI strings — those are i18n, not "content". +- Content with `lang="auto"` if the audit can't fetch a fallback + signal (be conservative; don't claim what we can't verify). + +## Cross-skill delegation + +- For per-page hreflang validation, stay inside `seo-hreflang`. +- For broader scaled-content scoring (entropy of translated pages, + AI-pattern detection in body), defer to `seo-content` via + `python3 scripts/content_quality.py`. +- For "is this translated by Google's own auto-translate widget" + detection, look for the `.goog-te-banner-frame` iframe; auto- + translate widgets are explicitly exempted from MT-scaled-content + abuse but produce poor passage-citability anyway. + +## Primary sources + +- Jan 2025 QRG §4.6.5: https://services.google.com/fh/files/misc/hsw-sqrg.pdf +- John Mueller on MT (multiple SOTR episodes, 2024-2025): MT is OK + when reviewed by a human; bulk MT without review is abuse. + +Last verified: 2026-05-17. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/SKILL.md new file mode 100644 index 00000000..5f813b43 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/SKILL.md @@ -0,0 +1,176 @@ +--- +name: seo-image-gen +description: "AI image generation for SEO assets: OG/social preview images, blog hero images, schema images, product photography, infographics. Powered by Gemini via nanobanana-mcp. Requires banana extension installed. Use when user says \"generate image\", \"OG image\", \"social preview\", \"hero image\", \"blog image\", \"product photo\", \"infographic\", \"seo image\", \"create visual\", \"image-gen\", \"favicon\", \"schema image\", \"pinterest pin\", \"generate visual\", \"banner\", or \"thumbnail\"." +argument-hint: "[og|hero|product|infographic|custom|batch] " +user-invocable: true +license: MIT +compatibility: "Requires nanobanana MCP server" +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# SEO Image Gen: AI Image Generation for SEO Assets (Extension) + +Generate production-ready images for SEO use cases using Gemini's image generation +via the banana Creative Director pipeline. Maps SEO needs to optimized domain modes, +aspect ratios, and resolution defaults. + +## Architecture Note + +This extension is built on [Claude Banana](https://github.com/AgriciDaniel/banana-claude), +the standalone AI image generation skill for Claude Code. + +This skill has two components with distinct roles: +- **SKILL.md** (this file): Handles interactive `/seo image-gen` commands for generating images +- **Agent** (`agents/seo-image-gen.md`): Audit-only analyst spawned during `/seo audit` to assess existing OG/social images and produce a generation plan (never auto-generates) + +## Prerequisites + +This skill requires the banana extension to be installed: +```bash +./extensions/banana/install.sh +``` + +**Check availability:** Before using any image generation tool, verify the MCP server +is connected by checking if `gemini_generate_image` or `set_aspect_ratio` tools are +available. If tools are not available, inform the user the extension is not installed +and provide install instructions. + +## Quick Reference + +| Command | What it does | +|---------|-------------| +| `/seo image-gen og ` | Generate OG/social preview image (1200x630 feel) | +| `/seo image-gen hero ` | Blog hero image (widescreen, dramatic) | +| `/seo image-gen product ` | Product photography (clean, white BG) | +| `/seo image-gen infographic ` | Infographic visual (vertical, data-heavy) | +| `/seo image-gen custom ` | Custom image with full Creative Director pipeline | +| `/seo image-gen batch [N]` | Generate N variations (default: 3) | + +## SEO Image Use Cases + +Each use case maps to pre-configured banana parameters: + +| Use Case | Aspect Ratio | Resolution | Domain Mode | Notes | +|----------|-------------|------------|-------------|-------| +| **OG/Social Preview** | `16:9` | `1K` | Product or UI/Web | Clean, professional, text-friendly | +| **Blog Hero** | `16:9` | `2K` | Cinema or Editorial | Dramatic, atmospheric, editorial quality | +| **Schema Image** | `4:3` | `1K` | Product | Clean, descriptive, schema ImageObject | +| **Social Square** | `1:1` | `1K` | UI/Web | Platform-optimized square | +| **Product Photo** | `4:3` | `2K` | Product | White background, studio lighting | +| **Infographic** | `2:3` | `4K` | Infographic | Data-heavy, vertical layout | +| **Favicon/Icon** | `1:1` | `512` | Logo | Minimal, scalable, recognizable | +| **Pinterest Pin** | `2:3` | `2K` | Editorial | Tall vertical card | + +## Generation Pipeline + +For every generation request: + +1. **Identify use case** from command or context (og, hero, product, etc.) +2. **Apply SEO defaults** from the use cases table above +3. **Set aspect ratio** via `set_aspect_ratio` MCP tool +4. **Construct Reasoning Brief** using the banana Creative Director pipeline: + - Load `references/prompt-engineering.md` for the 6-component system + - Apply domain mode emphasis (Subject 30%, Style 25%, Context 15%, etc.) + - Be SPECIFIC and VISCERAL: describe what the camera sees +5. **Generate** via `gemini_generate_image` MCP tool +6. **Post-generation SEO checklist** (see below) + +### Check for Presets + +If the user mentions a brand or has SEO presets configured: +```bash +python3 scripts/presets.py list +``` +Load matching preset and apply as defaults. Also check `references/seo-image-presets.md` +for SEO-specific preset templates. + +## Post-Generation SEO Checklist + +After every successful generation, guide the user on: + +1. **Alt text**:Write descriptive, keyword-rich alt text for the generated image +2. **File naming**:Rename to SEO-friendly format: `keyword-description-widthxheight.webp` +3. **WebP conversion**:Convert to WebP for optimal page speed: + ```bash + magick output.png -quality 85 output.webp + ``` +4. **File size**:Target under 200KB for hero images, under 100KB for thumbnails +5. **Schema markup**:Suggest `ImageObject` schema for the generated image: + ```json + { + "@type": "ImageObject", + "url": "https://example.com/images/keyword-description.webp", + "width": 1200, + "height": 630, + "caption": "Descriptive caption with target keyword" + } + ``` +6. **OG meta tags**:For social preview images, remind about: + ```html + + + + + ``` + +## Cost Awareness + +Image generation costs money. Be transparent: +- Show estimated cost before generating (especially for batch) +- Log every generation: `python3 scripts/cost_tracker.py log --model MODEL --resolution RES --prompt "brief"` +- Run `cost_tracker.py summary` if user asks about usage + +Approximate costs (gemini-3.1-flash): +- 512: ~$0.02/image +- 1K resolution: ~$0.04/image +- 2K resolution: ~$0.08/image +- 4K resolution: ~$0.16/image + +## Model Routing + +| Scenario | Model | Why | +|----------|-------|-----| +| OG images, social previews | `gemini-3.1-flash-image-preview` @ 1K | Fast, cost-effective | +| Hero images, product photos | `gemini-3.1-flash-image-preview` @ 2K | Quality + detail | +| Infographics with text | `gemini-3.1-flash-image-preview` @ 2K, thinking: high | Better text rendering | +| Quick drafts | `gemini-2.5-flash-image` @ 512 | Rapid iteration | + +## Error Handling + +| Error | Resolution | +|-------|-----------| +| MCP not configured | Run `./extensions/banana/install.sh` | +| API key invalid | New key at https://aistudio.google.com/apikey | +| Rate limited (429) | Wait 60s, retry. Free tier: ~10 RPM / ~500 RPD | +| `IMAGE_SAFETY` | Rephrase prompt - see `references/prompt-engineering.md` Safety section | +| MCP unavailable | Fall back: `python3 scripts/generate.py --prompt "..." --aspect-ratio "16:9"` | +| Extension not installed | Show install instructions: `./extensions/banana/install.sh` | + +## Cross-Skill Integration + +- **seo-images** (analysis) feeds into **seo-image-gen** (generation): audit results from `/seo images` identify missing or low-quality images; use those findings to drive `/seo image-gen` commands +- **seo-audit** spawns the seo-image-gen **agent** (not this skill) to analyze OG/social images across the site and produce a prioritized generation plan +- **seo-schema** can consume generated images: after generation, suggest `ImageObject` schema markup pointing to the new assets + +## Reference Documentation + +Load on-demand. Do NOT load all at startup: +- `references/prompt-engineering.md`:6-component system, domain modes, templates +- `references/gemini-models.md`:Model specs, rate limits, capabilities +- `references/mcp-tools.md`:MCP tool parameters and responses +- `references/post-processing.md`:ImageMagick/FFmpeg pipeline recipes +- `references/cost-tracking.md`:Pricing, usage tracking +- `references/presets.md`:Brand preset management +- `references/seo-image-presets.md`:SEO-specific preset templates + +## Response Format + +After generating, always provide: +1. **Image path**:where it was saved +2. **Crafted prompt**:show what was sent to the API (educational) +3. **Settings**:model, aspect ratio, resolution +4. **SEO checklist**:alt text suggestion, file naming, WebP conversion +5. **Schema snippet**:ImageObject or og:image markup if applicable diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/cost-tracking.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/cost-tracking.md new file mode 100644 index 00000000..80e89d43 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/cost-tracking.md @@ -0,0 +1,47 @@ +# Cost Tracking Reference + +> Load this on-demand when the user asks about costs or before batch operations. + +## Pricing Table + +| Model | Resolution | Cost/Image | Notes | +|-------|-----------|-----------|-------| +| 3.1 Flash | 512 | $0.020 | Quick drafts | +| 3.1 Flash | 1K | $0.039 | Standard (default) | +| 3.1 Flash | 2K | $0.078 | Quality assets | +| 3.1 Flash | 4K | $0.156 | Print/hero images | +| 2.5 Flash | 512 | $0.020 | Draft fallback | +| 2.5 Flash | 1K | $0.039 | Standard fallback | +| Batch API | Any | 50% of above | Asynchronous, higher latency | + +Pricing is approximate, based on ~1,290 output tokens per image. +Research suggests actual costs may be ~$0.067/img. Verify at https://ai.google.dev/gemini-api/docs/pricing + +## Free Tier Limits + +- ~10 requests per minute (RPM) +- ~500 requests per day (RPD) +- Per Google Cloud project, resets midnight Pacific + +## Cost Tracker Commands + +```bash +# Log a generation +cost_tracker.py log --model gemini-3.1-flash-image-preview --resolution 1K --prompt "coffee shop hero" + +# View summary (total + last 7 days) +cost_tracker.py summary + +# Today's usage +cost_tracker.py today + +# Estimate before batch +cost_tracker.py estimate --model gemini-3.1-flash-image-preview --resolution 1K --count 10 + +# Reset ledger +cost_tracker.py reset --confirm +``` + +## Storage + +Ledger stored at `~/.banana/costs.json`. Created automatically on first use. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/gemini-models.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/gemini-models.md new file mode 100644 index 00000000..513de9f4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/gemini-models.md @@ -0,0 +1,200 @@ +# Gemini Image Generation Models + +> Last updated: 2026-03-13 +> Aligned with Google's March 2026 API state + +## Available Models + +### gemini-3.1-flash-image-preview (Recommended) +| Property | Value | +|----------|-------| +| **Model ID** | `gemini-3.1-flash-image-preview` | +| **Tier** | Nano Banana 2 (Flash) | +| **Speed** | Fast - optimized for high-volume use | +| **Aspect Ratios** | All 14 ratios (see table below) | +| **Max Resolution** | Up to 4096×4096 (4K tier) | +| **Features** | Google Search grounding (web + image), thinking levels, image-only output, extreme aspect ratios | +| **Rate Limits (Free)** | ~10 RPM / ~500 RPD (per Google Cloud project, resets midnight Pacific) | +| **Output Tokens** | ~1,290 output tokens per image | +| **Best For** | Most use cases, rapid iteration, batch generation | + +### gemini-2.5-flash-image +| Property | Value | +|----------|-------| +| **Model ID** | `gemini-2.5-flash-image` | +| **Tier** | Nano Banana 2 (Flash, previous gen) | +| **Speed** | Fast | +| **Aspect Ratios** | 1:1, 16:9, 9:16, 4:3, 3:4 | +| **Max Resolution** | Up to 1024×1024 (1K tier) | +| **Rate Limits (Free)** | ~10 RPM / ~500 RPD | +| **Best For** | Stable fallback, proven quality | + +## Deprecated Models (DO NOT USE) + +### gemini-3-pro-image-preview +- **Status:** Base model deprecated March 9, 2026. **Image generation variant may still be accessible**. Use at your own discretion via `set_model`. Prefer 3.1 Flash. +- **Was:** Nano Banana Pro tier (professional asset production, 4K output, 14 reference images) +- **Migration:** Use `gemini-3.1-flash-image-preview` instead + +### gemini-2.0-flash-exp +- **Status:** Deprecated, replaced by gemini-2.5-flash-image + +## Aspect Ratios + +All 14 supported ratios. Availability varies by model: + +| Ratio | Orientation | Use Cases | 3.1 Flash | 2.5 Flash | +|-------|-------------|-----------|:---------:|:---------:| +| `1:1` | Square | Social posts, avatars, thumbnails | ✅ | ✅ | +| `16:9` | Landscape | Blog headers, YouTube thumbnails, presentations | ✅ | ✅ | +| `9:16` | Portrait | Stories, Reels, TikTok, mobile | ✅ | ✅ | +| `4:3` | Landscape | Product shots, classic display | ✅ | ✅ | +| `3:4` | Portrait | Book covers, portrait framing | ✅ | ✅ | +| `2:3` | Portrait | Pinterest pins, posters | ✅ | ❌ | +| `3:2` | Landscape | DSLR standard, photo prints | ✅ | ❌ | +| `4:5` | Portrait | Instagram portrait, social | ✅ | ❌ | +| `5:4` | Landscape | Large format photography | ✅ | ❌ | +| `1:4` | Tall strip | Vertical banners, side panels | ✅ | ❌ | +| `4:1` | Wide strip | Website banners, headers | ✅ | ❌ | +| `1:8` | Extreme tall | Narrow vertical strips | ✅ | ❌ | +| `8:1` | Extreme wide | Ultra-wide banners | ✅ | ❌ | +| `21:9` | Ultra-wide | Cinematic, film-grade, ultra-wide monitors | ✅ | ❌ | + +## Resolution Tiers + +Control output resolution with the `imageSize` parameter. Note the **uppercase K** requirement. + +| `imageSize` Value | Pixel Range | Model Availability | Use Case | +|-------------------|-------------|-------------------|----------| +| `512` | Up to 512×512 | All models | Drafts, quick iteration, low bandwidth | +| `1K` (default) | Up to 1024×1024 | All models | Standard web use, social media | +| `2K` | Up to 2048×2048 | 3.1 Flash | Quality assets, detailed work | +| `4K` | Up to 4096×4096 | 3.1 Flash | Print production, hero images, final assets | + +**Notes:** +- Actual pixel dimensions depend on aspect ratio (e.g., 4K at 16:9 = 4096×2304) +- Higher resolutions consume more tokens and cost more +- Default is `1K` if `imageSize` is not specified + +## API Configuration + +### Endpoint +``` +https://generativelanguage.googleapis.com/v1beta/models/{model-id}:generateContent +``` + +### Required Parameters +```json +{ + "contents": [{"parts": [{"text": "your prompt here"}]}], + "generationConfig": { + "responseModalities": ["TEXT", "IMAGE"], + "imageConfig": { + "aspectRatio": "16:9", + "imageSize": "1K" + } + } +} +``` + +### Image-Only Output Mode +Force the model to return only an image (no text response): +```json +{ + "generationConfig": { + "responseModalities": ["IMAGE"] + } +} +``` + +### Thinking Level +Control how much the model "thinks" before generating. Higher levels improve complex compositions but increase latency: +```json +{ + "generationConfig": { + "thinkingConfig": { + "thinkingLevel": "medium" + } + } +} +``` +Levels: `minimal`, `low`, `medium`, `high` + +### Google Search Grounding +Ground generation in real-world visual references. Supports web and image search (3.1 Flash): +```json +{ + "tools": [{"googleSearch": {}}] +} +``` +**Prompt pattern:** `[Search/source request] + [Analytical task] + [Visual translation]` + +Example: "Search for the latest SpaceX Starship design, analyze its proportions and markings, then generate a photorealistic image of it at sunset on the launch pad." + +### Multi-Image Input +Up to 14 reference images can be provided: +- **10 object references**: for style, composition, or visual matching +- **4 character references**: assign distinct names to preserve features across generations + +Useful for character consistency, style transfer, and brand-aligned generation. + +## Rate Limits by Tier + +| Tier | RPM | RPD | Notes | +|------|-----|-----|-------| +| Free | ~10 | ~500 | Per Google Cloud project, resets midnight Pacific. Reduced Dec 2025. | +| Pay-as-you-go | 30 | 10,000 | Production workloads | +| Enterprise | Custom | Custom | Contact Google | + +## Pricing + +| Model | Resolution | Cost per Image | Notes | +|-------|-----------|---------------|-------| +| 3.1 Flash | 1K | ~$0.039 | Standard | +| 3.1 Flash | 2K | ~$0.078 | 2× standard | +| 3.1 Flash | 4K | ~$0.156 | 4× standard | +| 2.5 Flash | 1K | ~$0.039 | Standard | +| Batch API | Any | 50% discount | Asynchronous, higher latency | + +Pricing is approximate and based on ~1,290 output tokens per image. +Research suggests NB2 pricing may be ~$0.067/img (vs documented $0.039). Verify current pricing at https://ai.google.dev/gemini-api/docs/pricing + +## Image Output Specs + +| Property | Value | +|----------|-------| +| **Format** | PNG | +| **Max Resolution** | Up to 4096×4096 (4K tier, 3.1 Flash) | +| **Color Space** | sRGB | +| **Text Rendering** | Supported - best under 25 characters | +| **Style Control** | Via prompt engineering | + +## Safety Filters + +Gemini uses a two-layer safety architecture: + +1. **Input filters**: block prompts containing prohibited content before generation +2. **Output filters**: analyze generated images and block unsafe results + +| `finishReason` | Meaning | Retryable? | +|----------------|---------|:----------:| +| `STOP` | Successful generation | N/A | +| `IMAGE_SAFETY` | Output blocked by safety filter | Rephrase prompt | +| `PROHIBITED_CONTENT` | Content policy violation | No - topic is blocked | +| `SAFETY` | General safety block | Rephrase prompt | +| `RECITATION` | Detected copyrighted content | Rephrase prompt | + +**Known issue:** Filters are known to be overly cautious. Benign prompts may be blocked. Iterate with rephrased wording if this happens. + +## Content Credentials + +- **SynthID watermarks** are always embedded in generated images (invisible, machine-readable) +- **C2PA metadata** is included on Pro/paid outputs (verifiable provenance chain) + +## Key Limitations +- No video generation (image only) +- No transparent backgrounds (PNG but always with background) +- Text rendering quality varies; keep text under 25 characters for best results +- Safety filters may block some prompts (violence, NSFW, public figures), known to be overly cautious +- Session context resets between Claude Code conversations +- `imageSize` and thinking level depend on MCP package version support diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/mcp-tools.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/mcp-tools.md new file mode 100644 index 00000000..5499ad74 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/mcp-tools.md @@ -0,0 +1,115 @@ +# MCP Tools Reference: @ycse/nanobanana-mcp + +> Package: `@ycse/nanobanana-mcp` +> GitHub: https://github.com/YCSE/nanobanana-mcp + +## Tools + +### gemini_generate_image +Generate an image from a text prompt. + +**Parameters:** +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `prompt` | string | Yes | Text description of the image to generate | + +**Returns:** Image data + file path (saved to `~/Documents/nanobanana_generated/`) + +**Example usage in Claude Code:** +``` +User: "Generate a sunset over mountains in watercolor style" +→ Claude calls gemini_generate_image with prompt +→ Returns image path and description +``` + +### gemini_edit_image +Edit an existing image with text instructions. + +**Parameters:** +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `imagePath` | string | Yes | Path to the image file to edit | +| `prompt` | string | Yes | Edit instructions | + +**Returns:** Modified image data + file path + +**Example:** +``` +User: "Remove the background from ~/Documents/photo.png" +→ Claude calls gemini_edit_image with path and instruction +``` + +### gemini_chat +Multi-turn visual conversation maintaining session context. + +**Parameters:** +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `message` | string | Yes | Chat message (can reference previous images) | + +**Returns:** Text response + optional image + +**Key feature:** Session consistency, which maintains style, characters, and context across turns. Great for iterative refinement. + +### set_aspect_ratio +Configure the aspect ratio for subsequent image generations. + +**Parameters:** +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `ratio` | string | Yes | Aspect ratio (e.g., "16:9", "1:1", "9:16") | + +**Supported ratios:** 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 1:4, 4:1, 1:8, 8:1, 21:9 + +### set_model +Switch the active Gemini model. + +**Parameters:** +| Param | Type | Required | Description | +|-------|------|----------|-------------| +| `model` | string | Yes | Model identifier | + +**Available models:** +- `gemini-3.1-flash-image-preview` (default, recommended) +- `gemini-2.5-flash-image` (stable fallback) + +### get_image_history +Retrieve list of images generated in the current session. + +**Parameters:** None + +**Returns:** Array of image entries with paths and prompts + +### clear_conversation +Reset session context and conversation history. + +**Parameters:** None + +**Returns:** Confirmation of reset + +## Environment Variables + +| Variable | Required | Description | +|----------|----------|-------------| +| `GOOGLE_AI_API_KEY` | Yes | API key from https://aistudio.google.com/apikey | +| `NANOBANANA_MODEL` | No | Override default model (default: `gemini-3.1-flash-image-preview`) | + +## Output Directory +All generated images are saved to: `~/Documents/nanobanana_generated/` + +Images are named with timestamps for easy identification. + +## Feature Availability via MCP + +Some newer Gemini API features depend on the MCP package version of `@ycse/nanobanana-mcp`. Check the package version to confirm support: + +| Feature | API Status | MCP Support | +|---------|-----------|-------------| +| `imageSize` (resolution control) | Available | Depends on package version | +| Thinking level (`thinkingConfig`) | Available | Depends on package version | +| Search grounding (`googleSearch`) | Available | Depends on package version | +| Image-only output (`responseModalities: ["IMAGE"]`) | Available | Depends on package version | +| Multi-image input (up to 14 refs) | Available | Via `gemini_chat` with image paths | +| All 14 aspect ratios | Available | Via `set_aspect_ratio` | + +If a feature is not yet supported by the MCP package, you can still use it via direct API calls with `curl` or the Google AI SDK. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/post-processing.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/post-processing.md new file mode 100644 index 00000000..0b4d07da --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/post-processing.md @@ -0,0 +1,192 @@ +# Post-Processing Pipeline Reference + +> Load this on-demand when the user needs image manipulation after generation. + +## Prerequisites + +Check availability before using: +```bash +which magick # ImageMagick 7 (preferred) +which convert # ImageMagick 6 (fallback) +which ffmpeg # For video/animation +``` + +Install ImageMagick if not present: `sudo apt install imagemagick` (Debian/Ubuntu) or `brew install imagemagick` (macOS). + +## Common Operations + +### Resize for Platforms + +```bash +# Instagram post (1080x1080) +magick input.png -resize 1080x1080^ -gravity center -extent 1080x1080 instagram.png + +# Twitter/X header (1500x500) +magick input.png -resize 1500x500^ -gravity center -extent 1500x500 twitter-header.png + +# YouTube thumbnail (1280x720) +magick input.png -resize 1280x720^ -gravity center -extent 1280x720 youtube-thumb.png + +# LinkedIn banner (1584x396) +magick input.png -resize 1584x396^ -gravity center -extent 1584x396 linkedin-banner.png + +# Favicon (multi-size ICO) +magick input.png -resize 32x32 favicon.ico +``` + +### Background Removal (Transparency) + +```bash +# Remove solid white background +magick input.png -fuzz 10% -transparent white output.png + +# Remove solid color background (specify color) +magick input.png -fuzz 15% -transparent "#F0F0F0" output.png + +# Clean edges after transparency (anti-alias) +magick input.png -fuzz 10% -transparent white -channel A -blur 0x1 -level 50%,100% output.png + +# Auto-crop transparent padding +magick input.png -trim +repage output.png +``` + +### Format Conversion + +```bash +# PNG to WebP (web-optimized, smaller file) +magick input.png -quality 85 output.webp + +# PNG to JPEG (with white background for transparency) +magick input.png -background white -flatten -quality 90 output.jpg + +# PNG to AVIF (modern, smallest size) +magick input.png -quality 80 output.avif + +# SVG trace (for logos; requires potrace) +potrace input.pbm -s -o output.svg +``` + +### Color Adjustments + +```bash +# Increase contrast +magick input.png -contrast-stretch 2%x1% output.png + +# Warm color temperature +magick input.png -modulate 100,110,105 output.png + +# Cool color temperature +magick input.png -modulate 100,90,95 output.png + +# Desaturate (muted colors) +magick input.png -modulate 100,70,100 output.png + +# Convert to grayscale +magick input.png -colorspace Gray output.png + +# Sepia tone +magick input.png -sepia-tone 80% output.png +``` + +### Compositing + +```bash +# Overlay watermark (bottom-right, 20% opacity) +magick base.png watermark.png -gravity southeast -geometry +20+20 \ + -compose dissolve -define compose:args=20 -composite output.png + +# Side-by-side comparison +magick input1.png input2.png +append comparison.png + +# Vertical stack +magick input1.png input2.png -append stack.png + +# Add padding/border +magick input.png -bordercolor white -border 40 output.png + +# Add rounded corners +magick input.png \( +clone -alpha extract -draw \ + "roundrectangle 0,0,%[fx:w-1],%[fx:h-1],20,20" \) \ + -alpha off -compose CopyOpacity -composite rounded.png +``` + +### Batch Processing + +```bash +# Resize all PNGs in directory +for f in ~/Documents/nanobanana_generated/*.png; do + magick "$f" -resize 800x800 "${f%.png}_thumb.png" +done + +# Convert all to WebP +for f in ~/Documents/nanobanana_generated/*.png; do + magick "$f" -quality 85 "${f%.png}.webp" +done +``` + +## Animation (GIF/Video from Multiple Frames) + +```bash +# Create GIF from multiple images +magick -delay 100 frame1.png frame2.png frame3.png animation.gif + +# Create MP4 from image sequence +ffmpeg -framerate 1 -pattern_type glob -i '*.png' \ + -c:v libx264 -pix_fmt yuv420p slideshow.mp4 +``` + +## Note on 4K Output + +With Gemini 3.1 Flash's `imageSize: "4K"` option (up to 4096×4096), many traditional +upscaling post-processing steps are no longer necessary. If your target platform accepts +images at or below 4K resolution, generate at native 4K instead of generating at 1K +and upscaling. This produces better detail and avoids upscaling artifacts. + +## Green Screen Transparency Pipeline + +Gemini cannot generate transparent backgrounds. Use this workaround: + +### 1. Generate with green screen prompt + +Append to any prompt: +``` +on a solid bright green (#00FF00) chroma key background +with a thin white outline separating the subject from the background +``` + +### 2. Remove green screen (ImageMagick) + +```bash +magick input.png -fuzz 20% -transparent "#00FF00" output.png +``` + +### 3. Clean edges + trim (ImageMagick) + +```bash +magick output.png -channel A -blur 0x1 -level 50%,100% -trim +repage final.png +``` + +### 4. Alternative (FFmpeg, better for batch) + +```bash +ffmpeg -i input.png -vf "colorkey=0x00FF00:0.3:0.1,despill=type=green" -pix_fmt rgba output.png +``` + +### Tips +- `-fuzz 20%` handles slight color variations at edges; increase to 25% for softer edges +- The white outline in the prompt helps prevent color spill on subject edges +- For batch processing, the FFmpeg approach is faster and handles despill automatically +- Always verify edges after conversion; may need manual touchup for hair/fur + +## Quality Assessment + +```bash +# Get image dimensions and info +magick identify -verbose input.png | head -20 + +# Check file size +ls -lh input.png + +# Get exact pixel dimensions +magick identify -format "%wx%h" input.png +``` diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/presets.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/presets.md new file mode 100644 index 00000000..2b6df0bb --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/presets.md @@ -0,0 +1,69 @@ +# Brand/Style Presets Reference + +> Load this on-demand when the user asks about presets or brand consistency. + +## Preset Schema + +Each preset is stored as `~/.banana/presets/NAME.json`: + +```json +{ + "name": "tech-saas", + "description": "Clean tech SaaS brand", + "colors": ["#2563EB", "#1E40AF", "#F8FAFC"], + "style": "clean minimal tech illustration, flat vectors, soft shadows", + "typography": "bold geometric sans-serif", + "lighting": "bright diffused studio, no harsh shadows", + "mood": "professional, trustworthy, modern", + "default_ratio": "16:9", + "default_resolution": "2K" +} +``` + +## Example Presets + +### tech-saas +- **Colors:** #2563EB, #1E40AF, #F8FAFC (blue + white) +- **Style:** Clean minimal tech illustration, flat vectors, soft shadows +- **Typography:** Bold geometric sans-serif +- **Mood:** Professional, trustworthy, modern + +### luxury-brand +- **Colors:** #1A1A1A, #C9A96E, #FAFAF5 (black + gold + cream) +- **Style:** Elegant high-end photography, rich textures, deep contrast +- **Typography:** Thin elegant serif, generous letter-spacing +- **Mood:** Exclusive, sophisticated, aspirational + +### editorial-magazine +- **Colors:** #000000, #FFFFFF, #FF3B30 (black + white + accent red) +- **Style:** Bold editorial photography, strong geometric composition +- **Typography:** Condensed all-caps sans-serif headlines +- **Mood:** Bold, provocative, contemporary + +## How Presets Merge into Reasoning Brief + +When a preset is active, Claude uses its values as defaults for the Reasoning Brief: +1. **Colors** → inform palette descriptions in Context and Style components +2. **Style** → becomes the base for the Style component +3. **Typography** → used for any text rendering +4. **Lighting** → becomes the base for the Lighting component +5. **Mood** → influences Action and Context components + +User instructions always override preset values. If a user says "make it dark" +but the preset has bright lighting, follow the user's instruction. + +## Managing Presets + +```bash +# List presets +presets.py list + +# Show details +presets.py show tech-saas + +# Create interactively (Claude fills in details from conversation) +presets.py create NAME --colors "#hex,#hex" --style "..." --mood "..." + +# Delete +presets.py delete NAME --confirm +``` diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/prompt-engineering.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/prompt-engineering.md new file mode 100644 index 00000000..d9f7341b --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/prompt-engineering.md @@ -0,0 +1,421 @@ +# Prompt Engineering Reference: Claude Banana + +> Load this on-demand when constructing complex prompts or when the user +> asks about prompt techniques. Do NOT load at startup. +> +> Aligned with Google's March 2026 "Ultimate Prompting Guide" for Gemini image generation. + +## Table of Contents + +- [The 6-Component Reasoning Brief](#the-6-component-reasoning-brief) -- Subject, Action, Context, Composition, Style, Technical +- [Domain Mode Modifier Libraries](#domain-mode-modifier-libraries) -- Photography, product, editorial, infographic modifiers +- [Advanced Techniques](#advanced-techniques) -- Negative prompting, iterative refinement, batch variation +- [Prompt Adaptation Rules](#prompt-adaptation-rules) -- Model-specific adjustments +- [Common Prompt Mistakes](#common-prompt-mistakes) -- Anti-patterns to avoid +- [Proven Prompt Templates](#proven-prompt-templates) -- Ready-to-use templates by use case +- [Safety Filter Rephrase Strategies](#safety-filter-rephrase-strategies) -- Workarounds for blocked prompts + +## The 6-Component Reasoning Brief + +Every image prompt should contain these components, written as natural +narrative paragraphs, NEVER as comma-separated keyword lists. + +### 1. Subject +The main focus of the image. Describe with physical specificity. + +**Good:** "A weathered Japanese ceramicist in his 70s, deep sun-etched +wrinkles mapping decades of kiln work, calloused hands cradling a +freshly thrown tea bowl with an irregular, organic rim" + +**Bad:** "old man, ceramic, bowl" + +### 2. Action +What is happening. Movement, pose, gesture, state of being. + +**Good:** "leaning forward with intense concentration, gently smoothing +the rim with a wet thumb, a thin trail of slip running down his wrist" + +**Bad:** "making pottery" + +### 3. Context +Environment, setting, temporal and spatial details. + +**Good:** "inside a traditional wood-fired anagama kiln workshop, +stacked shelves of drying pots visible in the soft background, late +afternoon light filtering through rice paper screens" + +**Bad:** "workshop, afternoon" + +### 4. Composition +Camera angle, shot type, framing, spatial relationships. + +**Good:** "intimate close-up shot from slightly below eye level, +shallow depth of field isolating the hands and bowl against the +soft bokeh of the workshop behind" + +**Bad:** "close up" + +### 5. Lighting +Light source, quality, direction, temperature, shadows. + +**Good:** "warm directional light from a single high window camera-left, +creating gentle Rembrandt lighting on the face with a soft triangle +of light on the shadow-side cheek, deep warm shadows in the workshop" + +**Bad:** "natural lighting" + +### 6. Style +Art medium, aesthetic reference, technical photographic details. + +**Good:** "captured with a Sony A7R IV, 85mm f/1.4 GM lens, Kodak Portra +400 color grading with lifted shadows and muted earth tones, reminiscent +of Dorothea Lange's documentary portraiture" + +**Bad:** "photorealistic, 8K, masterpiece" + +## Domain Mode Modifier Libraries + +### Cinema Mode +**Camera specs:** RED V-Raptor, ARRI Alexa 65, Sony Venice 2, Blackmagic URSA +**Lenses:** Cooke S7/i, Zeiss Supreme Prime, Atlas Orion anamorphic +**Film stocks:** Kodak Vision3 500T (tungsten), Kodak Vision3 250D (daylight), Fuji Eterna Vivid +**Lighting setups:** three-point, chiaroscuro, Rembrandt, split, butterfly, rim/backlight +**Shot types:** establishing wide, medium close-up, extreme close-up, Dutch angle, overhead crane, Steadicam tracking +**Color grading:** teal and orange, desaturated cold, warm vintage, high-contrast noir + +### Product Mode +**Surfaces:** polished marble, brushed concrete, raw linen, acrylic riser, gradient sweep +**Lighting:** softbox diffused, hard key with fill card, rim separation, tent lighting, light painting +**Angles:** 45-degree hero, flat lay, three-quarter, straight-on, worm's-eye +**Style refs:** Apple product photography, Aesop minimal, Bang & Olufsen clean, luxury cosmetics + +### Portrait Mode +**Focal lengths:** 85mm (classic), 105mm (compression), 135mm (telephoto), 50mm (environmental) +**Apertures:** f/1.4 (dreamy bokeh), f/2.8 (subject-sharp), f/5.6 (environmental context) +**Pose language:** candid mid-gesture, direct-to-camera confrontational, profile silhouette, over-shoulder glance +**Skin/texture:** freckles visible, pores at macro distance, catch light in eyes, subsurface scattering + +### Editorial/Fashion Mode +**Publication refs:** Vogue Italia, Harper's Bazaar, GQ, National Geographic, Kinfolk +**Styling notes:** layered textures, statement accessories, monochromatic palette, contrast patterns +**Locations:** marble staircase, rooftop at golden hour, industrial loft, desert dunes, neon-lit alley +**Poses:** power stance, relaxed editorial lean, movement blur, fabric in wind + +### UI/Web Mode +**Styles:** flat vector, isometric 3D, line art, glassmorphism, neumorphism, material design +**Colors:** specify exact hex or descriptive palette (e.g., "cool blues #2563EB to #1E40AF") +**Sizing:** design at 2x for retina, specify exact pixel dimensions needed +**Backgrounds:** transparent (request solid white then post-process), gradient, solid color + +### Logo Mode +**Construction:** geometric primitives, golden ratio, grid-based, negative space +**Typography:** bold sans-serif, elegant serif, custom lettermark, monogram +**Colors:** max 2-3 colors, works in monochrome, high contrast +**Output:** request on solid white background, post-process to transparent + +### Landscape Mode +**Depth layers:** foreground interest, midground subject, background atmosphere +**Atmospherics:** fog, mist, haze, volumetric light rays, dust particles +**Time of day:** blue hour (pre-dawn), golden hour, magic hour (post-sunset), midnight blue +**Weather:** dramatic storm clouds, clearing after rain, snow-covered, sun-dappled + +### Infographic Mode +**Layout:** modular sections, clear visual hierarchy, bento grid, flow top-to-bottom +**Text:** use quotes for exact text, descriptive font style, specify size hierarchy +**Data viz:** bar charts, pie charts, flow diagrams, timelines, comparison tables +**Colors:** high-contrast, accessible palette, consistent brand colors + +### Abstract Mode +**Geometry:** fractals, voronoi tessellation, spirals, fibonacci, organic flow, crystalline +**Textures:** marble veining, fluid dynamics, smoke wisps, ink diffusion, watercolor bleed +**Color palettes:** analogous harmony, complementary clash, monochromatic gradient, neon-on-black +**Styles:** generative art, data visualization art, glitch, procedural, macro photography of materials + +## Advanced Techniques + +### Character Consistency (Multi-turn) +Use `gemini_chat` and maintain descriptive anchors: +- First turn: Generate character with exhaustive physical description +- Following turns: Reference "the same character" + repeat 2-3 key identifiers +- Key identifiers: hair color/style, distinctive clothing, facial feature + +**Multi-image reference technique** (3.1 Flash): +- Provide up to 4-5 character reference images in the conversation +- Assign distinct names to each character ("Character A: the red-haired knight") +- Model preserves features across different angles, actions, and environments +- Works best when reference images show the character from multiple angles + +### Style Transfer Without Reference Images +Describe the target style exhaustively instead of referencing an image: +``` +Render this scene in the style of a 1950s travel poster: flat areas of +color in a limited palette of teal, coral, and cream. Bold geometric +shapes with visible paper texture. Hand-lettered title text with a +mid-century modern typeface feel. +``` + +### Text Rendering Tips +- Quote exact text: `with the text "OPEN DAILY" in bold condensed sans-serif` +- **25 characters or less**:this is the practical limit for reliable rendering +- **2-3 distinct phrases max**:more text fragments degrade quality +- Describe font characteristics, not font names +- Specify placement: "centered at the top third", "along the bottom edge" +- High contrast: light text on dark, or vice versa +- **Text-first hack:** Establish the text concept conversationally first ("I need a sign that says FRESH BREAD"), then generate. The model anchors on text mentioned early +- Expect creative font interpretations, not exact replication of described styles + +### Positive Framing (No Negative Prompts) +Gemini does NOT support negative prompts. Rephrase exclusions: +- Instead of "no blur" → "sharp, in-focus, tack-sharp detail" +- Instead of "no people" → "empty, deserted, uninhabited" +- Instead of "no text" → "clean, uncluttered, text-free" +- Instead of "not dark" → "brightly lit, high-key lighting" + +### Search-Grounded Generation +For images based on real-world data (weather, events, statistics), +Gemini can use Google Search grounding to incorporate live information. +Useful for infographics with current data. + +**Three-part formula for search-grounded prompts:** +1. `[Source/Search request`:What to look up +2. `[Analytical task`:What to analyze or extract +3. `[Visual translation`:How to render it as an image + +**Example:** "Search for the current top 5 programming languages by GitHub usage in 2026, analyze their relative popularity percentages, then generate a clean infographic bar chart with the language logos and percentages in a modern dark theme." + +## Prompt Adaptation Rules + +When adapting prompts from the claude-prompts database (Midjourney/DALL-E/etc.) +to Gemini's natural language format: + +| Source Syntax | Gemini Equivalent | +|---------------|-------------------| +| `--ar 16:9` | Call `set_aspect_ratio("16:9")` separately | +| `--v 6`, `--style raw` | Remove - Gemini has no version/style flags | +| `--chaos 50` | Describe variety: "unexpected, surreal composition" | +| `--no trees` | Positive framing: "open clearing with no vegetation" | +| `(word:1.5)` weight | Descriptive emphasis: "prominently featuring [word]" | +| `8K, masterpiece, ultra-detailed` | Keep only "ultra-realistic, high resolution"; remove the rest | +| Comma-separated tags | Expand into descriptive narrative paragraphs | +| `shot on Hasselblad` | Keep - camera specs work well in Gemini | + +## Common Prompt Mistakes + +1. **Keyword stuffing**:stacking generic quality terms ("8K, masterpiece, best quality") adds nothing. Use only "ultra-realistic, high resolution" at the end +2. **Tag lists**:Gemini wants prose, not "red car, sunset, mountain, cinematic" +3. **Missing lighting**:The single biggest quality differentiator +4. **No composition direction**:Results in generic centered framing +5. **Vague style**:"make it look cool" vs specific art direction +6. **Ignoring aspect ratio**:Always set before generating +7. **Overlong prompts**:Diminishing returns past ~200 words; be precise, not verbose +8. **Text longer than ~25 characters**:Rendering degrades rapidly past this limit +9. **Burying key details at the end**:In long prompts, details placed last may be deprioritized; put critical specifics (exact text, key constraints) in the first third of the prompt +10. **Not iterating with follow-up prompts**:Use `gemini_chat` for progressive refinement instead of trying to get everything right in one generation + +## Proven Prompt Templates + +> Extracted from 2,500+ tested prompts. These patterns consistently produce +> high-quality results. Use them as starting points and adapt to the request. + +### The Winning Formula (Weight Distribution) + +| Component | Weight | What to include | +|-----------|--------|-----------------| +| **Subject** | 40% | Age, skin tone, hair color/style, eye color, body type, expression | +| **Styling** | 25% | Brand names, textures, fit, accessories, colors | +| **Environment** | 15% | Location + time of day + context details | +| **Camera** | 10% | Camera model + lens + focal length + shot type | +| **Lighting** | 10% | Quality, direction, color temperature, shadows | + +### Instagram Ad / Social Media + +**Pattern:** `[Subject with age/appearance] + [outfit with brand/texture] + [action verb] + [setting] + [camera spec] + [lighting] + [platform aesthetic]` + +**Example (Product Placement):** +``` +Hyper-realistic gym selfie of athletic 24yo influencer with glowing olive +skin, wearing crinkle-textured athleisure set in mauve. iPhone 16 Pro Max +front-facing portrait mode capturing sweat droplets on collarbones, hazel +eyes enhanced by gym LED lighting. Mirror reflection shows perfect form, +golden morning light through floor-to-ceiling windows. Frayed chestnut +ponytail with baby hairs, ultra-detailed skin texture, trending aesthetic. +``` + +**Example (Lifestyle Ad):** +``` +A 24-year-old blonde fitness model in a high-energy sports drink +advertisement. Mid-run on a beach, wearing a vibrant orange sports bra +and black shorts, playful smile and sparkling blue eyes exuding vitality. +Bottle of the drink held in hand, waves crashing in background. Shot on +Nikon D850 with 70-200mm f/2.8 lens, natural light, fast shutter speed +capturing motion. Ultra-realistic skin texture, water droplets, product +label clearly visible. +``` + +**Example (Luxury Lifestyle):** +``` +Gorgeous Instagram model wearing a designer silk gown, luxury rooftop +restaurant, golden hour lighting, champagne in hand, luxurious aspirational +lifestyle. Captured with Sony A7R IV, 85mm f/1.4 lens, shallow depth of +field, warm color grading. +``` + +### Product / Commercial Photography + +**Pattern:** `[Product with brand/detail] + [dynamic elements] + [surface/setting] + "commercial photography for advertising campaign" + [lighting] + "high resolution"` + +**Example (Beverage):** +``` +Gatorade bottle with condensation dripping down the sides, surrounded by +lightning bolts and a burst of vibrant blue and orange light rays. The +Gatorade logo is prominently displayed on the bottle, with splashes of +water frozen in mid-air. Commercial food photography for an advertising +campaign, high resolution, high level of detail, vibrant complementary +colors. +``` + +**Example (Food):** +``` +In and Out burger with layers of fresh lettuce, melted cheese, and pretzel +bun, placed on a white surface with the In and Out logo subtly glowing in +the background. Falling french fries and golden light, warm scene. +Commercial food photography for an advertising campaign, high resolution, +high level of detail, vibrant complementary colors. +``` + +### Fashion / Editorial + +**Pattern:** `[Subject with ethnicity/age/features] + [outfit with texture/brand/cut] + [location] + [pose/action] + [camera + lens] + [lighting quality]` + +**Example (Street Style):** +``` +A 24-year-old female AI influencer posing confidently in an urban cityscape +during golden hour. Flawless sun-kissed skin, long wavy brown hair, deep +green eyes. Wearing a chic streetwear outfit: oversized beige blazer, +white top, high-waisted jeans. Captured with Sony A7R IV at 85mm f/1.4, +shallow depth of field with warm golden bokeh. +``` + +**Example (High Fashion):** +``` +Stunning 24-year-old woman, long platinum blonde hair, radiant skin, +piercing blue eyes, dressed in a chic pastel blazer with a modern +minimalist aesthetic, soft sunlight glow, high-end fashion appeal. +Shot on Canon EOS R5, 85mm f/1.2 lens. +``` + +**Example (Avant-Garde):** +``` +A blonde fitness model transformed into a runway-ready fashion icon, +wearing a bold avant-garde outfit: cropped leather jacket with neon pink +accents, paired with high-waisted athletic shorts and knee-high boots. +Captured mid-stride on a minimalist white runway, playful twinkle in her +eye, dramatic studio lighting from above. +``` + +### SaaS / Tech Marketing + +**Pattern:** `[UI mockup or abstract visual] + "on [dark/light] background" + [specific colors with hex] + [typography description] + "clean, premium SaaS aesthetic" + [glassmorphism/gradient/glow effects]` + +**Example (Dashboard Hero):** +``` +A floating glassmorphism UI card on a deep charcoal background showing a +content analytics dashboard with a rising line graph in teal (#14B8A6), +bar charts in coral (#F97316), and a circular progress indicator at 94%. +Subtle grid lines, frosted glass effect with 20% opacity, teal glow +bleeding from the card edges. Clean premium SaaS aesthetic, no text +smaller than headline size. +``` + +**Example (Feature Highlight):** +``` +An isometric 3D illustration of interconnected data nodes on a dark navy +background. Each node is a glowing teal sphere connected by thin luminous +lines, forming a constellation pattern. One central node pulses brighter +with radiating rings. Modern tech illustration style with subtle depth +of field, volumetric lighting from below. +``` + +**Example (Comparison/Before-After):** +``` +Split-screen image: left side shows a cluttered, dim workspace with +scattered papers, red error indicators, and a frustrated expression +conveyed through a cracked coffee mug and tangled cables. Right side +shows a clean, organized dashboard interface glowing in teal and white +on a dark background, with smooth flowing lines and checkmarks. A sharp +vertical dividing line separates chaos from clarity. +``` + +### Logo / Branding + +**Pattern:** `[Product/bottle/item] + "with [brand element] prominently displayed" + [dynamic visual elements] + "commercial photography" + [lighting style] + "high resolution, vibrant complementary colors"` + +**Example:** +``` +A sleek matte black bottle with a minimal white logo mark centered on the +label, surrounded by swirling gradient ribbons of teal and coral light. +The bottle sits on a reflective dark surface, sharp studio rim lighting +separating it from the background. Product photography for luxury +branding, high resolution, dramatic contrast. +``` + +### Key Tactics That Make Prompts Work + +1. **Name real cameras**:"Sony A7R IV", "Canon EOS R5", "iPhone 16 Pro Max" anchor realism +2. **Specify exact lens**:"85mm f/1.4" gives the model precise depth-of-field information +3. **Use age + ethnicity + features**:"24yo with olive skin, hazel eyes" beats "a person" +4. **Name brands for styling**:"Lululemon mat", "Tom Ford suit" triggers specific visual associations +5. **Include micro-details**:"sweat droplets on collarbones", "baby hairs stuck to neck" +6. **Add platform context**:"Instagram aesthetic", "commercial photography for advertising" +7. **Describe textures**:"crinkle-textured", "metallic silver", "frosted glass" +8. **Use action verbs**:"mid-run", "posing confidently", "captured mid-stride" +9. **End with "ultra-realistic, high resolution"**:these two specific anchors help on Gemini. Avoid generic stacking like "8K, masterpiece, best quality" which adds no value +10. **For products, say "prominently displayed"**:ensures the product/logo isn't hidden + +### Anti-Patterns (What NOT to Do) + +- **"A dark-themed Instagram ad showing..."**:too meta, describes the concept not the image +- **"A sleek SaaS dashboard visualization..."**:abstract, no visual anchors +- **"Modern, clean, professional..."**:vague adjectives that mean nothing to the model +- **"A bold call to action with..."**:describes marketing intent, not visual content +- **Describing what the viewer should feel**:instead, describe what creates that feeling + +## Safety Filter Rephrase Strategies + +Gemini's safety filters (Layer 2: server-side output filter) cannot be disabled. +When a prompt is blocked, the only path forward is rephrasing. + +### Common Trigger Categories + +| Category | Triggers on | Rephrase approach | +|----------|------------|-------------------| +| Violence/weapons | Combat, blood, injuries, firearms | Use metaphor or aftermath: "battle-worn" → "weathered veteran" | +| Medical/gore | Surgery, wounds, anatomical detail | Abstract or clinical: "open wound" → "medical illustration" | +| Real public figures | Named celebrities, politicians | Use archetypes: "Elon Musk" → "a tech entrepreneur in a minimalist office" | +| Children + risk | Minors in any ambiguous context | Add safety context: specify educational, family, or playful framing | +| NSFW/suggestive | Revealing clothing, intimate poses | Use artistic framing: "fashion editorial, fully clothed, editorial pose" | + +### Rephrase Patterns + +1. **Abstraction**:Replace specific dangerous elements with abstract concepts +2. **Artistic framing**:Frame content as art, editorial, or documentary +3. **Metaphor**:Use symbolic language instead of literal descriptions +4. **Positive emphasis**:Describe what IS present, not what's dangerous +5. **Context shift**:Move from threatening to educational/professional context + +### Example Rephrases + +| Blocked prompt | Successful rephrase | +|----------------|---------------------| +| "a soldier in combat firing a rifle" | "a determined soldier standing guard at dawn, rifle slung over shoulder, morning mist over the outpost" | +| "a scary horror monster" | "a fantastical creature from a dark fairy tale, intricate organic textures, bioluminescent accents, concept art style" | +| "dog in a fight" | "a friendly golden retriever playing energetically in a sunny park, action shot, joyful expression" | +| "medical surgery scene" | "a clean modern operating room viewed from the observation gallery, soft blue surgical lights, professional documentary style" | +| "celebrity portrait of [name]" | "a distinguished middle-aged man in a tailored navy suit, warm studio lighting, editorial portrait style" | + +### Key Principle + +Layer 2 (output filter) analyzes the generated image, not just the prompt. +Even well-phrased prompts can be blocked if the model's interpretation triggers +the output filter. When this happens, try shifting the visual concept further +from the trigger rather than just changing words. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/seo-image-presets.md b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/seo-image-presets.md new file mode 100644 index 00000000..44fbd663 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-image-gen/references/seo-image-presets.md @@ -0,0 +1,137 @@ +# SEO Image Presets + +Pre-configured presets for common SEO image use cases. These map to banana's +preset format (see `references/presets.md` for schema details). + +## Preset Templates + +### og-default:Standard OG/Social Preview + +```json +{ + "name": "og-default", + "description": "Clean, professional OG image for social sharing", + "aspect_ratio": "16:9", + "resolution": "1K", + "domain_mode": "Product", + "style": { + "colors": ["#FFFFFF", "#F5F5F5"], + "mood": "Professional, clean, trustworthy", + "lighting": "Bright, even studio lighting with soft shadows", + "typography": "Modern sans-serif if text needed" + }, + "post_processing": "magick output.png -resize 1200x630^ -gravity center -extent 1200x630 output-og.webp" +} +``` + +### blog-hero:Widescreen Blog Hero Image + +```json +{ + "name": "blog-hero", + "description": "Dramatic widescreen hero for blog posts", + "aspect_ratio": "16:9", + "resolution": "2K", + "domain_mode": "Cinema", + "style": { + "colors": ["contextual"], + "mood": "Dramatic, atmospheric, editorial", + "lighting": "Golden hour or moody blue hour, directional", + "typography": "None:image only" + }, + "post_processing": "magick output.png -quality 85 output-hero.webp" +} +``` + +### product-white:E-commerce Product Shot + +```json +{ + "name": "product-white", + "description": "Clean white background product photography", + "aspect_ratio": "4:3", + "resolution": "2K", + "domain_mode": "Product", + "style": { + "colors": ["#FFFFFF"], + "mood": "Clean, professional, catalog-ready", + "lighting": "360-degree soft studio lighting, minimal shadows", + "typography": "None" + }, + "prompt_suffix": "Studio product photography, clean white background, professional catalog shot, high resolution", + "post_processing": "magick output.png -fuzz 5% -transparent white output-transparent.png" +} +``` + +### social-square:Social Media Square + +```json +{ + "name": "social-square", + "description": "1:1 square image for social media platforms", + "aspect_ratio": "1:1", + "resolution": "1K", + "domain_mode": "UI/Web", + "style": { + "colors": ["brand-contextual"], + "mood": "Engaging, scroll-stopping, platform-native", + "lighting": "Bright, even, high-contrast", + "typography": "Bold sans-serif if text needed, under 25 characters" + } +} +``` + +### infographic-vertical:Data-Heavy Infographic + +```json +{ + "name": "infographic-vertical", + "description": "Tall vertical infographic for data visualization", + "aspect_ratio": "2:3", + "resolution": "4K", + "domain_mode": "Infographic", + "style": { + "colors": ["brand-contextual", "data-visualization palette"], + "mood": "Informative, structured, authoritative", + "lighting": "Flat, even, no dramatic shadows", + "typography": "Clear hierarchy:headline, subheads, body, captions" + }, + "notes": "Use thinking: high for better text rendering accuracy" +} +``` + +### favicon-mark:Favicon / App Icon + +```json +{ + "name": "favicon-mark", + "description": "Minimal iconic mark for favicon or app icon", + "aspect_ratio": "1:1", + "resolution": "512", + "domain_mode": "Logo", + "style": { + "colors": ["2-3 brand colors max"], + "mood": "Minimal, recognizable, scalable", + "lighting": "Flat, no shadows", + "typography": "Single letter or symbol only" + }, + "post_processing": "magick output.png -resize 32x32 favicon.ico && magick output.png -resize 180x180 apple-touch-icon.png" +} +``` + +## Creating Custom Presets + +Users can create their own presets: +```bash +python3 ~/.claude/skills/seo-image-gen/scripts/presets.py create my-brand +``` + +This creates `~/.banana/presets/my-brand.json` with the full schema. +Custom presets override SEO defaults when specified. + +## Preset Selection Logic + +1. If user specifies a use case command (og, hero, product), load the matching preset +2. If user mentions a brand preset name, load from `~/.banana/presets/` +3. Brand presets override SEO presets for colors, mood, and typography +4. SEO presets always provide aspect ratio and resolution defaults diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-images/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-images/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-images/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-images/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-images/SKILL.md new file mode 100644 index 00000000..9a6ccc90 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-images/SKILL.md @@ -0,0 +1,409 @@ +--- +name: seo-images +description: > + Image optimization analysis for SEO and performance. Checks alt text, file + sizes, formats, responsive images, lazy loading, CLS prevention, image SERP + rankings (via DataForSEO), and image file optimization (WebP/AVIF conversion, + IPTC/XMP metadata injection). Use when user says "image optimization", + "alt text", "image SEO", "image size", "image audit", "optimize images", + "image metadata", "image SERP", "convert to webp", or "image file optimize". +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Image Optimization Analysis + +## Checks + +### Alt Text +- Present on all `` elements (except decorative: `role="presentation"`) +- Descriptive: describes the image content, not "image.jpg" or "photo" +- Includes relevant keywords where natural, not keyword-stuffed +- Length: 10-125 characters + +**Good examples:** +- "Professional plumber repairing kitchen sink faucet" +- "Red 2024 Toyota Camry sedan front view" +- "Team meeting in modern office conference room" + +**Bad examples:** +- "image.jpg" (filename, not description) +- "plumber plumbing plumber services" (keyword stuffing) +- "Click here" (not descriptive) + +### File Size + +**Tiered thresholds by image category:** + +| Image Category | Target | Warning | Critical | +|----------------|--------|---------|----------| +| Thumbnails | < 50KB | > 100KB | > 200KB | +| Content images | < 100KB | > 200KB | > 500KB | +| Hero/banner images | < 200KB | > 300KB | > 700KB | + +Recommend compression to target thresholds where possible without quality loss. + +### Format +| Format | Browser Support | Use Case | +|--------|-----------------|----------| +| WebP | 97%+ | Default recommendation | +| AVIF | 92%+ | Best compression, newer | +| JPEG | 100% | Fallback for photos | +| PNG | 100% | Graphics with transparency | +| SVG | 100% | Icons, logos, illustrations | + +Recommend WebP/AVIF over JPEG/PNG. Check for `` element with format fallbacks. + +#### Recommended `` Element Pattern + +Use progressive enhancement with the most efficient format first: + +```html + + + + Descriptive alt text + +``` + +The browser will use the first supported format. Current browser support: AVIF 93.8%, WebP 95.3%. + +#### JPEG XL: Emerging Format + +In November 2025, Google's Chromium team reversed its 2022 decision and announced it will restore JPEG XL support in Chrome using a Rust-based decoder. The implementation is feature-complete but not yet in Chrome stable. JPEG XL offers lossless JPEG recompression (~20% savings with zero quality loss) and competitive lossy compression. Not yet practical for web deployment, but worth monitoring for future adoption. + +### Responsive Images +- `srcset` attribute for multiple sizes +- `sizes` attribute matching layout breakpoints +- Appropriate resolution for device pixel ratios + +```html +Description +``` + +### Lazy Loading +- `loading="lazy"` on below-fold images +- Do NOT lazy-load above-fold/hero images (hurts LCP) +- Check for native vs JavaScript-based lazy loading + +```html + +Description + + +Hero image +``` + +#### Detected lazy-loader methods (`lazy_method` field) + +`scripts/parse_html.py` classifies each image's lazy-loading mechanism via the +`lazy_method` field on every image entry. Five values: + +| `lazy_method` | Signal detected | Common stack | +|---|---|---| +| `native` | `loading="lazy"` HTML attribute | Modern browsers, plain HTML | +| `perfmatters` | `data-perfmatters-src`/`-srcset` OR class `perfmatters-lazy` | WordPress + Perfmatters plugin | +| `ewww` | `data-ewww-src` / `data-eio` OR class `lazyload-eio` | WordPress + EWWW Image Optimizer | +| `js-generic` | `data-src` / `data-lazy-src` / `data-original` / `data-srcset` OR class `lazyload`/`lazyloaded`/`lazy` | Lazysizes, vanilla-lazyload, jQuery plugins | +| `none` | Neither attribute nor class signal | Page is not lazy-loading this image | + +When auditing image SEO, report `lazy_method` alongside `loading` so users know +whether their site is using a JS-driven lazy-loader (in which case the native +`loading="lazy"` attribute is intentionally absent — that is not a regression). + +### `fetchpriority="high"` for LCP Images + +Add `fetchpriority="high"` to your hero/LCP image to prioritize its download in the browser's network queue: + +```html +Hero image description +``` + +**Critical:** Do NOT lazy-load above-the-fold/LCP images. Using `loading="lazy"` on LCP images directly harms LCP scores. Reserve `loading="lazy"` for below-the-fold images only. + +### `decoding="async"` for Non-LCP Images + +Add `decoding="async"` to non-LCP images to prevent image decoding from blocking the main thread: + +```html +Description +``` + +### CLS Prevention +- `width` and `height` attributes set on all `` elements +- `aspect-ratio` CSS as alternative +- Flag images without dimensions + +```html + +Description + + +Description + + +Description +``` + +### File Names +- Descriptive: `blue-running-shoes.webp` not `IMG_1234.jpg` +- Hyphenated, lowercase, no special characters +- Include relevant keywords + +### CDN Usage +- Check if images served from CDN (different domain, CDN headers) +- Recommend CDN for image-heavy sites +- Check for edge caching headers + +## Output + +### Image Audit Summary + +| Metric | Status | Count | +|--------|--------|-------| +| Total Images | - | XX | +| Missing Alt Text | ❌ | XX | +| Oversized (>200KB) | ⚠️ | XX | +| Wrong Format | ⚠️ | XX | +| No Dimensions | ⚠️ | XX | +| Not Lazy Loaded | ⚠️ | XX | + +### Prioritized Optimization List + +Sorted by file size impact (largest savings first): + +| Image | Current Size | Format | Issues | Est. Savings | +|-------|--------------|--------|--------|--------------| +| ... | ... | ... | ... | ... | + +### Recommendations +1. Convert X images to WebP format (est. XX KB savings) +2. Add alt text to X images +3. Add dimensions to X images +4. Enable lazy loading on X below-fold images +5. Compress X oversized images + +--- + +## Image SERP Analysis + +When DataForSEO MCP is available, enhance the image audit with competitive data. + +### `/seo images serp ` + +Cross-reference on-page images with Google Images SERP rankings. + +**Workflow:** +1. Fetch Google Images results via `serp_google_images_live_advanced` (depth=100) +2. Extract: top domains, image types, alt text patterns +3. Output competitor image SERP landscape + +**Output:** + +| Rank | Domain | Title/Alt | Image URL | Page URL | +|------|--------|-----------|-----------|----------| +| 1 | example.com | "Blue running shoes..." | .../shoes.webp | /products/... | + +**Analysis includes:** +- **Domain dominance**: which sites own the most image positions (top 10 by count) +- **Alt text patterns**: common title/alt patterns in top-ranking images +- **Format distribution**: WebP vs JPEG vs PNG in top results +- **Opportunity score**: keywords where you have page rankings but no image presence + +If DataForSEO MCP is not available, inform user and suggest installing the extension. + +--- + +## Image File Optimization + +Optimize image files for SEO: format conversion, metadata injection, compression. + +### `/seo images optimize ` + +Optimize image file(s) for web and SEO. Converts to WebP/AVIF, injects IPTC +metadata, compresses, and generates responsive variants. + +**Tools used (in order of preference):** +- `exiftool` -- EXIF/IPTC/XMP read/write (install: `sudo apt install libimage-exiftool-perl`) +- `cwebp` -- WebP conversion (install: `sudo apt install webp`) +- ImageMagick `convert` -- Format conversion, resizing (pre-installed on most systems) +- FFmpeg -- Fallback for format conversion (pre-installed) + +**Before running:** Check which tools are available with `which exiftool cwebp convert ffmpeg`. + +### Format Conversion + +Convert images to modern formats with metadata preservation: + +```bash +# WebP (recommended default) - with metadata preserved +cwebp -q 82 -metadata all input.jpg -o output.webp + +# WebP via ImageMagick (fallback if cwebp not installed) +convert input.jpg -quality 82 output.webp + +# AVIF via FFmpeg (slower encode, best compression) +ffmpeg -i input.jpg -c:v libaom-av1 -crf 30 -still-picture 1 output.avif + +# Responsive variants (400w, 800w, 1200w) +convert input.jpg -resize 400x -quality 82 image-400.webp +convert input.jpg -resize 800x -quality 82 image-800.webp +convert input.jpg -resize 1200x -quality 82 image-1200.webp +``` + +### Metadata Injection (IPTC for Google Rich Results) + +Google Images displays IPTC Creator, Credit Line, and Copyright in search results. +This is **NOT a ranking factor** but improves rich result display and brand attribution. + +**With exiftool (preferred):** +```bash +# Read all metadata +exiftool image.jpg + +# Inject IPTC + XMP metadata for Google Images rich results +exiftool \ + -IPTC:ObjectName="Product Photo Description" \ + -IPTC:Caption-Abstract="Detailed image description" \ + -IPTC:By-line="Brand Name Photography" \ + -IPTC:Credit="Brand Name" \ + -IPTC:CopyrightNotice="Copyright 2026 Brand Name" \ + -IPTC:Source="brandname.com" \ + -XMP:Title="Product Photo Description" \ + -XMP:Description="Detailed image description" \ + -XMP:Creator="Brand Name Photography" \ + -XMP:Rights="Copyright 2026 Brand Name" \ + image.jpg + +# Batch inject to all images in directory +exiftool -overwrite_original \ + -IPTC:By-line="Brand Name" \ + -IPTC:CopyrightNotice="Copyright 2026 Brand Name" \ + *.jpg *.webp *.png +``` + +**With ImageMagick (fallback):** +```bash +identify -verbose image.jpg | head -50 + +convert input.jpg \ + -set comment "Product Photo Description" \ + -set IPTC:2:80 "Brand Name Photography" \ + -set IPTC:2:116 "Copyright 2026 Brand Name" \ + output.jpg +``` + +**IMPORTANT:** WebP supports EXIF and XMP but NOT IPTC natively. For WebP files, +use XMP fields instead of IPTC. exiftool handles this conversion automatically. + +### AI-Generated Images: `DigitalSourceType` (Merchant Center requirement) + +For product images produced by generative AI, **Google Merchant Center requires** +IPTC `DigitalSourceType: TrainedAlgorithmicMedia` metadata. This is an +operational policy requirement, not a ranking factor — feeds missing this label +on AI-generated imagery can be disapproved. + +Primary source: +https://developers.google.com/search/docs/fundamentals/ai-optimization-guide +(references the underlying Merchant Center policy on AI media labeling). + +**Audit command:** + +```bash +# Audit a directory for the IPTC label (counts: missing, ai, captured, etc.) +python3 scripts/iptc_ai_label.py audit ./images/ --json + +# Audit a single image +python3 scripts/iptc_ai_label.py audit ./hero.webp --json + +# Inject the AI label into an image +python3 scripts/iptc_ai_label.py inject ./ai-hero.webp \ + --source-type trainedAlgorithmicMedia + +# Other vocabulary values: +# compositeSynthetic (mix of captured + AI elements) +# digitalCapture (fully captured photograph) +``` + +**Raw exiftool equivalents** (for ad-hoc usage): + +```bash +# Inject manually +exiftool \ + -XMP-iptcExt:DigitalSourceType="https://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia" \ + ai-generated-product.jpg + +# Audit: find images missing the label across a directory +exiftool -if 'not $XMP-iptcExt:DigitalSourceType' \ + -filename -DigitalSourceType *.jpg *.webp *.png +``` + +The IPTC vocabulary also defines: +- `trainedAlgorithmicMedia` — fully AI-generated (use this for diffusion-model + product imagery) +- `compositeSynthetic` — mixes captured + AI-generated elements +- `digitalCapture` — fully captured photograph (no AI element) + +When `/seo images optimize` is run on AI-generated assets, prompt the user to +confirm the source type and inject the matching IPTC value automatically. + +For **AI-generated product titles and descriptions**, Google Merchant Center +also requires the AI-generated text to be separately specified and labeled in +the feed. This is enforced at the feed layer, not the page layer — flag this +in cross-reference with `seo-ecommerce`. + +### Metadata Audit + +```bash +# Quick audit with exiftool +exiftool -IPTC:all -XMP:all -EXIF:ImageDescription image.jpg + +# Batch audit - find images missing IPTC Creator +exiftool -if 'not $IPTC:By-line' -filename *.jpg *.webp *.png +``` + +### Full Optimization Pipeline + +For maximum image SEO, run this pipeline on each image: + +1. **Audit existing metadata**: `exiftool -IPTC:all -XMP:all image.jpg` +2. **Inject IPTC/XMP metadata**: Creator, Copyright, Description +3. **Convert to WebP**: `cwebp -q 82 -metadata all image.jpg -o image.webp` +4. **Generate responsive variants**: 400w, 800w, 1200w +5. **Verify metadata preserved**: `exiftool image.webp` +6. **Generate `` HTML**: AVIF > WebP > JPEG fallback chain + +### What Matters vs What Doesn't for Google Images + +| Factor | Impact | Where to Set | +|--------|--------|--------------| +| Alt text | **CRITICAL** (ranking) | HTML `` | +| Filename | **HIGH** (ranking) | File system (descriptive, hyphenated) | +| Page context | **HIGH** (ranking) | Surrounding HTML content | +| File size/speed | **MEDIUM** (indirect via CWV) | Compression + format conversion | +| IPTC Creator/Copyright | **LOW** (display only) | Image file metadata | +| EXIF camera data | NONE | Irrelevant for SEO | +| IPTC Keywords | NONE | Google ignores these | + +--- + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable | Report connection error with status code. Suggest verifying URL and checking if site requires authentication. | +| No images found on page | Report that no `` elements were detected. Suggest checking if images are loaded via JavaScript or CSS background-image. | +| Images behind CDN or authentication | Note that image files could not be directly accessed for size analysis. Report available metadata (alt text, dimensions, format from markup) and flag inaccessible resources. | +| exiftool not installed | Fall back to ImageMagick for metadata. Recommend: `sudo apt install libimage-exiftool-perl` | +| cwebp not installed | Fall back to ImageMagick or FFmpeg for WebP conversion. Recommend: `sudo apt install webp` | +| DataForSEO credentials/tools unavailable | Skip Image SERP Analysis section and continue with on-page image checks. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-local/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-local/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-local/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-local/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-local/SKILL.md new file mode 100644 index 00000000..ecc1b87f --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-local/SKILL.md @@ -0,0 +1,317 @@ +--- +name: seo-local +description: > + Local SEO analysis covering Google Business Profile optimization, NAP + consistency, citation health, review signals, local schema markup, + location page quality, multi-location SEO, and industry-specific + recommendations. Detects business type (brick-and-mortar, SAB, hybrid) + and industry vertical (restaurant, healthcare, legal, home services, + real estate, automotive). Use when user says "local SEO", "Google + Business Profile", "GBP", "map pack", "local pack", "citations", + "NAP consistency", "local rankings", "service area", "multi-location", + or "local search". +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Local SEO Analysis (March 2026) + +## Key Statistics + +| Metric | Value | Source | +|--------|-------|--------| +| GBP signals share of local pack weight | 32% | Whitespark 2026 | +| Proximity share of ranking variance | 55.2% | Search Atlas ML study | +| Review signals share (up from 16%) | ~20% | Whitespark 2026 | +| Google searches seeking local info | 46% | Industry data | +| Mobile "near me" searches leading to visit in 24h | 76% | Google confirmed | +| ChatGPT/AI usage for local recommendations | 45% (up from 6%) | BrightLocal LCRS 2026 | +| ChatGPT local conversion rate | 15.9% | Seer Interactive | +| Google organic local conversion rate | 1.76% | Seer Interactive | +| Local pack ads growth (Jan 2025 to Jan 2026) | 1% to 22% | Sterling Sky | + +--- + +## Business Type Detection + +Detect from page signals before analysis. This determines which checks apply. + +### Brick-and-Mortar +- Physical street address visible in page content or footer +- Google Maps embed with pin/directions +- "Visit us at", "Located at", "Come see us" +- Structured address in LocalBusiness schema + +### Service Area Business (SAB) +- No visible physical address +- Service area mentions: "serving [city/region]", "service area includes" +- "We come to you", "On-site service", "Mobile [service]" +- `areaServed` in schema without `address.streetAddress` + +### Hybrid +- Both physical address AND service area language present +- "Visit our showroom" combined with "We also serve [areas]" + +**Impact on checks**: SABs skip embedded map verification and physical address consistency. Brick-and-mortar gets full NAP + map checks. + +--- + +## Industry Vertical Detection + +Detect from page signals and GBP category patterns. Routes to industry-specific checks from `../seo/references/local-schema-types.md`. + +| Vertical | Detection Signals | +|----------|------------------| +| **Restaurant** | /menu, menu items, reservations, cuisine types, food ordering, "dine-in", "takeout" | +| **Healthcare** | insurance accepted, patients, appointments, NPI, medical terms, "Dr.", HIPAA notice | +| **Legal** | attorney, lawyer, practice areas, bar admission, case results, "free consultation" | +| **Home Services** | service area, emergency service, "free estimate", licensed/insured/bonded, "24/7" | +| **Real Estate** | listings, MLS, properties for sale/rent, agent bio, brokerage, "open house" | +| **Automotive** | inventory, VIN, test drive, dealership, service department, "new/used/certified" | + +If no vertical detected, use generic `LocalBusiness` analysis path. + +--- + +## Analysis Dimensions + +### 1. GBP Signals (25%) + +Primary category is the **single most important local pack factor** (Whitespark #1, score: 193). Incorrect primary category is the **#1 negative factor** (score: 176). + +**Check for:** +- GBP embed or reference detectable on page (Maps iframe, place ID, reviews widget) +- Primary category appropriateness (infer from page content vs visible GBP data) +- Evidence of secondary categories (optimal: 4 additional per BrightLocal) +- GBP posts presence (no direct ranking impact per WebFX, but triggers Post Justifications) +- Photos/video evidence (45% more direction requests with photos, Agency Jet) +- Q&A content (deprecated Dec 2025, replaced by Ask Maps Gemini AI -- recommend recreating Q&A content as FAQ sections on website; GBP removed existing Q&A with no export available) +- Google Verified badge eligibility (replaced Guaranteed/Screened in Oct 2025) +- GBP link URL strategy: do NOT link to strongest website page (Sterling Sky Diversity Update -- risks suppressing organic rankings) +- Business hours visibility on page (businesses open at search time rank higher, factor #5) + +**Scoring guide:** +- Full: GBP embed present, category signals align, posts active, photos present +- Partial: Some GBP signals present but incomplete +- Low: No visible GBP integration on website + +### 2. Reviews & Reputation (20%) + +Review velocity matters more than total count. The **18-day rule** (Sterling Sky): rankings cliff if no new reviews for 3 weeks. + +**Check for:** +- Total Google review count visible on page or schema (magic threshold: 10, Sterling Sky) +- Star rating (31% of consumers only use 4.5+, 68% only use 4+, BrightLocal 2026) +- Review recency indicators (74% only care about reviews in last 3 months) +- `aggregateRating` in schema (ratingValue, reviewCount, bestRating) +- Third-party review presence (consumers use average of 6 review sites, BrightLocal 2026) +- Owner response patterns (88% would use business that responds, BrightLocal) +- Review gating detection: any pre-screening of satisfaction before directing to review platform is prohibited by Google (fake engagement policy) and FTC ($53,088/violation) + +**Industry-specific:** +- Healthcare: HIPAA prohibits confirming/denying reviewer is a patient in responses +- Legal: attorney-client privilege considerations in review responses + +**Scoring guide:** +- Full: 10+ reviews, 4.5+ stars, recent activity, owner responses, multi-platform presence +- Partial: Some reviews but gaps in recency, rating, or response rate +- Low: <10 reviews, no recent activity, no responses, single platform only + +### 3. Local On-Page SEO (20%) + +Dedicated service pages = **#1 local organic factor AND #2 AI visibility factor** (Whitespark 2026). + +**Check for:** +- Title tag contains city/service keywords +- H1 tag with local intent (city + service) +- NAP (Name, Address, Phone) visible in page HTML (footer, contact section, header) +- Dedicated service pages (one page per core service) +- Location page quality for multi-location sites: + - **>60-70% unique content** minimum (industry consensus, no Google-confirmed threshold) + - **Swap test**: if you can swap the city name and content still makes sense, it's a doorway page (RicketyRoo method). HVAC company lost 80% rankings + 63% traffic after March 2024 Core Update for this pattern + - Local photos, area-specific testimonials, local FAQs +- Embedded Google Map (geographic signal reinforcement, not direct ranking factor -- lazy-load to mitigate speed impact) +- Click-to-call button (`tel:` link) and contact form above the fold +- Internal linking architecture: hub-and-spoke, every critical page within 3 clicks of homepage +- 2-5 contextual internal links per 1,000 words with descriptive anchor text + +**Multi-location specific:** +- Store locator with individual crawlable URLs (SSR/SSG preferred over CSR) +- Subdirectory structure: `domain.com/locations/city-name/` (subdirectories consolidate link equity better, Bruce Clay: 50%+ traffic lift) +- Each location page has unique LocalBusiness schema with `@id` + +**Scoring guide:** +- Full: City in title + H1, NAP visible, dedicated service pages, no doorway patterns, good internal linking +- Partial: Some local signals but missing service pages or doorway page risk +- Low: Generic title/H1, NAP not visible, thin location pages + +### 4. NAP Consistency & Citations (15%) + +Citations declining for traditional pack rankings but **3 of top 5 AI visibility factors are citation-related** (Whitespark 2026). Google's July 2025 documentation update removed "directories" from prominence definition. + +**Check for:** +- NAP extraction: compare Name, Address, Phone from: + 1. Visible page HTML (footer, contact page) + 2. LocalBusiness JSON-LD schema + 3. Any visible GBP data + - Flag any discrepancies between these three sources +- Citation presence on Tier 1 directories (check via WebFetch or site: search patterns): + - Google Business Profile signals on page + - Yelp: `site:yelp.com "Business Name"` + - BBB: `site:bbb.org "Business Name"` + - Facebook business page references +- Apple Business Connect awareness (usage doubled to 27%, BrightLocal 2026 -- recommend claiming) +- Bing Places awareness (powers ChatGPT, Copilot, Alexa -- recommend claiming and optimizing) +- Industry-specific directory recommendations: load `../seo/references/local-schema-types.md` for per-vertical citation sources +- Data aggregator awareness: Data Axle, Foursquare, Neustar/TransUnion (recommend submission for downstream distribution) + +**Scoring guide:** +- Full: Consistent NAP across page/schema, Tier 1 citations detected, industry directories present +- Partial: NAP present but inconsistencies, some citations missing +- Low: NAP discrepancies, no detectable citations, no schema address + +### 5. Local Schema Markup (10%) + +Schema is NOT a direct ranking factor (John Mueller confirmed). But enables rich results (43% CTR increase, Webstix case study) and helps AI systems parse business information. + +**Check for:** +- LocalBusiness schema presence (extract JSON-LD blocks) +- Required properties: `name`, `address` with PostalAddress sub-properties +- Recommended properties: `geo` (minimum 5 decimal places, Confirmed), `openingHoursSpecification`, `telephone`, `url`, `priceRange` (<100 chars), `image`, `aggregateRating` +- **Correct subtype for industry** -- load `../seo/references/local-schema-types.md`: + - Restaurant using `Restaurant` not generic `LocalBusiness` + - Legal using `LegalService` not deprecated `Attorney` + - Auto dealer using `AutoDealer` not deprecated `VehicleListing` + - Healthcare using `MedicalClinic`/`Hospital`/`Dentist` not generic `MedicalBusiness` +- SAB-specific: `areaServed` with named cities (recommended, not in Google's official list but Schema.org supported) +- Multi-location: each location page has own LocalBusiness with unique `@id`, linked via `branchOf` to Organization on homepage +- Industry-specific schema patterns (per `../seo/references/local-schema-types.md`): + - Restaurant: Menu + MenuSection + MenuItem + ReserveAction + - Healthcare: Physician (Person) + MedicalSpecialty + sameAs to NPI + - Legal: LegalService + Person + Service (practice areas) + - Home Services: Subtype + areaServed + Service + - Real Estate: RealEstateAgent + Person + RealEstateListing + - Automotive: AutoDealer + Car + Offer (separate dept schemas) + +**Scoring guide:** +- Full: Correct subtype, all recommended properties, industry-specific patterns, valid JSON-LD +- Partial: LocalBusiness present but generic type or missing recommended properties +- Low: No local schema, or schema with errors/placeholder content + +### 6. Local Link & Authority Signals (10%) + +Links declining for local pack but remain **~26% of local organic ranking** (Whitespark 2026, #2 factor group). "Best of" list placements = **#1 AI visibility citation factor**. + +**Check for:** +- Local backlink indicators detectable from page: + - Chamber of Commerce mentions or links (high Trust Flow, ~80% more consumer visits, GlueUp) + - BBB accreditation/badge (Google uses BBB for business verification) + - Local news/press mentions + - Community involvement signals (sponsorships, local events, partnerships) +- "Best of" list presence (top AI visibility factor per Whitespark 2026) +- Digital PR signals: 66.2% of PR practitioners now track AI citations as KPI (BuzzStream 2026) +- Brand mentions correlate **3x more strongly** with AI visibility than traditional backlinks (Ahrefs: 0.664 vs 0.218 correlation) +- Link velocity benchmark: 5-10 quality local links/month for small businesses (consensus) + +**Scoring guide:** +- Full: Local authority signals visible (chamber, BBB, press), community involvement evident +- Partial: Some authority signals but limited local link indicators +- Low: No detectable local authority signals + +--- + +## AI Search Impact on Local + +**Do not duplicate seo-geo analysis.** Provide local-specific AI context and recommend `/seo geo ` for full analysis. + +Key local AI facts: +- AI Overviews appear on up to 68% of local searches (Whitespark Q2 2025) +- ChatGPT converts at 15.9% vs Google organic at 1.76% (Seer Interactive) +- 3 of top 5 AI visibility factors are citation-related (Whitespark 2026) +- ChatGPT does NOT access GBP directly -- sources from Bing index, Yelp, TripAdvisor, BBB, Reddit +- Bing Places is critical: powers ChatGPT, Copilot, Alexa +- AI-powered local packs (mobile US) show only 1-2 businesses, 32% fewer shown (Sterling Sky) + +**Recommendation**: Run `/seo geo ` for comprehensive AI search visibility analysis including citability scoring, llms.txt check, and brand mention audit. + +--- + +## Reference Files + +Load on-demand as needed: +- `../seo/references/local-seo-signals.md`: Ranking factors, review benchmarks, citation tiers, GBP feature status, algorithm updates +- `../seo/references/local-schema-types.md`: LocalBusiness subtypes by industry, schema patterns, citation sources per vertical + +--- + +## Output + +Generate `LOCAL-SEO-ANALYSIS-{domain}.md` with: + +1. **Local SEO Score: XX/100** with dimension breakdown table +2. **Business type**: Brick-and-mortar / SAB / Hybrid +3. **Industry vertical detected** + industry-specific findings +4. **GBP optimization checklist** (detected signals vs missing) +5. **Review health snapshot** (rating, count, velocity indicators, response patterns) +6. **NAP consistency audit** (page vs schema discrepancies, cross-source comparison) +7. **Citation presence check** (Tier 1 directory status) +8. **Local schema status** (present/missing/malformed + ready-to-use fix) +9. **Location page quality** (if multi-location: unique content %, doorway risk, store locator) +10. **Top 10 prioritized actions** (Critical > High > Medium > Low) +11. **Limitations disclaimer**: What this analysis could NOT assess (geo-grid ranking, Domain Authority, comprehensive backlinks, GBP Insights data, real-time local pack position) and which paid tools can fill those gaps + +--- + +## Quick Wins + +1. Claim and optimize Apple Business Connect (usage doubled to 27%) +2. Claim and optimize Bing Places (powers ChatGPT, Copilot, Alexa) +3. Fix any NAP discrepancies between page, schema, and GBP +4. Add LocalBusiness schema with correct industry subtype +5. Add `geo` coordinates with 5+ decimal precision +6. Ensure phone number uses `tel:` link for click-to-call +7. Add city + service keyword to title tag and H1 + +## Medium Effort + +1. Create dedicated page for each core service (Whitespark: #1 local organic factor) +2. Build review generation strategy maintaining 18-day minimum cadence +3. Submit to three data aggregators (Data Axle, Foursquare, Neustar/TransUnion) for downstream distribution +4. Claim industry-specific directory listings (per vertical recommendations) +5. Add industry-specific schema patterns (Menu for restaurants, Physician for healthcare, etc.) +6. Implement hub-and-spoke internal linking for service/location pages + +## High Impact + +1. Build local digital PR strategy targeting "best of" lists (#1 AI visibility factor) +2. Develop unique, non-swappable content for each location page (>60% unique) +3. Establish presence on platforms ChatGPT sources from (Yelp, TripAdvisor, BBB, Reddit) +4. Pursue Chamber of Commerce and BBB membership (authority + verification signals) +5. Create community involvement content (sponsorships, local events, partnerships) + +--- + +## DataForSEO Integration (Optional) + +If DataForSEO credentials or optional tools are available, use direct DataForSEO calls for live GBP data extraction, real-time local pack positions, and automated citation auditing across directories. + +--- + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site content. Suggest the user verify the URL and try again. | +| No local signals detected on page | Report that no local business indicators were found. Suggest the user confirm this is a local business and provide the GBP listing URL if available. | +| NAP not found in page HTML | Check schema and meta tags. If still absent, flag as Critical issue. Recommend adding visible NAP to footer and contact page. | +| Industry vertical unclear | Present the top two detected verticals with supporting signals. Ask the user to confirm before applying industry-specific recommendations. | +| Multi-location with 50+ location pages | Apply the quality gates from seo orchestrator: WARNING at 30+ pages (enforce 60%+ unique), HARD STOP at 50+ pages (require user justification before continuing). | + +## FLOW Framework Integration + +For prompt-guided local optimization, use `/seo flow local ` — FLOW's 11 local-stage prompts cover GBP optimization, meta descriptions, title tags, and structured local audit workflows. diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-maps/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-maps/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-maps/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-maps/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-maps/SKILL.md new file mode 100644 index 00000000..3ee1876a --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-maps/SKILL.md @@ -0,0 +1,259 @@ +--- +name: seo-maps +description: > + Maps intelligence for local SEO — geo-grid rank tracking, GBP profile + auditing via API, review intelligence across Google/Tripadvisor/Trustpilot, + cross-platform NAP verification (Google/Bing/Apple/OSM), competitor + radius mapping, and LocalBusiness schema generation from API data. + Three-tier capability: free (Overpass + Geoapify), DataForSEO (full + intelligence), DataForSEO + Google (maximum coverage). Use when user + says "maps", "geo-grid", "rank tracking", "GBP audit", "review + velocity", "competitor radius", "maps analysis", "local rank + tracking", "Share of Local Voice", or "SoLV". +user-invocable: true +argument-hint: "[command] [url|keyword|location]" +license: MIT +compatibility: "DataForSEO MCP for Tier 1+, Google Maps API for Tier 2" +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Maps Intelligence (March 2026) + +Maps platform analysis for local businesses. Works with external APIs to assess +how a business appears on Google Maps, Bing Places, Apple Maps, and OpenStreetMap. + +**Boundary with seo-local:** This skill analyzes the business on maps PLATFORMS +(via APIs). seo-local analyzes local SEO signals on the WEBSITE (via HTML fetch). +Do not duplicate seo-local on-page analysis. Recommend `/seo local ` for +website-level checks. + +--- + +## Quick Reference + +| Command | What it does | Tier | +|---------|-------------|------| +| `/seo maps ` | Full maps presence audit (auto-selects tier) | 0+ | +| `/seo maps grid ` | Geo-grid rank scan (7x7, 1 keyword default) | 1+ | +| `/seo maps reviews ` | Cross-platform review intelligence | 1+ | +| `/seo maps competitors ` | Competitor radius mapping | 0+ | +| `/seo maps nap ` | Cross-platform NAP verification | 0+ | +| `/seo maps schema ` | Generate LocalBusiness JSON-LD from data | 0+ | +| `/seo maps gbp ` | GBP completeness audit | 1+ | + +--- + +## Three-Tier Capability Detection + +Before any analysis, detect the available capability tier: + +### Tier 0 (Free) +**Detection:** DataForSEO credentials/tools not available. +**Capabilities:** Overpass API competitor discovery, Geoapify POI search, Nominatim geocoding, static GBP checklist, schema generation, cross-platform NAP guidance. +**Load:** `../seo/references/maps-free-apis.md` + +### Tier 1 (DataForSEO) +**Detection:** DataForSEO credentials are present in the selected project environment, or an optional DataForSEO adapter is already available. +**Capabilities:** Everything in Tier 0 PLUS geo-grid rank tracking, live GBP profile audit, review intelligence (velocity, sentiment, distribution), GBP post activity, Q&A data, Tripadvisor/Trustpilot reviews. +**Load:** `../seo/references/maps-api-endpoints.md` + +### Tier 2 (DataForSEO + Google Maps Platform) +**Detection:** Tier 1 available AND Google Maps API key in environment. +**Capabilities:** Everything in Tier 1 PLUS Google Places details, real-time business status, AI-powered place summaries, photo analysis. +**Note:** Google ToS restricts storage to `place_id` only. Lat/lng cached 30 days max. + +**Always communicate the detected tier to the user** at the start of analysis. + +--- + +## Geo-Grid Rank Tracking (Tier 1+) + +Simulates Google Maps searches from multiple GPS coordinates to show ranking +variation across a geographic area. Requires DataForSEO. + +**Load:** `../seo/references/maps-geo-grid.md` for algorithm, SoLV formula, heatmap format. +**Load:** `../seo/references/maps-api-endpoints.md` for Maps SERP endpoint details. + +### Workflow + +1. Geocode business address to get center lat/lng +2. Generate grid points (default: 7x7, 5km radius) using Haversine offset formula +3. **Display cost estimate and ask for confirmation before proceeding** +4. Fire DataForSEO Maps SERP API calls with `location_coordinate` per grid point +5. Find target business rank at each point +6. Calculate SoLV: `(top_3_count / total_points) * 100` +7. Render ASCII heatmap in output + +### Cost Warning (REQUIRED) + +Before every geo-grid scan, display: +``` +Geo-Grid Scan: [keyword] at [location] +Grid: 7x7 (49 points) | Keywords: [N] | Est. cost: $[amount] +DataForSEO credits will be consumed. Proceed? +``` + +--- + +## GBP Profile Audit (Tier 1 preferred, Tier 0 manual) + +Audits the 25 fields that affect Google Business Profile quality and ranking. + +**Load:** `../seo/references/maps-gbp-checklist.md` for full checklist and scoring. + +### Tier 1 Workflow + +1. Fetch business profile via DataForSEO My Business Info API (keyword or CID) +2. Map API response fields to 25-field checklist +3. Score each field: Present + Optimized = 2pts, Present = 1pt, Missing = 0pts +4. Apply industry-specific weight multipliers +5. Normalize to 0-100 scale + +### Tier 0 Workflow + +1. Fetch the business website via WebFetch +2. Extract any visible GBP signals (Maps embed, place references, review widgets) +3. Apply static checklist based on detectable signals +4. Mark undetectable fields as "Unknown (requires DataForSEO for live data)" + +--- + +## Review Intelligence (Tier 1+) + +Cross-platform review analysis: velocity, sentiment, rating distribution, fake detection. + +**Reference:** `../seo/references/local-seo-signals.md` for benchmarks (shared with seo-local). + +### Workflow + +1. Fetch Google reviews via DataForSEO Reviews API (sort by newest) +2. Calculate review velocity: reviews per month over last 6 months +3. Check 18-day rule (Sterling Sky): any 3-week gap = ranking risk +4. Analyze rating distribution: healthy = bell curve skewed to 5-star +5. Calculate owner response rate: responses / total reviews +6. Fetch Tripadvisor and Trustpilot reviews (if available) +7. Cross-platform comparison table + +### Fake Review Detection Signals + +Flag reviews matching 2+ of these patterns: +- Uniform timing (multiple reviews same day/hour) +- Reviewer accounts with limited history or single review +- Geographic inconsistencies (reviewer location vs business location) +- Exclusively 5-star velocity spike (vs historical baseline) +- Identical or near-identical text across reviews +- Sudden volume spike without corresponding marketing activity + +--- + +## Competitor Radius Mapping (Tier 0+) + +Identify and analyze competitors within a defined radius. + +### Tier 0 (Overpass API) + +**Load:** `../seo/references/maps-free-apis.md` for query templates. + +1. Geocode business address +2. Query Overpass API for businesses with same OSM tag within radius +3. Parse results: name, address, phone, website, distance from center +4. Sort by distance, present as competitor landscape table + +### Tier 1 (DataForSEO) + +1. Use Maps SERP API with business keyword + location +2. Extract top 20 competitors with full profile data +3. Compare: rating, review count, categories, photos, attributes +4. Calculate competitive density score: competitors per km^2 + +--- + +## Cross-Platform NAP Verification (Tier 0+) + +Check business listing consistency across Google, Bing Places, Apple, and OSM. + +### Workflow + +1. Search for business name on each platform: + - Google: infer from GBP data or Maps SERP result + - Bing: `WebFetch https://www.bing.com/maps?q=BUSINESS+NAME+LOCATION` + - Apple: manual check (no public API -- recommend Apple Business Connect at businessconnect.apple.com) + - OSM: Overpass or Nominatim search +2. Extract NAP (Name, Address, Phone) from each source +3. Compare for consistency: exact match, partial match, missing, or conflicting +4. Flag discrepancies as Critical (name mismatch), High (address mismatch), Medium (phone mismatch) +5. Recommend claiming unclaimed profiles + +--- + +## Schema Generation (Tier 0+) + +Generate LocalBusiness JSON-LD markup from collected data. + +**Reference:** `../seo/references/local-schema-types.md` for industry subtypes (shared with seo-local). + +### Workflow + +1. Determine most specific schema subtype for the industry +2. Populate required properties: `@type`, `name`, `address`, `image` +3. Add recommended properties: `telephone`, `url`, `geo`, `openingHoursSpecification`, `priceRange` +4. Add strategic properties for multi-location: `branchOf`, `areaServed`, `sameAs` +5. Add `aggregateRating` if review data available +6. Output valid JSON-LD block ready for implementation + +**Do NOT generate self-serving review markup** -- Google ignores LocalBusiness review markup from the business itself. Only mark up third-party reviews visible on the page. + +--- + +## Reference Files + +Load on-demand as needed (do NOT load all at startup): +- `../seo/references/maps-api-endpoints.md`: DataForSEO endpoint details, params, costs +- `../seo/references/maps-free-apis.md`: Overpass, Geoapify, Nominatim query templates +- `../seo/references/maps-geo-grid.md`: Grid algorithm, SoLV formula, heatmap rendering +- `../seo/references/maps-gbp-checklist.md`: 25-field GBP audit with industry weights +- `../seo/references/local-seo-signals.md`: Ranking factors, review benchmarks (shared) +- `../seo/references/local-schema-types.md`: LocalBusiness subtypes by industry (shared) + +--- + +## Output + +Generate `MAPS-ANALYSIS-{domain}.md` with: + +1. **Maps Health Score: XX/100** with dimension breakdown table +2. **Capability tier detected** (Tier 0 or Tier 1) with explanation of what's available +3. **Geo-grid heatmap** (Tier 1): ASCII grid with SoLV percentage and average rank +4. **GBP profile audit**: field-by-field scoring with industry-specific weights +5. **Review intelligence**: velocity chart, rating distribution, response rate, cross-platform comparison +6. **Competitor landscape**: count in radius, top 5 by rating/reviews, competitive density +7. **Cross-platform presence**: Google/Bing/Apple/OSM listing status +8. **Schema recommendation**: generated LocalBusiness JSON-LD (if missing or incomplete) +9. **Top 10 prioritized actions** (Critical > High > Medium > Low) +10. **Cost report**: DataForSEO credits consumed during analysis (Tier 1 only) +11. **Limitations disclaimer**: what could not be assessed at current tier + +--- + +## Cross-Skill Delegation + +- Website on-page local signals: recommend `/seo local ` +- Full AI search visibility: recommend `/seo geo ` +- Schema validation and fixes: recommend `/seo schema ` +- Live SERP and keyword data: recommend `/seo dataforseo [command]` + +--- + +## Error Handling + +| Scenario | Action | +|----------|--------| +| DataForSEO MCP not available | Drop to Tier 0. Inform user: "DataForSEO not detected. Running free-tier analysis. For geo-grid tracking and review intelligence, install the DataForSEO extension." | +| Business not found in Maps SERP | Try My Business Info with keyword. If still not found, report "Business not found in Google Maps for this location." | +| Geocoding fails (Nominatim) | Ask user to provide coordinates or a more specific address. | +| API rate limit hit | Report the limit. Suggest waiting or using standard (queued) method instead of live. | +| No reviews found | Report zero review state. Recommend review generation strategy with 18-day cadence target. | +| Multi-location detected | Ask user which location to analyze, or offer batch mode with per-location cost estimate. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-page/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-page/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-page/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-page/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-page/SKILL.md new file mode 100644 index 00000000..af88c753 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-page/SKILL.md @@ -0,0 +1,94 @@ +--- +name: seo-page +description: > + Deep single-page SEO analysis covering on-page elements, content quality, + technical meta tags, schema, images, and performance. Use when user says + "analyze this page", "check page SEO", "single URL", "check this page", + "page analysis", or provides a single URL for review. +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Single Page Analysis + +## What to Analyze + +### On-Page SEO +- Title tag: 50-60 characters, includes primary keyword, unique +- Meta description: 150-160 characters, compelling, includes keyword +- H1: exactly one, matches page intent, includes keyword +- H2-H6: logical hierarchy (no skipped levels), descriptive +- URL: short, descriptive, hyphenated, no parameters +- Internal links: sufficient, relevant anchor text, no orphan pages +- External links: to authoritative sources, reasonable count + +### Content Quality +- Word count vs page type minimums (see quality-gates.md) +- Readability: Flesch Reading Ease score, grade level +- Keyword density: natural (1-3%), semantic variations present +- E-E-A-T signals: author bio, credentials, first-hand experience markers +- Content freshness: publication date, last updated date + +### Technical Elements +- Canonical tag: present, self-referencing or correct +- Meta robots: index/follow unless intentionally blocked +- Open Graph: og:title, og:description, og:image, og:url +- Twitter Card: twitter:card, twitter:title, twitter:description +- Hreflang: if multi-language, correct implementation + +### Schema Markup +- Detect all types (JSON-LD preferred) +- Validate required properties +- Identify missing opportunities +- NEVER recommend HowTo (deprecated) or FAQ for rich results (retired May 2026); keep existing FAQPage as an AI-citation signal, use QAPage for genuine Q&A + +### Images +- Alt text: present, descriptive, includes keywords where natural +- File size: flag >200KB (warning), >500KB (critical) +- Format: recommend WebP/AVIF over JPEG/PNG +- Dimensions: width/height set for CLS prevention +- Lazy loading: report `lazy_method` per image (native | perfmatters | ewww | js-generic | none). Do not flag "not lazy-loaded" when JS lazy-loaders (Perfmatters, EWWW, lazysizes) are detected — they intentionally strip the native `loading="lazy"` attribute and use `data-src` placeholders + +### Core Web Vitals (reference only, not measurable from HTML alone) +- Flag potential LCP issues (huge hero images, render-blocking resources) +- Flag potential INP issues (heavy JS, no async/defer) +- Flag potential CLS issues (missing image dimensions, injected content) + +## Output + +### Page Score Card +``` +Overall Score: XX/100 + +On-Page SEO: XX/100 ████████░░ +Content Quality: XX/100 ██████████ +Technical: XX/100 ███████░░░ +Schema: XX/100 █████░░░░░ +Images: XX/100 ████████░░ +``` + +### Issues Found +Organized by priority: Critical -> High -> Medium -> Low + +### Recommendations +Specific, actionable improvements with expected impact + +### Schema Suggestions +Ready-to-use JSON-LD code for detected opportunities + +## DataForSEO Integration (Optional) + +If DataForSEO credentials or optional tools are available, use direct DataForSEO calls for real SERP positions and backlink data with spam scores. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess page content. Suggest the user verify the URL and try again. | +| Page requires authentication (401/403) | Report that the page is behind authentication. Suggest the user provide the rendered HTML directly or a publicly accessible URL. | +| JavaScript-rendered content (empty body in HTML) | Note that key content may be rendered client-side. Analyze the available HTML and flag that results may be incomplete. Suggest using a browser-rendered snapshot if available. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-plan/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-plan/SKILL.md new file mode 100644 index 00000000..0c393260 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/SKILL.md @@ -0,0 +1,126 @@ +--- +name: seo-plan +description: > + Strategic SEO planning for new or existing websites. Industry-specific + templates, competitive analysis, content strategy, and implementation + roadmap. Use when user says "SEO plan", "SEO strategy", "SEO planning", + "content strategy", "keyword strategy", "content calendar", + "site architecture", or "SEO roadmap". +user-invocable: true +argument-hint: "[business-type]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Strategic SEO Planning + +## Process + +### 1. Discovery +- Business type, target audience, competitors, goals +- Current site assessment (if exists) +- Budget and timeline constraints +- Key performance indicators (KPIs) + +### 2. Competitive Analysis +- Identify top 5 competitors +- Analyze their content strategy, schema usage, technical setup +- Identify keyword gaps and content opportunities +- Assess their E-E-A-T signals +- Estimate their domain authority + +### 3. Architecture Design +- Load industry template from `assets/` directory +- Design URL hierarchy and content pillars +- Plan internal linking strategy +- Sitemap structure with quality gates applied +- Information architecture for user journeys + +### 4. Content Strategy +- Content gaps vs competitors +- Page types and estimated counts +- Blog/resource topics and publishing cadence +- E-E-A-T building plan (author bios, credentials, experience signals) +- Content calendar with priorities + +### 5. Technical Foundation +- Hosting and performance requirements +- Schema markup plan per page type +- Core Web Vitals baseline targets +- AI search readiness requirements +- Mobile-first considerations + +### 6. Implementation Roadmap (4 phases) + +#### Phase 1: Foundation (weeks 1-4) +- Technical setup and infrastructure +- Core pages (home, about, contact, main services) +- Essential schema implementation +- Analytics and tracking setup + +#### Phase 2: Expansion (weeks 5-12) +- Content creation for primary pages +- Blog launch with initial posts +- Internal linking structure +- Local SEO setup (if applicable) + +#### Phase 3: Scale (weeks 13-24) +- Advanced content development +- Link building and outreach +- GEO optimization +- Performance optimization + +#### Phase 4: Authority (months 7-12) +- Thought leadership content +- PR and media mentions +- Advanced schema implementation +- Continuous optimization + +## Industry Templates + +Load from `assets/` directory: +- `saas.md`: SaaS/software companies +- `local-service.md`: Local service businesses +- `ecommerce.md`: E-commerce stores +- `publisher.md`: Content publishers/media +- `agency.md`: Agencies and consultancies +- `generic.md`: General business template + +## Output + +### Deliverables +- `SEO-STRATEGY.md`: Complete strategic plan +- `COMPETITOR-ANALYSIS.md`: Competitive insights +- `CONTENT-CALENDAR.md`: Content roadmap +- `IMPLEMENTATION-ROADMAP.md`: Phased action plan +- `SITE-STRUCTURE.md`: URL hierarchy and architecture + +### KPI Targets +| Metric | Baseline | 3 Month | 6 Month | 12 Month | +|--------|----------|---------|---------|----------| +| Organic Traffic | ... | ... | ... | ... | +| Keyword Rankings | ... | ... | ... | ... | +| Domain Authority | ... | ... | ... | ... | +| Indexed Pages | ... | ... | ... | ... | +| Core Web Vitals | ... | ... | ... | ... | + +### Success Criteria +- Clear, measurable goals per phase +- Resource requirements defined +- Dependencies identified +- Risk mitigation strategies + +## DataForSEO Integration (Optional) + +If DataForSEO credentials or optional tools are available, use direct DataForSEO calls for real competitive intelligence, traffic estimates, keyword volume and difficulty, and local business data. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| Unrecognized business type | Fall back to `generic.md` template. Inform user that no industry-specific template was found and proceed with the general business template. | +| No website URL provided | Proceed with new-site planning mode. Skip current site assessment and competitive gap analysis that require a live URL. | +| Industry template not found | Check `assets/` directory for available templates. If the requested template file is missing, use `generic.md` and note the missing template in output. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/agency.md b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/agency.md new file mode 100644 index 00000000..6d236edc --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/agency.md @@ -0,0 +1,175 @@ + +# Agency/Consultancy SEO Strategy Template + +## Industry Characteristics + +- Service-based, high-value transactions +- Expertise and trust are paramount +- Long consideration cycles +- Portfolio/case study driven decisions +- Relationship-based sales +- Niche specialization benefits + +## Recommended Site Architecture + +``` +/ +├── Home +├── /services +│ ├── /service-1 +│ │ ├── /sub-service-1 +│ │ └── ... +│ └── /service-2 +├── /industries +│ ├── /industry-1 +│ ├── /industry-2 +│ └── ... +├── /work (or /case-studies) +│ ├── /case-study-1 +│ ├── /case-study-2 +│ └── ... +├── /about +│ ├── /team +│ │ ├── /team-member-1 +│ │ └── ... +│ ├── /culture +│ └── /careers +├── /insights (or /blog) +│ ├── /articles +│ ├── /guides +│ ├── /webinars +│ └── /podcasts +├── /contact +├── /process +└── /faq +``` + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | Organization, ProfessionalService | +| Service Page | Service, ProfessionalService | +| Case Study | Article, Organization (client) | +| Team Member | Person, ProfilePage | +| Blog | Article, BlogPosting | + +### ProfessionalService Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "ProfessionalService", + "name": "Agency Name", + "description": "What the agency does", + "url": "https://example.com", + "logo": "https://example.com/logo.png", + "address": { + "@type": "PostalAddress", + "streetAddress": "123 Agency St", + "addressLocality": "City", + "addressRegion": "State", + "postalCode": "12345" + }, + "telephone": "+1-555-555-5555", + "areaServed": "National", + "hasOfferCatalog": { + "@type": "OfferCatalog", + "name": "Services", + "itemListElement": [ + { + "@type": "Offer", + "itemOffered": { + "@type": "Service", + "name": "Service 1" + } + } + ] + } +} +``` + +## E-E-A-T Requirements + +### Team Pages Must Include +- Professional headshots +- Detailed bios with credentials +- Industry experience +- Speaking engagements +- Publications +- Social profiles + +### Case Studies Must Include +- Client name (with permission) or industry +- Challenge/problem statement +- Approach/methodology +- Results with specific metrics +- Timeline +- Testimonial quote + +## Content Priorities + +### High Priority +1. Service pages (detailed, specific) +2. Industry pages (vertical expertise) +3. 3-5 detailed case studies +4. Team/leadership pages + +### Medium Priority +1. Methodology/process page +2. Blog with thought leadership +3. Comparison content (vs alternatives) +4. FAQ page + +### Thought Leadership Topics +- Industry trend analysis +- How-to guides (non-competitive) +- Original research/surveys +- Event recaps and insights +- Expert interviews +- Tool/technology reviews + +## Content Strategy + +### Service Pages (min 800 words) +- Clear value proposition +- Methodology overview +- Deliverables list +- Relevant case studies +- Team members who deliver this service +- CTA to schedule consultation + +### Industry Pages (min 800 words) +- Industry-specific challenges +- How you solve them differently +- Relevant case studies +- Industry credentials/experience +- Client logos (with permission) + +### Case Studies (min 1,000 words) +- Executive summary +- Client background +- Challenge details +- Solution approach +- Implementation process +- Measurable results +- Client testimonial +- Related services/CTA + +## Key Metrics to Track + +- Organic traffic to service pages +- Case study page views +- Contact form submissions from organic +- Time on page for key content +- Blog → service page conversion + +## Generative Engine Optimization (GEO) for Agencies + +- [ ] Publish original case studies with specific, citable metrics and results +- [ ] Use Person schema with sameAs links for all team members (builds entity authority) +- [ ] Use ProfilePage schema for team member pages +- [ ] Include clear, quotable expertise statements in service page descriptions +- [ ] Produce original industry research and surveys AI systems can cite +- [ ] Structure thought leadership content with clear headings and extractable insights +- [ ] Maintain consistent agency entity information across directories, social profiles, and industry sites +- [ ] Monitor AI citation in ChatGPT, Perplexity, and Google AI Overviews for brand and key service terms diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/ecommerce.md b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/ecommerce.md new file mode 100644 index 00000000..10da63c6 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/ecommerce.md @@ -0,0 +1,167 @@ + +# E-commerce SEO Strategy Template + +## Industry Characteristics + +- High transaction intent +- Product comparison behavior +- Price sensitivity +- Visual-first decision making +- Seasonal demand patterns +- Competitive marketplace listings + +## Recommended Site Architecture + +``` +/ +├── Home +├── /collections (or /categories) +│ ├── /category-1 +│ │ ├── /subcategory-1 +│ │ └── ... +│ ├── /category-2 +│ └── ... +├── /products +│ ├── /product-1 +│ ├── /product-2 +│ └── ... +├── /brands +│ ├── /brand-1 +│ └── ... +├── /sale (or /deals) +├── /new-arrivals +├── /best-sellers +├── /gift-guide +├── /blog +│ ├── /buying-guides +│ ├── /how-to +│ └── /trends +├── /about +├── /contact +├── /shipping +├── /returns +└── /faq +``` + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Product Page | Product, Offer, AggregateRating, Review, BreadcrumbList | +| Category Page | CollectionPage, ItemList, BreadcrumbList | +| Brand Page | Brand, Organization | +| Blog | Article, BlogPosting | + +### Additional E-commerce Schema (2025) + +- **ProductGroup**: Use for products with variants (size, color). Wraps individual Product entries with `variesBy` and `hasVariant` properties. See `schema/templates.json`. +- **Certification**: For product certifications (Energy Star, safety, organic). Replaced EnergyConsumptionDetails (April 2025). Use `hasCertification` on Product. +- **OfferShippingDetails**: Include shipping rate, handling time, and transit time. Critical for Merchant Center eligibility. + +> **Google Merchant Center Free Listings:** Products can appear in Google Shopping for free. Ensure Product structured data is in the initial server-rendered HTML (not JavaScript-injected) with required properties: `name`, `image`, `price`, `priceCurrency`, `availability`. + +> **JS Rendering Note:** Product structured data should be in initial server-rendered HTML: not dynamically injected via JavaScript (per December 2025 Google JS SEO guidance). + +### Product Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "Product", + "name": "Product Name", + "image": ["https://example.com/product.jpg"], + "description": "Product description", + "sku": "SKU123", + "brand": { + "@type": "Brand", + "name": "Brand Name" + }, + "offers": { + "@type": "Offer", + "price": "99.99", + "priceCurrency": "USD", + "availability": "https://schema.org/InStock", + "url": "https://example.com/product" + }, + "aggregateRating": { + "@type": "AggregateRating", + "ratingValue": "4.5", + "reviewCount": "42" + } +} +``` + +## Content Requirements + +### Product Pages (min 400 words) +- Unique product descriptions (not manufacturer copy) +- Feature highlights +- Use cases / who it's for +- Specifications table +- Size/fit guide (for apparel) +- Care instructions +- Customer reviews + +### Category Pages (min 400 words) +- Category introduction +- Buying guide excerpt +- Featured products +- Subcategory links +- Filter/sort options + +## Technical Considerations + +### Pagination +- Use rel="next"/rel="prev" or load-more +- Ensure all products are crawlable +- Canonical to main category page + +### Faceted Navigation +- Noindex filter combinations that create duplicate content +- Use canonical tags appropriately +- Ensure popular filters are indexable + +### Product Variations +- Single URL for parent product with variants +- Or separate URLs with canonical to parent +- Structured data for all variants + +## Content Priorities + +### High Priority +1. Category pages (top level) +2. Best-selling product pages +3. Homepage +4. Buying guides for main categories + +### Medium Priority +1. Subcategory pages +2. Brand pages +3. Comparison content +4. Seasonal landing pages + +### Blog Topics +- Buying guides ("How to Choose...") +- Product comparisons +- Trend reports +- Use cases and inspiration +- Care and maintenance guides + +## Key Metrics to Track + +- Revenue from organic search +- Product page rankings +- Category page rankings +- Click-through rate (rich results) +- Average order value from organic + +## Generative Engine Optimization (GEO) for E-commerce + +AI search platforms increasingly answer product queries directly. Optimize for AI citation: + +- [ ] Include clear product specifications, dimensions, materials in structured format +- [ ] Use ProductGroup schema for variant products +- [ ] Provide original product photography with descriptive alt text +- [ ] Include genuine customer review content (AggregateRating schema) +- [ ] Maintain consistent product entity data across all platforms (site, Amazon, Merchant Center) +- [ ] Structure comparison content with clear feature tables AI can parse +- [ ] Add detailed FAQ content for common product questions diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/generic.md b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/generic.md new file mode 100644 index 00000000..afb88f44 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/generic.md @@ -0,0 +1,144 @@ + +# Generic Business SEO Strategy Template + +## Overview + +This template applies to businesses that don't fit neatly into SaaS, local service, e-commerce, publisher, or agency categories. Customize based on your specific business model. + +## Recommended Site Architecture + +``` +/ +├── Home +├── /products (or /services) +│ ├── /product-1 +│ ├── /product-2 +│ └── ... +├── /solutions (if applicable) +│ ├── /solution-1 +│ └── ... +├── /about +│ ├── /team +│ ├── /history +│ └── /values +├── /resources +│ ├── /blog +│ ├── /guides +│ ├── /faq +│ └── /glossary +├── /contact +├── /support +└── /legal + ├── /privacy + └── /terms +``` + +## Universal SEO Principles + +### Every Page Should Have +- Unique title tag (30-60 chars) +- Unique meta description (120-160 chars) +- Single H1 matching page intent +- Logical heading hierarchy (H1→H2→H3) +- Internal links to related content +- Clear call-to-action + +### Schema for All Sites +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | Organization, WebSite | +| About | Organization, AboutPage | +| Contact | ContactPage | +| Blog | Article, BlogPosting | +| FAQ | QAPage for genuine Q&A; FAQPage no longer yields rich results (retired May 2026) but still aids AI citation | +| Product/Service | Product or Service | + +## Content Quality Standards + +### Minimum Word Counts +| Page Type | Min Words | +|-----------|-----------| +| Homepage | 500 | +| Product/Service | 800 | +| Blog Post | 1,500 | +| About Page | 400 | +| Landing Page | 600 | + +### E-E-A-T Essentials +1. **Experience**: Share real examples and case studies +2. **Expertise**: Display credentials and qualifications +3. **Authoritativeness**: Earn mentions and citations +4. **Trustworthiness**: Full contact info, policies visible + +## Technical Foundations + +### Must-Haves +- [ ] HTTPS enabled +- [ ] Mobile-responsive design +- [ ] robots.txt configured +- [ ] XML sitemap submitted +- [ ] Google Search Console verified +- [ ] Core Web Vitals passing (LCP <2.5s, INP <200ms, CLS <0.1) + +### Should-Haves +- [ ] Structured data on key pages +- [ ] Internal linking strategy +- [ ] 404 error page optimized +- [ ] Redirect chains eliminated +- [ ] Image optimization (WebP, lazy loading) + +## Content Priorities + +### Phase 1: Foundation (weeks 1-4) +1. Homepage optimization +2. Core product/service pages +3. About and contact pages +4. Basic schema implementation + +### Phase 2: Expansion (weeks 5-12) +1. Blog launch (2-4 posts/month) +2. FAQ page +3. Additional product/service pages +4. Internal linking audit + +### Phase 3: Growth (weeks 13-24) +1. Consistent content publishing +2. Link building outreach +3. GEO optimization +4. Performance optimization + +### Phase 4: Authority (months 7-12) +1. Thought leadership content +2. Original research +3. PR and media mentions +4. Advanced schema + +## Key Metrics to Track + +- Organic traffic (overall and by section) +- Keyword rankings (branded and non-branded) +- Conversion rate from organic +- Pages indexed +- Core Web Vitals scores +- Backlinks acquired + +## Customization Points + +Adjust this template based on: + +1. **Business Model**: B2B vs B2C vs D2C +2. **Geographic Scope**: Local, national, or international +3. **Content Type**: Product-focused vs content-heavy +4. **Competition Level**: Niche vs competitive market +5. **Resources**: Budget and team capacity + +## Generative Engine Optimization (GEO) Checklist + +- [ ] Include clear, quotable facts and statistics that AI systems can extract and cite +- [ ] Use structured data (Schema.org) to help AI systems understand content +- [ ] Build topical authority through comprehensive content clusters +- [ ] Provide original data, research, or unique perspectives AI cannot find elsewhere +- [ ] Maintain consistent entity information (brand, people, products) across the web +- [ ] Structure content with clear headings, definitions, and step-by-step formats +- [ ] Consider adding an `llms.txt` file at site root (emerging convention for AI crawlers: Google treats it as a regular text file) +- [ ] Monitor AI citation across Google AI Overviews, ChatGPT, Perplexity, and Bing Copilot diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/local-service.md b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/local-service.md new file mode 100644 index 00000000..a60b56a3 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/local-service.md @@ -0,0 +1,160 @@ + +# Local Service Business SEO Strategy Template + +## Industry Characteristics + +- Geographic-focused searches +- High intent, quick decision making +- Reviews heavily influence decisions +- Phone calls are primary conversion +- Mobile-first user behavior +- Emergency/urgent service needs + +## Recommended Site Architecture + +``` +/ +├── Home +├── /services +│ ├── /service-1 +│ ├── /service-2 +│ └── ... +├── /locations +│ ├── /city-1 +│ │ ├── /service-1-city-1 +│ │ └── ... +│ ├── /city-2 +│ └── ... +├── /about +├── /reviews +├── /gallery (or /portfolio) +├── /blog +├── /contact +├── /emergency (if applicable) +└── /faq +``` + +## Quality Gates + +### Location Page Limits +- ⚠️ **WARNING** at 30+ location pages +- 🛑 **HARD STOP** at 50+ location pages + +### Unique Content Requirements +| Page Type | Min Words | Unique % | +|-----------|-----------|----------| +| Primary Location | 600 | 60%+ | +| Service Area | 500 | 40%+ | +| Service Page | 800 | 100% | + +### What Makes Location Pages Unique +- Local landmarks and neighborhoods +- Specific services offered at that location +- Local team members +- Location-specific testimonials +- Community involvement +- Local regulations or considerations + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | LocalBusiness, Organization | +| Service Pages | Service, LocalBusiness | +| Location Pages | LocalBusiness (with geo) | +| Contact | ContactPage, LocalBusiness | +| Reviews | LocalBusiness (with AggregateRating) | + +### LocalBusiness Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "LocalBusiness", + "name": "Business Name", + "address": { + "@type": "PostalAddress", + "streetAddress": "123 Main St", + "addressLocality": "City", + "addressRegion": "State", + "postalCode": "12345" + }, + "telephone": "+1-555-555-5555", + "openingHours": "Mo-Fr 08:00-18:00", + "geo": { + "@type": "GeoCoordinates", + "latitude": "40.7128", + "longitude": "-74.0060" + }, + "areaServed": ["City 1", "City 2"], + "priceRange": "$$" +} +``` + +## Google Business Profile Integration + +- Ensure NAP consistency (Name, Address, Phone) +- Sync service categories +- Regular post updates +- Photo uploads +- Review response strategy + +### Google Business Profile Updates (2025-2026) + +- **Video verification** is now standard: postcard verification has been largely phased out. Prepare for a short video verification process showing the business location or service area. +- **WhatsApp integration** replaced Google Business Chat (deprecated). Businesses can connect WhatsApp as their primary messaging channel. +- **Q&A removed from Maps**: replaced by AI-generated answers. Ensure your GBP description, services, and website FAQ are comprehensive, as Google AI uses them to answer queries. +- **Business hours are a top-5 ranking factor**: "Business is open at time of search" ranked as a top individual factor for the first time (Whitespark 2026 Local Search Ranking Factors Report). Keep hours accurate; consider extended hours if feasible. +- **Review "Stories" format**: Google Maps now shows review snippets in a swipeable Stories format on mobile. Encourage detailed, descriptive reviews with photos. + +### Service Area Business (SAB) Update (June 2025) + +Google updated SAB guidelines to **disallow entire states or countries** as service areas. SABs must specify: cities, postal/ZIP codes, or neighborhoods. If you serve an entire metro area, list the major cities within it rather than the state. + +### AI Visibility for Local Businesses + +AI Overviews appear for only ~0.14% of local keywords (March 2025 data), local SEO faces significantly less AI disruption than other verticals. However, ChatGPT and Perplexity are increasingly used for local recommendations. + +To optimize for AI local visibility: +- Ensure presence on expert-curated "best of" lists (ranked #1 AI visibility factor in Whitespark 2026 report) +- Maintain consistent NAP (Name, Address, Phone) across all platforms +- Build genuine review volume and quality +- Use LocalBusiness schema with complete properties (geo, openingHours, priceRange, areaServed) + +## Content Priorities + +### High Priority +1. Homepage with clear service area +2. Core service pages +3. Primary city page +4. Contact page with all locations + +### Medium Priority +1. Service + location combination pages +2. FAQ page +3. About/team page +4. Reviews/testimonials page + +### Blog Topics +- Seasonal maintenance tips +- How to choose a [service provider] +- Warning signs of [problem] +- DIY vs professional comparisons +- Local regulations and permits + +## Key Metrics to Track + +- Local pack rankings +- Phone call volume from organic +- Direction requests +- Google Business Profile insights +- Reviews count and rating + +## Generative Engine Optimization (GEO) for Local + +- [ ] Include clear, quotable service descriptions and pricing ranges +- [ ] Use LocalBusiness schema with complete geo, openingHours, and areaServed +- [ ] Build presence on curated "best of" and local directory lists +- [ ] Maintain consistent NAP across all platforms (Google, Yelp, Apple Maps) +- [ ] Include original photos of work, team, and location +- [ ] Structure FAQ content for common local service questions +- [ ] Monitor AI citation in ChatGPT and Perplexity local recommendations diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/publisher.md b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/publisher.md new file mode 100644 index 00000000..55d75e41 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/publisher.md @@ -0,0 +1,153 @@ + +# Publisher/Media SEO Strategy Template + +## Industry Characteristics + +- High content volume +- Time-sensitive content (news) +- Ad revenue dependent on traffic +- Authority and trust critical +- Competing with social platforms +- AI Overviews impact on traffic + +## Recommended Site Architecture + +``` +/ +├── Home +├── /news (or /latest) +├── /topics +│ ├── /topic-1 +│ ├── /topic-2 +│ └── ... +├── /authors +│ ├── /author-1 +│ └── ... +├── /opinion +├── /reviews +├── /guides +├── /videos +├── /podcasts +├── /newsletter +├── /about +│ ├── /editorial-policy +│ ├── /corrections +│ └── /contact +└── /[year]/[month]/[slug] (article URLs) +``` + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Article | NewsArticle or Article, Person (author), Organization (publisher) | +| Author Page | Person, ProfilePage | +| Topic Page | CollectionPage, ItemList | +| Homepage | WebSite, Organization | +| Video | VideoObject | +| Podcast | PodcastEpisode, PodcastSeries | + +### NewsArticle Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "NewsArticle", + "headline": "Article Headline", + "datePublished": "2026-02-07T10:00:00Z", + "dateModified": "2026-02-07T14:30:00Z", + "author": { + "@type": "Person", + "name": "Author Name", + "url": "https://example.com/authors/author-name" + }, + "publisher": { + "@type": "Organization", + "name": "Publication Name", + "logo": { + "@type": "ImageObject", + "url": "https://example.com/logo.png" + } + }, + "image": ["https://example.com/article-image.jpg"], + "mainEntityOfPage": { + "@type": "WebPage", + "@id": "https://example.com/article-url" + } +} +``` + +## E-E-A-T Requirements + +Publishers face highest E-E-A-T scrutiny. + +### Author Pages Must Include +- Full name and photo +- Bio and credentials +- Areas of expertise +- Contact information +- Social profiles (sameAs) +- Previous articles by this author + +### Editorial Standards +- Clear correction policy +- Transparent editorial process +- Fact-checking procedures +- Conflict of interest disclosures + +## Content Priorities + +### High Priority +1. Breaking news (speed matters) +2. Evergreen guides on core topics +3. Author pages with credentials +4. Topic hubs/pillar pages + +### Medium Priority +1. Opinion/analysis pieces +2. Video content +3. Interactive content +4. Newsletter landing pages + +### GEO Considerations +- Clear, quotable facts in articles +- Tables for data-heavy content +- Expert quotes with attribution +- Update dates prominently displayed +- Structured headings (H2/H3) +- First-party data and original research are highly cited by AI systems +- Ensure author entities are clearly defined with Person schema + sameAs links +- Monitor AI citation frequency across Google AI Overviews, AI Mode, ChatGPT, Perplexity +- Treat AI citation as a standalone KPI alongside organic traffic + +### Publisher SEO Updates (2025-2026) + +- **Google News automatic inclusion:** Google News no longer accepts manual applications (since March 2025). Inclusion is fully automatic based on Google's content quality criteria. Focus on Google News sitemap markup and consistent, high-quality publishing cadence. +- **KPI shift:** Traffic-based KPIs (sessions, pageviews) are declining in relevance as AI Overviews reduce click-through rates. Leading publishers are shifting to: subscriber conversions, time on page, scroll depth, newsletter signups, AI citation frequency, and revenue per visitor. +- **Site reputation abuse risk:** Publishers hosting third-party content (coupons, product reviews, affiliate content) under their domain are at high risk. Google penalized Forbes, WSJ, Time, and CNN for this in late 2024. If hosting third-party content, ensure strong editorial oversight and clear first-party involvement. + +## Technical Considerations + +### Core Web Vitals +- Ad placement affects CLS +- Lazy load ads and images below fold +- Optimize hero images for LCP +- Minimize render-blocking resources + +### AMP (if used) +- Consider dropping AMP (no longer required for Top Stories) +- Ensure canonical setup is correct +- Monitor performance vs non-AMP + +### Pagination +- Proper pagination for multi-page articles +- Or infinite scroll with proper indexing +- Canonical to page 1 or full article + +## Key Metrics to Track + +- Page views from organic +- Time on page +- Pages per session +- Newsletter signups from organic +- Google News/Discover traffic +- AI Overview appearances diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/saas.md b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/saas.md new file mode 100644 index 00000000..7a42948b --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-plan/assets/saas.md @@ -0,0 +1,135 @@ + +# SaaS SEO Strategy Template + +## Industry Characteristics + +- Long sales cycles with multiple touchpoints +- Feature-focused decision making +- Comparison shopping behavior +- Heavy research phase before purchase +- Integration and ecosystem considerations + +## Recommended Site Architecture + +``` +/ +├── Home +├── /product (or /platform) +│ ├── /features +│ │ ├── /feature-1 +│ │ ├── /feature-2 +│ │ └── ... +│ ├── /integrations +│ │ ├── /integration-1 +│ │ └── ... +│ └── /security +├── /solutions +│ ├── /by-industry +│ │ ├── /industry-1 +│ │ └── ... +│ └── /by-use-case +│ ├── /use-case-1 +│ └── ... +├── /pricing +├── /customers +│ ├── /case-studies +│ │ ├── /case-study-1 +│ │ └── ... +│ └── /testimonials +├── /resources +│ ├── /blog +│ ├── /guides +│ ├── /webinars +│ ├── /templates +│ └── /glossary +├── /docs (or /help) +│ └── /api +├── /company +│ ├── /about +│ ├── /careers +│ ├── /press +│ └── /contact +└── /compare + ├── /vs-competitor-1 + └── /vs-competitor-2 +``` + +## Content Priorities + +### High Priority Pages +1. Homepage (value proposition, social proof) +2. Features overview +3. Pricing page +4. Key integrations +5. Top 3-5 use case pages + +### Medium Priority Pages +1. Individual feature pages +2. Industry solution pages +3. Case studies (2-3 detailed ones) +4. Comparison pages (vs competitors) + +### Content Marketing Focus +1. Bottom-of-funnel: Comparison guides, ROI calculators +2. Middle-of-funnel: How-to guides, best practices +3. Top-of-funnel: Industry trends, educational content + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | Organization, WebSite, SoftwareApplication | +| Product/Features | SoftwareApplication, Offer | +| Pricing | SoftwareApplication, Offer (with pricing) | +| Blog | Article, BlogPosting | +| Case Studies | Article, Organization (customer) | +| Documentation | TechArticle | + +## Key Metrics to Track + +- Organic traffic to pricing page +- Demo/trial signups from organic +- Blog → pricing page conversion +- Comparison page rankings +- Integration page performance + +## Comparison & Alternative Pages + +Comparison pages are among the highest-converting content types for SaaS, with conversion rates of **4-7%** vs. 0.5-1.8% for standard blog content (35.8% of marketers report comparison content performs "better than ever" per Intergrowth November 2025 survey). + +**Recommended page types:** +- `/{product}-vs-{competitor}`: Direct 1:1 comparison +- `/{competitor}-alternative`: Targeting competitor brand searches +- `/compare/{category}`: Category comparison hub +- `/best-{category}-tools`: Roundup-style pages + +**Best practices:** +- Include structured comparison tables with pricing, features, pros/cons +- Be factually accurate about competitors: verify claims regularly +- Include customer testimonials from users who switched +- Add FAQ content for common comparison questions (FAQPage rich results retired May 2026, but the markup still aids AI search and entity signals) +- Update regularly: stale comparison data damages credibility +- Cross-reference the `seo-competitor-pages` skill for detailed frameworks + +**Legal considerations:** +- Nominative fair use generally permits competitor brand mentions for comparison purposes +- Do NOT imply endorsement or affiliation +- Do NOT make false or unverifiable claims about competitor products +- Different jurisdictions have different trademark laws: consult legal counsel + +## Competitive Considerations + +- Monitor competitor feature releases +- Track competitor content strategies +- Identify keyword gaps in feature coverage +- Watch for new comparison opportunities + +## Generative Engine Optimization (GEO) for SaaS + +- [ ] Include clear, structured feature comparisons that AI systems can parse and cite +- [ ] Use SoftwareApplication schema with complete feature lists and pricing +- [ ] Publish original benchmark data, case studies, and ROI metrics +- [ ] Build content clusters around key product categories and use cases +- [ ] Ensure integration pages have clear, quotable descriptions +- [ ] Structure pricing information in tables AI can extract +- [ ] Monitor AI citation across Google AI Overviews, ChatGPT, and Perplexity diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-programmatic/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-programmatic/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-programmatic/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-programmatic/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-programmatic/SKILL.md new file mode 100644 index 00000000..24701ffc --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-programmatic/SKILL.md @@ -0,0 +1,178 @@ +--- +name: seo-programmatic +description: > + Programmatic SEO planning and analysis for pages generated at scale from data + sources. Covers template engines, URL patterns, internal linking automation, + thin content safeguards, and index bloat prevention. Use when user says + "programmatic SEO", "pages at scale", "dynamic pages", "template pages", + "generated pages", or "data-driven SEO". +user-invocable: true +argument-hint: "[url or plan]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Programmatic SEO Analysis & Planning + +Build and audit SEO pages generated at scale from structured data sources. +Enforces quality gates to prevent thin content penalties and index bloat. + +## Data Source Assessment + +Evaluate the data powering programmatic pages: +- **CSV/JSON files**: Row count, column uniqueness, missing values +- **API endpoints**: Response structure, data freshness, rate limits +- **Database queries**: Record count, field completeness, update frequency +- Data quality checks: + - Each record must have enough unique attributes to generate distinct content + - Flag duplicate or near-duplicate records (>80% field overlap) + - Verify data freshness; stale data produces stale pages + +## Template Engine Planning + +Design templates that produce unique, valuable pages: +- **Variable injection points**: Title, H1, body sections, meta description, schema +- **Content blocks**: Static (shared across pages) vs dynamic (unique per page) +- **Conditional logic**: Show/hide sections based on data availability +- **Supplementary content**: Related items, contextual tips, user-generated content +- Template review checklist: + - Each page must read as a standalone, valuable resource + - No "mad-libs" patterns (just swapping city/product names in identical text) + - Dynamic sections must add genuine information, not just keyword variations + +## URL Pattern Strategy + +### Common Patterns +- `/tools/[tool-name]`: Tool/product directory pages +- `/[city]/[service]`: Location + service pages +- `/integrations/[platform]`: Integration landing pages +- `/glossary/[term]`: Definition/reference pages +- `/templates/[template-name]`: Downloadable template pages + +### URL Rules +- Lowercase, hyphenated slugs derived from data +- Logical hierarchy reflecting site architecture +- No duplicate slugs; enforce uniqueness at generation time +- Keep URLs under 100 characters +- No query parameters for primary content URLs +- Consistent trailing slash usage (match existing site pattern) + +## Internal Linking Automation + +- **Hub/spoke model**: Category hub pages linking to individual programmatic pages +- **Related items**: Auto-link to 3-5 related pages based on data attributes +- **Breadcrumbs**: Generate BreadcrumbList schema from URL hierarchy +- **Cross-linking**: Link between programmatic pages sharing attributes (same category, same city, same feature) +- **Anchor text**: Use descriptive, varied anchor text. Avoid exact-match keyword repetition +- Link density: 3-5 internal links per 1000 words (match seo-content guidelines) + +## Thin Content Safeguards + +### Quality Gates + +| Metric | Threshold | Action | +|--------|-----------|--------| +| Pages without content review | 100+ | ⚠️ WARNING: require content audit before publishing | +| Pages without justification | 500+ | 🛑 HARD STOP: require explicit user approval and thin content audit | +| Unique content per page | <40% | ❌ Flag as thin content (likely penalty risk) | +| Word count per page | <300 | ⚠️ Flag for review (may lack sufficient value) | + +### Scaled Content Abuse: Enforcement Context (2025-2026) + +Google's Scaled Content Abuse policy (introduced March 2024) saw major enforcement escalation in 2025: + +- **June 2025:** Wave of manual actions targeting websites with AI-generated content at scale +- **August 2025:** SpamBrain spam update enhanced pattern detection for AI-generated link schemes and content farms +- **Result:** Google reported 45% reduction in low-quality, unoriginal content in search results post-March 2024 enforcement + +**Enhanced quality gates for programmatic pages:** +- **Content differentiation:** ≥30-40% of content must be genuinely unique between any two programmatic pages (not just city/keyword string replacement) +- **Human review:** Minimum 5-10% sample review of generated pages before publishing +- **Progressive rollout:** Publish in batches of 50-100 pages. Monitor indexing and rankings for 2-4 weeks before expanding. Never publish 500+ programmatic pages simultaneously without explicit quality review. +- **Standalone value test:** Each page should pass: "Would this page be worth publishing even if no other similar pages existed?" +- **Site reputation abuse:** If publishing programmatic content under a high-authority domain (not your own), this may trigger site reputation abuse penalties. Google began enforcing this aggressively in November 2024. + +> **Recommendation:** The WARNING gate at `<40% unique content` remains appropriate. Consider a HARD STOP at `<30%` unique content to prevent scaled content abuse risk. + +### Safe Programmatic Pages (OK at scale) +✅ Integration pages (with real setup docs, API details, screenshots) +✅ Template/tool pages (with downloadable content, usage instructions) +✅ Glossary pages (200+ word definitions with examples, related terms) +✅ Product pages (unique specs, reviews, comparison data) +✅ Data-driven pages (unique statistics, charts, analysis per record) + +### Penalty Risk (avoid at scale) +❌ Location pages with only city name swapped in identical text +❌ "Best [tool] for [industry]" without industry-specific value +❌ "[Competitor] alternative" without real comparison data +❌ AI-generated pages without human review and unique value-add +❌ Pages where >60% of content is shared template boilerplate + +### Uniqueness Calculation +Unique content % = (words unique to this page) / (total words on page) × 100 + +Measure against all other pages in the programmatic set. Shared headers, footers, and navigation are excluded from the calculation. Template boilerplate text IS included. + +## Canonical Strategy + +- Every programmatic page must have a self-referencing canonical tag +- Parameter variations (sort, filter, pagination) canonical to the base URL +- Paginated series: canonical to page 1 or use rel=next/prev +- If programmatic pages overlap with manual pages, the manual page is canonical +- No canonical to a different domain unless intentional cross-domain setup + +## Sitemap Integration + +- Auto-generate sitemap entries for all programmatic pages +- Split at 50,000 URLs per sitemap file (protocol limit) +- Use sitemap index if multiple sitemap files needed +- `` reflects actual data update timestamp (not generation time) +- Exclude noindexed programmatic pages from sitemap +- Register sitemap in robots.txt +- Update sitemap dynamically as new records are added to data source + +## Index Bloat Prevention + +- **Noindex low-value pages**: Pages that don't meet quality gates +- **Pagination**: Noindex paginated results beyond page 1 (or use rel=next/prev) +- **Faceted navigation**: Noindex filtered views, canonical to base category +- **Crawl budget**: For sites with >10k programmatic pages, monitor crawl stats in Search Console +- **Thin page consolidation**: Merge records with insufficient data into aggregated pages +- **Regular audits**: Monthly review of indexed page count vs intended count + +## Output + +### Programmatic SEO Score: XX/100 + +### Assessment Summary +| Category | Status | Score | +|----------|--------|-------| +| Data Quality | ✅/⚠️/❌ | XX/100 | +| Template Uniqueness | ✅/⚠️/❌ | XX/100 | +| URL Structure | ✅/⚠️/❌ | XX/100 | +| Internal Linking | ✅/⚠️/❌ | XX/100 | +| Thin Content Risk | ✅/⚠️/❌ | XX/100 | +| Index Management | ✅/⚠️/❌ | XX/100 | + +### Critical Issues (fix immediately) +### High Priority (fix within 1 week) +### Medium Priority (fix within 1 month) +### Low Priority (backlog) + +### Recommendations +- Data source improvements +- Template modifications +- URL pattern adjustments +- Quality gate compliance actions + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable | Report connection error with status code. Suggest verifying URL accessibility and checking for authentication requirements. | +| No programmatic pages detected | Inform user that no template-generated or data-driven page patterns were found. Suggest checking if pages use client-side rendering or if the URL points to the correct section. | +| Thin content threshold exceeded | Trigger quality gate warning. Report the unique content percentage and flag pages below 40% uniqueness. Require user acknowledgment before proceeding. | +| Quality gate violation | Halt analysis at the HARD STOP threshold (500+ pages without justification or <30% unique content). Present findings and require explicit user approval to continue. | diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-schema/LICENSE.txt b/plugins/avalonreset/seo-dungeon/skills/seo-schema/LICENSE.txt new file mode 100644 index 00000000..7b87d4d4 --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-schema/LICENSE.txt @@ -0,0 +1,4 @@ +MIT License - see repository root LICENSE file for complete terms. + +Copyright (c) 2026 AgriciDaniel +https://github.com/AgriciDaniel/claude-seo diff --git a/plugins/avalonreset/seo-dungeon/skills/seo-schema/SKILL.md b/plugins/avalonreset/seo-dungeon/skills/seo-schema/SKILL.md new file mode 100644 index 00000000..e465b3ad --- /dev/null +++ b/plugins/avalonreset/seo-dungeon/skills/seo-schema/SKILL.md @@ -0,0 +1,170 @@ +--- +name: seo-schema +description: > + Detect, validate, and generate Schema.org structured data. JSON-LD format + preferred. Use when user says "schema", "structured data", "rich results", + "JSON-LD", or "markup". +user-invocable: true +argument-hint: "[url]" +license: MIT +metadata: + author: AgriciDaniel + version: "2.2.16" + category: seo +--- + +# Schema Markup Analysis & Generation + +## Detection + +1. Scan page source for JSON-LD `