docs-seo

Audits documentation sites for indexability, canonicals, hreflang, and page signals, then produces an owner-assigned fix list.

2|Updated Sep 6, 2026
One-click install
npx skills add https://github.com/samber/developer-relations-skills --skill docs-seo-samber
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: docs-seo
Source: https://github.com/samber/developer-relations-skills/tree/main/skills/docs-seo
Command: npx skills add https://github.com/samber/developer-relations-skills --skill docs-seo-samber

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Documentation sites fail SEO in ways a general audit never catches: versioned and translated pages competing with each other, generator-controlled titles and canonicals, preview branches leaking into the index, and thousands of thin auto-generated reference pages. This Skill diagnoses those docs-specific failure modes and produces a prioritized, owner-assigned fix list with agreed pass thresholds. ## Core Features & Use Cases - Indexability and crawl audit: Crawls the sitemap with a bundled Python script, flags blocking defects like robots.txt-plus-noindex combinations, non-200 sitemap URLs, and leaked preview hosts. - Version and translation posture: Settles the canonical strategy across versioned docs (stable-canonical, latest-only, per-version indexable) and validates complete bidirectional hreflang sets per locale. - Template-level page signals: Fixes title templates, descriptions, headings, internal linking, and structured data at the generator config level rather than page by page. - Use Case: Your old v1 docs outrank the current release in Google. The Skill crawls the site, identifies conflicting canonical signals, recommends a version posture, and delivers a ranked fix list with named owners and measurable thresholds. ## Quick Start Ask the assistant to audit your documentation site for SEO, providing the docs URL, the generator and hosting platform, and whether the docs are versioned or translated.

Frequently Asked Questions about docs-seo

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix old documentation versions outranking the current release in Google?

Choose a version canonical posture: canonicalize every version to a stable alias, noindex archived versions, or keep each version self-canonical. Then align the sitemap, canonical tags, and internal links to the same target so Google stops picking its own canonical.

Why are my noindexed docs pages still showing in search results?

A URL disallowed in robots.txt is never crawled, so its noindex directive is never read and the URL stays indexed as a bare link. Remove the Disallow so the noindex can be read, or redirect the URLs instead.

How should hreflang be set up for translated documentation?

Each locale needs a self-referencing canonical plus a complete bidirectional hreflang set including x-default, using ISO 639-1 language codes with optional ISO 3166-1 regions. Regenerate the whole mesh across every locale whenever a language is added or removed.

Should I noindex auto-generated API reference pages to avoid thin content penalties?

No. Generated reference pages are thin but the highest-intent pages on the domain. Instead consolidate to one page per resource rather than per field, use a language switcher instead of per-SDK URLs, and keep stable anchor IDs per symbol.

Does the docs SEO crawl script require any Python packages?

No. The crawl script uses only the Python standard library and runs anywhere Python 3.9 or newer is available. It reads a sitemap or URL list and outputs CSV or JSON with titles, canonicals, robots directives, and link counts.

Is HowTo or FAQPage structured data still worth adding to docs?

No. Google removed the HowTo rich result in August 2023 and FAQPage stopped appearing entirely by May 2026. BreadcrumbList still renders and is worth adding because docs have a real hierarchy to express.