agentleFS
juanpulagjuanpulag/seo-ops-studio/CLAUDE.md

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

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
  1. Very specific:

    Every /seo-ops audit ends with a Markdown report and a PDF that lists the real data sources and what was not measured.

    line 28
  2. Very specific:

    Keep SKILL.md files under 500 lines / 5000 tokens

    line 222
  3. Distinctive:

    Follow kebab-case naming for all skill directories

    line 225
  4. Very specific:

    Test with python3 -m pytest tests/ after changes (if applicable)

    line 229
  5. Very specific:

    URL validation: All scripts that connect to user-supplied URLs must use scripts/url_safety.py (validate_url_strict() plus the pinned safe …

    line 234
  6. Very specific:

    OAuth tokens: Never store client_secret in the token file.

    line 235
  7. Very specific:

    No hardcoded paths: Use os.path.dirname(os.path.abspath(__file__)) for relative paths, never a user-specific absolute path

    line 236
  8. Very specific:

    Before presenting any PDF to the user: verify the review passes ("status": "PASS")

    line 250
  9. Very specific:

    Cross-skill enforcement: After completing ANY analysis command (audit, page, technical, content, schema, geo, local, maps), offer: …

    line 251

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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) and skills/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) and scripts/ops_pdf.py (HTML→PDF with real data sources, no WeasyPrint dependency). Both are in ALLOWED_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 audit ends 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, skill seo and /seo → seo-ops-analyze, every skill/agent seo-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 documentation

Commands

CommandUse 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 generateCreate 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 uses CLAUDE_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*.json are 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_secret in 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.json and ~/.config/seo-ops-studio/backlinks-api.json (user-space, not in repo)

Report Generation Rules

  • All SEO reports must use scripts/google_report.py as the canonical report generator
  • Dependencies: matplotlib>=3.8.0 (charts) + weasyprint>=70.0 (HTML-to-PDF), both in requirements.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: avoid on 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:

Key Principles

  1. Progressive Disclosure: Metadata always loaded, instructions on activation, resources on demand
  2. Industry Detection: Auto-detect SaaS, e-commerce, local, publisher, agency
  3. Parallel Execution: Full audits spawn up to 17 subagents simultaneously
  4. Extension System: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, and Unlighthouse extensions

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.