Communitygithub.com

heraut-seo

Deep, read-only SEO investigation of a website and its server that answers "why does Google not index or send visitors to this site, and what exactly do we do about it". Four tracks run in parallel (Google Search Console and GA4 with URL Inspection on a stratified sample; server logs with DNS-verified Googlebot, speed and blocking; code and content as Google reads it; outside view with paid DataForSEO SERPs, rankings and backlinks and Perplexity deep research), then a consulting-style synthesis (situation, complication, question, cause tree, phased plan, KPIs at 30, 60 and 90 days, owner decisions). Use when a site gets no organic traffic, when blog articles are not indexed, when an SEO program or content pipeline produces nothing measurable, before spending more on content, or to audit every site of a fleet the same way. French triggers (enquete SEO, pourquoi Google n'indexe pas mon site, pourquoi mes articles ne sont pas indexes, mon SEO ne marche pas, personne ne vient sur le site.

What is heraut-seo?

heraut-seo is a Claude Code agent skill that deep, read-only SEO investigation of a website and its server that answers "why does Google not index or send visitors to this site, and what exactly do we do about it". Four tracks run in parallel (Google Search Console and GA4 with URL Inspection on a stratified sample; server logs with DNS-verified Googlebot, speed and blocking; code and content as Google reads it; outside view with paid DataForSEO SERPs, rankings and backlinks and Perplexity deep research), then a consulting-style synthesis (situation, complication, question, cause tree, phased plan, KPIs at 30, 60 and 90 days, owner decisions). Use when a site gets no organic traffic, when blog articles are not indexed, when an SEO program or content pipeline produces nothing measurable, before spending more on content, or to audit every site of a fleet the same way. French triggers (enquete SEO, pourquoi Google n'indexe pas mon site, pourquoi mes articles ne sont pas indexes, mon SEO ne marche pas, personne ne vient sur le site.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/koffih/claude-skill-heraut-seo/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Heraut SEO

The heraut (herald) is the one who makes a domain known to the world. When nobody hears it, this skill investigates why, with proof for every claim, and returns a plan the owner can attack in order.

It came out of a real case: a site with 58 000 URLs and 1 000 generated articles, a content pilot spending money every day, zero blog impressions. The answer was not where the pilot looked (rewriting pages) but in site-wide quality, authority and demand. The method below is built to find that kind of answer instead of confirming the first hypothesis.

The rules

  1. Read only, everywhere. No production change, no database write, no restart, nothing submitted to Google (no indexing request, no sitemap added or removed). The investigation describes; the plan is applied later, one decided change at a time.
  2. Proof for every claim. Command, number, date, file. Mark what is MEASURED and what is SUPPOSED. A sample is not a count: give n.
  3. Be gentle with the site. One request at a time, a pause of 1.5 s at least (politesse.delai_s). Small servers fall under audits.
  4. Paid APIs behind a cap. budgets.dataforseo_usd and budgets.perplexity_usd are enforced by the scripts before every call; every cost is logged. Report the total spent.
  5. No secret in any output. Name where a key lives, never its value. Scripts read keys from the environment or from env files named in the config.

Where things are

Scripts in scripts/ (usually ~/.claude/skills/heraut-seo/scripts), Python standard library only, openssl for Google tokens. Every script takes --config <site.json> --dossier <investigation folder> and writes CSV and JSON there, plus a resume.json to read first.

ScriptTrackWhat it does
sitemap.pycodewhole sitemap tree, every URL typed and languaged, lastmod honesty, duplicates
gsc.py performancegoogle16 months by month and page type, 28 days vs previous, queries, countries, sections
gsc.py sitemapsgooglesubmitted sitemaps, errors, pending, last read by Google
gsc.py echantillon / inspecter / analysergooglestratified URL Inspection (2 000/day quota, resumable), coverage per type, movement since a previous run
ga4.pygooglechannels over a year, Google organic then and now, AI assistants, robot-like share
pages.pycodeon-page reading of a sample: lang, canonical, hreflang, robots, words, JSON-LD, links to the blog, Googlebot vs browser
logs.pyserverreal Googlebot (DNS verified) per day, per type, waste, response times, first visit of followed URLs
ttfb.pyservertime to first byte per type, warm, cold and origin
dataforseo.pyoutsidereal SERPs, ranked keywords, backlinks of site and competitors, volumes, bilan
perplexity.pyoutsidedated, sourced deep research (Agent API, effort)

The investigation, step by step

0. Frame (10 minutes, with the owner if needed)

  • Write the owner's question in their words, and the symptoms with numbers (impressions, clicks, articles published, money spent).
  • Find what is already known: earlier audits, notes, the content pipeline and its database. Treat it as hypotheses to check, not facts to copy.
  • Build the site file from config.example.json: domain, sitemap, languages, page types as path regexes (the most important part: every count is per type), sections to follow (the blog), Search Console property, GA4 id, service account key path, markets (DataForSEO location codes), 3 to 6 competitors, 15 to 30 real queries people would type, budgets.
  • Check access before starting: gsc.py sitemaps answers, GA4 answers, the logs are readable (often only by root and the adm group: ask the owner, never work around a refusal).

1. Four tracks in parallel

Create the folder enquete-YYYY-MM-DD/ next to the site's other audit files, write BRIEF.md there from references/brief.md, then launch four investigators (subagents) at once, each with the brief and its track file. Each writes volet-<track>.md with a 10-line summary on top, and its raw data alongside.

TrackFileKey question
Googlereferences/track-google.mdDoes Google know the pages, crawl them, keep them? Is it getting better or worse?
Serverreferences/track-server.mdDoes the real Googlebot come, what does it read, is anything slowing or blocking it?
Code and contentreferences/track-code-content.mdWhat does Google find when it reads the site: how many pages, how thin, how linked, how honest?
Outsidereferences/track-outside.mdWho wins the real searches, with what authority, and is there demand for what the site writes?

Run sitemap.py first (the others sample from it), then the tracks. gsc.py inspecter can take hours on a full sample: run it in the background.

2. Synthesis

Read the four reports, then build the answer with references/cause-tree.md: it lists the causes seen in practice, the measure that confirms or rules out each one, and the traps (a technical audit that comes back clean does not mean the site is fine).

Write the report following references/report.md: short answer first, situation, complication, question, cause tree with the evidence on each branch, why the current program does not work, the plan in phases with a "done when" for each step, KPIs at 30, 60, 90 days, decisions for the owner, limits of the investigation, sources. Publish it as a page when the session can (private by default), otherwise as an HTML file.

3. Hand over

  • Give the owner the link, the core diagnosis in five lines, the cost of the investigation, what could not be measured.
  • Then the decisions, one at a time, each with the fact behind it and a recommendation. Apply each decided step before asking the next.
  • Save the verdict and the operating rule it implies (for example "no new content until the core pages are indexed") where the project keeps its memory.

Running it on another server or site

Install the skill on the machine that has the access (Search Console key, logs), copy config.example.json to the site's folder, fill it, run step 0 to 3. Keep one folder per investigation date so the next run can compare: gsc.py analyser --avant <old inspection.jsonl> shows URL by URL what entered or left the index.

Re-run the investigation 60 to 90 days after the plan starts. Between runs, a daily rotating inspection of 50 to 100 URLs is the cheapest way to see the index move.

What this skill does not do

It does not change the site, write content, request indexing, or buy links. It does not judge the product or the business model, only whether search can bring people to it. Scores from SEO tools (rank, spam score, estimated traffic) are models, not measures: say so when quoting them.

Related Skills