seo-ops-studio
CLAUDE.md0 starsChanged 6 days agoMITView on GitHub
This repository contains SEO Ops Studio, a Tier 4 Claude Code skill for comprehensive SEO analysis across all industries. It follows the Agent Skills open standard and the 3-layer architecture (directive, orchestration, execution). 28 sub-skills (2 SEO Ops skills + 22 core + 1 orchestrator + 1 framework integration + 2 extension mirrors), 19 sub-agents (16 core + 1 framework integration + 2 extension mirrors), and an extensible reference system cover technical SEO, content quality, schema markup, image optimization, sitemap…
- Reads credentials
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- seo-ops-agenticSkill
- seo-ops-analyzeSkill
- seo-ops-auditSkill
- seo-ops-backlinksSkill
- seo-ops-clusterSkill
- seo-ops-competitor-pagesSkill
- seo-ops-content-briefSkill
- seo-ops-contentSkill
- seo-ops-dataforseoSkill
- seo-ops-driftSkill
- seo-ops-ecommerceSkill
- seo-ops-flowSkill
- seo-ops-geoSkill
- seo-ops-googleSkill
- seo-ops-hreflangSkill
- seo-ops-image-genSkill
- seo-ops-imagesSkill
- seo-ops-localSkill
- seo-ops-mapsSkill
- seo-ops-pageSkill
- seo-ops-planSkill
- seo-ops-programmaticSkill
- seo-ops-schemaSkill
- seo-ops-setupSkill
- seo-ops-sitemapSkill
- seo-opsSkill
- seo-ops-sxoSkill
- seo-ops-technicalSkill
The file
We split this CLAUDE.md into the rules it gives an agent
9 rules. About 0 are common, 1 is distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Every /seo-ops audit ends with a Markdown report and a PDF that lists the real data sources and what was not measured.
- Very specific: line 222
Keep SKILL.md files under 500 lines / 5000 tokens
- Distinctive: line 225
Follow kebab-case naming for all skill directories
- Very specific: line 229
Test with python3 -m pytest tests/ after changes (if applicable)
- Very specific: line 234
URL validation: All scripts that connect to user-supplied URLs must use scripts/url_safety.py (validate_url_strict() plus the pinned safe …
- Very specific: line 235
OAuth tokens: Never store client_secret in the token file.
- Very specific: line 236
No hardcoded paths: Use os.path.dirname(os.path.abspath(__file__)) for relative paths, never a user-specific absolute path
- Very specific: line 250
Before presenting any PDF to the user: verify the review passes ("status": "PASS")
- Very specific: line 251
Cross-skill enforcement: After completing ANY analysis command (audit, page, technical, content, schema, geo, local, maps), offer: …
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SEO Ops Studio: Universal SEO Analysis Skill
Project Overview
This repository contains SEO Ops Studio, a Tier 4 Claude Code skill for comprehensive SEO analysis across all industries. It follows the Agent Skills open standard and the 3-layer architecture (directive, orchestration, execution). 28 sub-skills (2 SEO Ops skills + 22 core + 1 orchestrator + 1 framework integration + 2 extension mirrors), 19 sub-agents (16 core + 1 framework integration + 2 extension mirrors), and an extensible reference system cover technical SEO, content quality, schema markup, image optimization, sitemap architecture, AI search optimization, local SEO (GBP, citations, reviews, map pack), maps intelligence, semantic topic clustering, search experience optimization (SXO), SEO drift monitoring, e-commerce SEO, and international SEO with cultural adaptation profiles. Matomo is available as an optional extension for self-hosted analytics.
SEO Ops Studio layer (what this fork adds)
SEO Ops Studio is a standalone product derived from claude-seo v2.5.0 (MIT, Daniel Agrici; see CREDITS.md). The audit engine (skills/seo-ops-analyze, the seo-ops-<name> skills, agents/, scripts/, extensions/) comes from upstream. The product layer is ours, in English (Claude responds in the user's language on request):
skills/seo-ops(menu, onboarding detection, single-site audit + PDF) andskills/seo-ops-setup(API onboarding). The multi-client layer (client folders, Notion backlog, cross-site detection) lives in the private SEO Ops Studio Premium repo.scripts/ops_setup.py(credential templates and status, never prints secrets) andscripts/ops_pdf.py(HTML→PDF with real data sources, no WeasyPrint dependency). Both are inALLOWED_CORE_SCRIPTS.templates/credentials/: empty credential templates.docs/guides/: user-facing guides (APIs, service account).
Rules for the product layer:
- Credentials only in
~/.config/seo-ops-studio/. Never ask for, print, or write user secrets. Users write keys themselves. - Every
/seo-ops auditends with a Markdown report and a PDF that lists the real data sources and what was not measured. - Upstream project: AgriciDaniel/claude-seo (not a git remote here). Pull improvements manually and re-apply the rename rules (claude-seo → seo-ops-studio,
CLAUDE_SEO_→SEO_OPS_,scripts/claude-seo→scripts/seo-ops,~/.config/claude-seo→~/.config/seo-ops-studio, skillseoand/seo→seo-ops-analyze, every skill/agentseo-X→seo-ops-X). Do not rename Lighthouse's"seo"category key.
Architecture
seo-ops-studio/
CLAUDE.md # Project instructions (this file)
CONTRIBUTORS.md # Community credits (Pro Hub Challenge)
AGENTS.md # Multi-platform agent instructions (Cursor, Antigravity)
.claude-plugin/
plugin.json # Plugin manifest (v0.4.0)
marketplace.json # Marketplace catalog for distribution
skills/ # 28 sub-skills (auto-discovered; includes the 2 SEO Ops skills)
seo/ # Main orchestrator skill
SKILL.md # Entry point, routing table, core rules
references/ # On-demand knowledge files (13 files)
seo-ops-audit/SKILL.md # Full site audit with parallel agents
seo-ops-page/SKILL.md # Deep single-page analysis
seo-ops-technical/SKILL.md # Technical SEO (9 categories)
seo-ops-content/SKILL.md # E-E-A-T and content quality
seo-ops-content-brief/SKILL.md # Content brief generation
seo-ops-schema/SKILL.md # Schema.org markup detection/generation
seo-ops-sitemap/SKILL.md # XML sitemap analysis/generation
seo-ops-images/SKILL.md # Image optimization analysis
seo-ops-geo/SKILL.md # AI search / GEO optimization
seo-ops-agentic/ # Agent readiness (Lighthouse Agentic Browsing, WebMCP)
SKILL.md
references/ # Lighthouse category, access policy, discovery, WebMCP, vendor matrix
seo-ops-local/SKILL.md # Local SEO (GBP, citations, reviews, map pack)
seo-ops-maps/SKILL.md # Maps intelligence (geo-grid, GBP audit, reviews, competitors)
seo-ops-plan/SKILL.md # Strategic SEO planning
seo-ops-flow/SKILL.md # FLOW framework integration
seo-ops-programmatic/SKILL.md # Programmatic SEO at scale
seo-ops-competitor-pages/SKILL.md # Competitor comparison pages
seo-ops-hreflang/SKILL.md # International SEO / hreflang
seo-ops-google/ # Google SEO APIs
SKILL.md
references/ # API reference files (11 files)
seo-ops-backlinks/SKILL.md # Backlink profile analysis
seo-ops-cluster/ # Semantic topic clustering (v1.9.0, by Lutfiya Miller)
SKILL.md
references/ # Clustering methodology, architecture, workflow
templates/ # cluster-map.html interactive visualization
seo-ops-sxo/ # Search Experience Optimization (v1.9.0, by Florian Schmitz)
SKILL.md
references/ # Page-type taxonomy, user stories, personas, wireframes
seo-ops-drift/ # SEO drift monitoring (v1.9.0, by Dan Colta)
SKILL.md
references/ # Comparison rules (17 rules, 3 severity levels)
seo-ops-ecommerce/ # E-commerce SEO (v1.9.0, by Matej Marjanovic)
SKILL.md
references/ # Marketplace API endpoints
seo-ops-dataforseo/SKILL.md # Live SEO data via DataForSEO MCP (extension mirror)
seo-ops-image-gen/ # AI image generation for SEO assets (extension mirror)
SKILL.md
references/ # Image gen reference files (7 files)
agents/ # 19 subagents (auto-discovered)
seo-ops-technical.md # Crawlability, indexability, security
seo-ops-content.md # E-E-A-T, readability, thin content
seo-ops-schema.md # Structured data validation
seo-ops-sitemap.md # Sitemap quality gates
seo-ops-performance.md # Core Web Vitals, page speed
seo-ops-visual.md # Screenshots, mobile rendering
seo-ops-geo.md # AI crawler access, GEO, citability
seo-ops-agentic.md # Agent readiness, Lighthouse Agentic Browsing
seo-ops-local.md # GBP, NAP, citations, reviews, local schema
seo-ops-maps.md # Geo-grid, GBP audit, reviews, competitor radius
seo-ops-google.md # Google API analyst (CrUX, GSC, GA4)
seo-ops-backlinks.md # Backlink profile analyst (Moz, Bing, CC, verify)
seo-ops-dataforseo.md # DataForSEO data analyst
seo-ops-image-gen.md # SEO image audit analyst
seo-ops-cluster.md # Semantic clustering analysis
seo-ops-sxo.md # Search experience optimization
seo-ops-drift.md # SEO drift monitoring
seo-ops-ecommerce.md # E-commerce SEO analysis
seo-ops-flow.md # FLOW framework integration
hooks/ # Quality gate hooks
hooks.json # PostToolUse schema validation
scripts/ # 62 Python execution scripts
ops_setup.py # SEO Ops: credential templates and API status (never prints secrets)
ops_pdf.py # SEO Ops: HTML report to PDF with the real data sources
google_auth.py # Credential management (OAuth, SA, API key, 4-tier detection)
backlinks_auth.py # Backlink API credential management (Moz, Bing)
moz_api.py # Moz Link Explorer API (DA/PA, spam, domains, anchors)
bing_webmaster.py # Bing Webmaster Tools API (registered-site links/comparison)
commoncrawl_graph.py # Common Crawl web graph parser (PageRank, in-degree)
verify_backlinks.py # Backlink existence verification crawler
pagespeed_check.py # PSI v5 + CrUX API
crux_history.py # CrUX History API (25-week trends)
gsc_query.py # Search Console (queries, pages, sitemaps, sites)
gsc_inspect.py # URL Inspection (single + batch)
indexing_notify.py # Indexing API v3 (URL_UPDATED/URL_DELETED)
ga4_report.py # GA4 organic traffic reports
matomo_auth.py # Matomo credential management (extension)
matomo_report.py # Matomo Reporting API client (extension)
keywordseverywhere_api.py # Keywords Everywhere (Open PageRank) backlinks fallback
google_report.py # PDF/HTML report generator (WeasyPrint + matplotlib)
youtube_search.py # YouTube Data API v3
nlp_analyze.py # Cloud Natural Language API
keyword_planner.py # Google Ads Keyword Planner
fetch_page.py # Page fetcher with UA rotation
parse_html.py # HTML parser for SEO elements
capture_screenshot.py # Playwright screenshots
analyze_visual.py # Visual analysis helper
drift_baseline.py # SEO drift baseline capture (SQLite)
drift_compare.py # SEO drift comparison engine (17 rules)
drift_report.py # SEO drift HTML report generator
drift_history.py # SEO drift history query
dataforseo_costs.py # DataForSEO cost estimation and budget tracking
dataforseo_merchant.py # Google Shopping / Amazon data fetching
dataforseo_normalize.py # DataForSEO response normalization utility
sync_flow.py # FLOW prompt library sync (GitHub API, CC BY 4.0 headers, --dry-run, --ref)
url_safety.py # Canonical URL/SSRF safety module (validate, DNS-pin, safe fetch)
render_page.py # Shared headless renderer (SPA-aware, Playwright)
lcp_subparts.py # LCP subparts breakdown via CrUX API
preload_check.py # Speculation Rules / bfcache / prerender / preload detector
agent_ux_check.py # Agent-friendly page auditor
agentic_check.py # Agent-readiness HTTP auditor (robots, llms.txt, Markdown, ARD, well-known, WebMCP)
agentic_fix.py # Agent-readiness fix drafter (robots Content-Signal, llms.txt, ai-catalog, WebMCP)
lighthouse_agentic.py # Lighthouse Agentic Browsing fraction reader (PSI or saved JSON)
content_quality.py # QRG-aligned content quality detector
metadata_template.py # Templated title/description detector (title echo + stock CTA)
content_humanize.py # AI-pattern remover (rewrites AI-typical phrasing)
content_verify.py # Claim extractor + citation-gap detector
schema_generate.py # JSON-LD generators for high-leverage v2 schema types
schema_ecommerce_validate.py # Product schema validator (merchant-listing requirements)
iptc_ai_label.py # IPTC DigitalSourceType audit/injection for AI imagery
parasite_risk.py # Parasite-SEO risk scanner
gbp_deprecation_lint.py # GBP feature-deprecation linter
domain_history.py # Expired-domain heritage check
seo_updates.py # Primary-source Google updates query tool
indexnow_submit.py # IndexNow submitter
ucp_check.py # UCP (Universal Commerce Protocol) profile auditor
unlighthouse_run.py # Unlighthouse CLI wrapper (site-wide Lighthouse)
validate_backlink_report.py # Backlink report validation
portability_check.py # Cross-platform portability lint for SKILL.md files
consistency_check.py # Reference-graph gate: dead refs, routing, lock, orphans
release_sign.py # SHA-256 manifest generator for release signing
verify_release.py # Verify checkout integrity against a release manifest
sitemap_discovery.py # Sitemap discovery (robots.txt, common paths)
runtime.py # Managed runtime behind the seo-ops-studio launcher
schema/ # Schema.org JSON-LD templates
extensions/ # Optional add-on install helpers
dataforseo/ # DataForSEO MCP install scripts
firecrawl/ # Firecrawl MCP install scripts
banana/ # Banana MCP install scripts
ahrefs/ # Ahrefs MCP install scripts
bing-webmaster/ # Bing Webmaster and IndexNow install scripts
profound/ # Profound MCP install scripts
seranking/ # SE Ranking MCP install scripts
unlighthouse/ # Unlighthouse install scripts
docs/ # Extended documentationCommands
| Command | Use Case |
/seo-ops-analyze audit <url> | Full website audit with parallel subagents |
/seo-ops-analyze page <url> | Single page analysis |
/seo-ops-analyze technical <url> | Technical SEO across 9 categories |
/seo-ops-analyze content <url> | E-E-A-T and content quality |
/seo-ops-analyze content-brief <topic> | Detailed content brief: keywords, outline, internal links |
/seo-ops-analyze schema <url> | Schema markup detection, validation, generation |
/seo-ops-analyze sitemap <url> | Sitemap validation |
/seo-ops-analyze sitemap generate | Create new sitemap with industry templates |
/seo-ops-analyze images <url> | Image optimization |
/seo-ops-analyze geo <url> | AI search optimization (GEO) |
/seo-ops-analyze agentic <url> | Agent readiness (Lighthouse Agentic Browsing, AI agent access, WebMCP) |
/seo-ops-analyze local <url> | Local SEO (GBP, citations, reviews) |
/seo-ops-analyze maps [command] | Maps intelligence (geo-grid, GBP audit, competitors) |
/seo-ops-analyze backlinks <url> | Backlink profile analysis |
/seo-ops-analyze cluster <seed> | SERP-based semantic clustering |
/seo-ops-analyze sxo <url> | Search Experience Optimization |
/seo-ops-analyze drift baseline|compare|history <url> | SEO drift monitoring |
/seo-ops-analyze ecommerce <url> | E-commerce SEO |
/seo-ops-analyze hreflang [url] | Hreflang and international SEO |
/seo-ops-analyze plan <type> | Strategic planning by industry |
/seo-ops-analyze programmatic [url|plan] | Programmatic SEO analysis |
/seo-ops-analyze competitor-pages [url|generate] | Competitor comparison pages |
/seo-ops-analyze flow [stage] [url|topic] | FLOW framework prompts |
/seo-ops-analyze google [command] [url] | Google SEO APIs (GSC, PSI, CrUX, GA4) |
/seo-ops-analyze dataforseo [command] | Live SEO data (extension) |
/seo-ops-analyze image-gen [use-case] <desc> | AI image generation (extension) |
/seo-ops-analyze firecrawl [command] <url> | Full-site crawling (extension) |
/seo-ops-analyze ahrefs [command] <url> | Backlinks, organic keywords, and content data via the official Ahrefs MCP (extension) |
/seo-ops-analyze seranking [command] | AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, AI Mode (extension) |
/seo-ops-analyze profound [command] | LLM citation tracking with time-series data (extension) |
/seo-ops-analyze bing [command] <url> | Bing Webmaster Tools + IndexNow URL submission (extension) |
/seo-ops-analyze unlighthouse <url> | Multi-page Lighthouse runner, runs locally (extension) |
Development Rules
- Keep SKILL.md files under 500 lines / 5000 tokens
- Reference files should be focused and under 200 lines
- Scripts must have docstrings, CLI interface, and JSON output
- Follow kebab-case naming for all skill directories
- Agents invoked via Agent tool, never via Bash
- Bundled tools run through
"${CLAUDE_PLUGIN_ROOT}/scripts/seo-ops" run; plugin state usesCLAUDE_PLUGIN_DATA - Manual Python dependencies install into
~/.claude/skills/seo-ops-analyze/.venv/ - Test with
python3 -m pytest tests/after changes (if applicable)
Security Rules
- Never commit credentials:
.env,client_secret*.json,oauth-token.json,service_account*.jsonare all in.gitignore - URL validation: All scripts that connect to user-supplied URLs must use
scripts/url_safety.py(validate_url_strict()plus the pinned safe request helpers). This blocks private IPs, loopback, metadata endpoints, redirect rebinding, and DNS rebinding. - OAuth tokens: Never store
client_secretin the token file. Read it from the client_secret.json file at runtime. - No hardcoded paths: Use
os.path.dirname(os.path.abspath(__file__))for relative paths, never a user-specific absolute path - Config location:
~/.config/seo-ops-studio/google-api.jsonand~/.config/seo-ops-studio/backlinks-api.json(user-space, not in repo)
Report Generation Rules
- All SEO reports must use
scripts/google_report.pyas the canonical report generator - Dependencies:
matplotlib>=3.8.0(charts) +weasyprint>=70.0(HTML-to-PDF), both inrequirements.txt - Format: A4 PDF via WeasyPrint + matplotlib charts at 200 DPI
- Style: Clean white title page with navy (#1e3a5f) accent, Times New Roman body font
- Color palette: Navy #1e3a5f (headers), dark gold #b8860b (accents), forest green #2d6a4f (pass), warm amber #d4740e (warnings), deep red #c53030 (fail), warm cream #faf9f7 (backgrounds)
- Structure: Title page → TOC with scores → Executive Summary → Data sections → Recommendations → Methodology
- Charts: 85% width, max-height 120mm, figure captions on every chart, saved to
charts/at 200 DPI - No
page-break-inside: avoidon any element (causes white gaps in WeasyPrint) - Post-generation review:
_review_pdf()runs automatically, checking for empty images, thin sections, duplicates - Before presenting any PDF to the user: verify the review passes (
"status": "PASS") - Cross-skill enforcement: After completing ANY analysis command (audit, page, technical, content, schema, geo, local, maps), offer: "Generate a PDF report? Use
/seo-ops-analyze google report" - Google logo appears on title page when using Google API data ("Powered by Google APIs")
Ecosystem
Part of the Claude Code skill family:
- Claude Banana -- standalone image gen (bundled as extension here)
- Claude Blog -- companion blog engine, consumes SEO findings
- AI Marketing Claude -- community marketing suite (copy, emails, ads, funnels, CRO)
Key Principles
- Progressive Disclosure: Metadata always loaded, instructions on activation, resources on demand
- Industry Detection: Auto-detect SaaS, e-commerce, local, publisher, agency
- Parallel Execution: Full audits spawn up to 17 subagents simultaneously
- Extension System: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, and Unlighthouse extensions
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

