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
- 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.
- Proof for every claim. Command, number, date, file. Mark what is MEASURED and what is SUPPOSED. A sample is not a count: give n.
- 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. - Paid APIs behind a cap.
budgets.dataforseo_usdandbudgets.perplexity_usdare enforced by the scripts before every call; every cost is logged. Report the total spent. - 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.
| Script | Track | What it does |
|---|---|---|
sitemap.py | code | whole sitemap tree, every URL typed and languaged, lastmod honesty, duplicates |
gsc.py performance | 16 months by month and page type, 28 days vs previous, queries, countries, sections | |
gsc.py sitemaps | submitted sitemaps, errors, pending, last read by Google | |
gsc.py echantillon / inspecter / analyser | stratified URL Inspection (2 000/day quota, resumable), coverage per type, movement since a previous run | |
ga4.py | channels over a year, Google organic then and now, AI assistants, robot-like share | |
pages.py | code | on-page reading of a sample: lang, canonical, hreflang, robots, words, JSON-LD, links to the blog, Googlebot vs browser |
logs.py | server | real Googlebot (DNS verified) per day, per type, waste, response times, first visit of followed URLs |
ttfb.py | server | time to first byte per type, warm, cold and origin |
dataforseo.py | outside | real SERPs, ranked keywords, backlinks of site and competitors, volumes, bilan |
perplexity.py | outside | dated, 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 sitemapsanswers, GA4 answers, the logs are readable (often only by root and theadmgroup: 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.
| Track | File | Key question |
|---|---|---|
| references/track-google.md | Does Google know the pages, crawl them, keep them? Is it getting better or worse? | |
| Server | references/track-server.md | Does the real Googlebot come, what does it read, is anything slowing or blocking it? |
| Code and content | references/track-code-content.md | What does Google find when it reads the site: how many pages, how thin, how linked, how honest? |
| Outside | references/track-outside.md | Who 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.