docs-seo skill (samber): fix indexing and canonicals on a docs site

Audits a documentation site for SEO: indexing, canonicals across versions and translations, templates and internal links.

Installs: 12.4K; on skills.sh
Stars: 7; on GitHub
Files: 5; besides SKILL.md
Updated: Nov 2026; last repo commit

docs-seo fixes what a documentation site publishes: what search engines can crawl, which URL wins among duplicates, what each title and snippet says and how pages link to each other. It builds a crawl set from the sitemap, clears blocking defects first, settles a version and translation posture (stable-canonical, latest-only or per-version indexable), fixes page signals at the template level and ends with an owner-assigned fix list against agreed thresholds.

It triggers on "docs SEO", "our docs don't rank", "the old version of our docs outranks the current one" or "preview docs got indexed". It bundles scripts/docs-seo-crawl.py, which fetches a sitemap and each page. SKILL.md says not to use it for keyword research or for docs content, and that nearly every fix is a template or configuration change.

Good for

Docs teams whose old version outranks the current one
Platform engineers whose preview or staging docs got indexed
Maintainers with translated or auto-generated reference docs

Install docs-seo

Claude Code

Copy this prompt.

Install the docs-seo skill in Claude Code. Run this command:

/plugin marketplace add samber/developer-relations-skills
/plugin install developer-relations-skills@developer-relations-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

The README recommends installing the whole collection because its skills reference each other, and docs-seo names other skills in the collection to hand work to. The whole-collection routes add all 93 skills in the repo (counted from the git tree); the repo holds no hooks, agents, commands or MCP server files, and 14 of its skills bundle a script. This skill runs scripts/docs-seo-crawl.py, which needs Python 3.9+. Pick one route per agent.

From the project README. Source.

What's in the skill

When it loads

Runs on-page and technical SEO for a documentation site - indexability, canonicals and hreflang across versioned and translated pages, redirects, the generator's title and description templates, internal linking, and an owner-assigned fix list against an agreed pass threshold. Use whenever someone says "docs SEO", "our docs don't rank", "documentation search optimization", "the old version of our docs outranks the current one", "our docs pages aren't indexed", "fix the canonicals on our docs", "docs sitemap problems", "hreflang on our translated docs" or "preview docs got indexed" - even if they never say SEO. Covers versioned, translated and auto-generated reference docs. Not keyword research - use samber/developer-relations-skills@developer-keyword-research.

Sections in SKILL.md

Interview
Step 1 - Build the crawl set
Step 2 - Clear the blocking defects first
Step 3 - Settle the version and translation posture
Step 4 - Fix page signals at the template level
Step 5 - Repair internal linking
Step 6 - Page experience
Step 7 - Ship the fix list and set the threshold
Audience note
Failure modes
References

Key facts

Author: Samuel Berthe (named in SKILL.md metadata, LICENSE and the plugin manifest)
License: MIT (LICENSE file, SKILL.md frontmatter, plugin.json and marketplace.json agree)
Skill version: 1.0.5 (SKILL.md metadata)
Installs on skills.sh: 12,409 (Nov 2, 2026)
GitHub stars: 8 for the whole samber/developer-relations-skills repo (Nov 2, 2026)
Last repo commit: Nov 1, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: warn
What it includes: 6 files in the git tree: SKILL.md, evals/evals.json, 3 files under references/ and scripts/docs-seo-crawl.py.
Needs: Python 3.9+, standard library only (per the script header)
Part of: The developer-relations-skills plugin: 93 skill folders in the git tree
Works in: The README documents installs for Claude Code, Claude.ai, Codex, Cursor and Gemini CLI, all for the whole set

What it includes

Asks 13 questions; questions 1 to 4 gate the work and 11 to 13 re-rank the posture.
Interview
Runs docs-seo-crawl.py on the sitemap, then checks robots.txt and a no-JavaScript page.
Runs docs-seo-crawl.py on the sitemap or a URL list, then checks robots.txt, the sitemap and a page without JavaScript.
Runs code · Step 1: Build the crawl set
Checks robots.txt, bad sitemap URLs, stray noindex and preview hosts, in order.
Checks robots.txt, non-200 sitemap URLs, stray noindex, preview hosts, JavaScript-only content and crawler rules, in order.
Step 2: Clear blocking defects
Compares stable-canonical, latest-only and per-version indexable, and checks hreflang.
Step 3: Version and translation posture
Fixes title and description templates, headings and anchors in the generator config.
Fixes title and description templates, heading structure and stable anchors in the generator config.
Step 4: Page signals
Repairs orphans and dead ends and adds contextual links.
Step 5: Internal linking
Checks Core Web Vitals for the docs path on three page types.
Step 6: Page experience
Delivers an owner-assigned fix list and agrees seven numeric thresholds.
Delivers an owner-assigned fix list and agrees seven numeric thresholds before the fix pass.
Step 7: Fix list and thresholds
Fetches a sitemap or URL list and writes per-page search signals to CSV or JSON.
Fetches a sitemap or URL list and writes title, description, canonical, robots directives, h1, word count and link counts per page to CSV or JSON.
Runs code · scripts/docs-seo-crawl.py

From the official docs

Permissions

Medium risk

docs-seo is audit instructions plus one Python script that fetches the sitemap and every page you point it at. Our advice: crawl your own site, keep the default delay and start with --limit.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

The crawler sends many requests to a site
scripts/docs-seo-crawl.py fetches every URL it is given with 4 workers and a 0.2 second default delay, and reads up to 3,000,000 bytes per page. Use --limit for a first pass and raise --delay on a site you do not own, as SKILL.md says. github.com
Canonical and robots changes affect indexing
SKILL.md says to ask you to confirm the version posture before writing canonical rules, and it flags a robots.txt disallow combined with noindex as self-defeating. Review each rule before deploying. github.com
It may save notes to devrel-context.md
SKILL.md tells Claude to keep task and project context in devrel-context.md when memory lives in a file, or in the memory system your tool already uses. Check the file before you commit it. github.com
The whole-set install adds 93 skills, 14 with scripts
The README says to install every skill. The git tree has 93 skill folders, and 14 of them hold .py or .sh files. This skill bundles scripts/docs-seo-crawl.py. The tree holds no hooks, agents or MCP config files. github.com

Technical details

Turning on read-only	SKILL.md describes no read-only mode.
Talks to	The sitemap URL and page URLs you pass to docs-seo-crawl.py (any host you choose)
Sign-in and keys	SKILL.md and the bundled script name no account, key or token.
Scopes	Claude writes an audit report and fix list in the conversation docs-seo-crawl.py sends HTTP requests to the sitemap and pages you give it docs-seo-crawl.py writes a CSV or JSON file when you pass --out Writes devrel-context.md when memory lives in a file

Questions

What does docs-seo do?

It audits and fixes the search signals of a documentation site. It finds pages that cannot be crawled or indexed, picks which version of a page should win in search and rewrites title and description templates.

How do I install it?

Use the install box at the top. The README says to install every skill in the repo, because the skills point to each other. The box shows the whole-set route for each app. There is no Claude app route listed, because the crawl step needs a local shell and Python.

What does the crawl script do to my site?

docs-seo-crawl.py requests the sitemap and every page in it with the user agent "docs-seo-crawl/1.0 (+documentation SEO audit)", using 4 workers and a 0.2 second delay by default. SKILL.md says to keep the delay at or above the default on a site you do not own and to use --limit for a first pass.

Does it need Search Console or an API key?

The crawl command takes a sitemap URL or a URL file and no key, and the script header says it uses only the Python standard library. The interview asks whether you can reach Search Console, and SKILL.md says to use its field data when lab data is missing.

Is it safe to install?

The crawl script makes HTTP requests to the sitemap and pages you give it, and writes results to a file you name with --out. SKILL.md also says nearly every fix is a config change, so review canonical rules before you ship them. The whole-set install adds 93 skills, 14 of which bundle scripts.

How is it different from developer-keyword-research?

This skill fixes what the site publishes. SKILL.md routes the question of which queries to target to samber/developer-relations-skills@developer-keyword-research.

Information

updated Nov 2, 2026

Repository: samber/developer-relations-skills
Folder: skills/docs-seo

samber/developer-relations-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

README · github.com
docs-seo SKILL.md · github.com
docs-seo scripts/docs-seo-crawl.py · github.com
LICENSE · github.com