| name | moai-ref-seo |
| description | Search-visibility and crawlability reference for web output: canonical URL discipline, per-page title and meta description uniqueness, robots.txt and sitemap.xml as host-derived artifacts, JSON-LD structured data with entity consistency, and the document-semantics rules that decide whether a machine can read a page at all. Agent-extending skill that amplifies web-output implementation and pre-ship review with production-grade indexing and structured-data patterns. NOT for: keyboard operability, visible focus indicators, and form-control labeling (accessibility owns those; delegated to the accessibility surface); generative-engine optimization, deliberately excluded as insufficiently settled; visual polish and interface detail (see moai-ref-ui-polish); API contract design (see moai-ref-api-patterns); security headers and hardening (see moai-ref-owasp-checklist and moai-ref-secops).
|
| when_to_use | Use when a project emits pages that a search engine or an automated reader will fetch: choosing canonical addresses, writing per-page metadata, emitting robots.txt or sitemap.xml, adding or reviewing JSON-LD, keeping entity naming consistent between the page and its serialized data, or auditing heading structure, image alt text, anchor text, and in-page fragment targets before shipping. Guidance stays at the protocol and output layer — addresses, response headers, markup, serialized data — so it applies to any stack that produces HTML.
|
| user-invocable | false |
| metadata | {"version":"1.0.0","category":"domain","status":"active","updated":"2026-08-01","tags":"seo, canonical, structured-data, json-ld, sitemap, robots, metadata, crawlability, reference"} |
| progressive_disclosure | {"enabled":true,"level1_tokens":100,"level2_tokens":3000} |
Search Visibility Reference
Target Agents
manager-develop — applies these rules while implementing pages, routes, and serialized metadata output/moai review — pre-ship indexing review surface; equivalently available as a per-spawn Agent(general-purpose) with web-output review instructions
Core Principle
A page is indexed on what a machine can fetch and parse, not on what a person sees
once everything has finished loading. Two failures dominate everything below: the
same content reachable at more than one address, and a claim asserted in serialized
data that nothing on the page corroborates. Every rule here is a specialization of
one of those two.
Figures that engines publish and then quietly revise — truncation widths, ranking
weights, crawl allowances — are deliberately absent. Where a limit matters, this
reference gives the decision rule and the measurement to take, so the guidance
outlives the figure.
Document Semantics
The structure a parser reads before it reaches any content signal. Cheapest class of
defect to introduce, and the cheapest to detect.
| Rule | How to check it | Failure it prevents |
|---|
Exactly one h1 per document | Count h1 elements in the rendered output of each page | Competing topic signals leave the subject ambiguous |
| No skipped heading level | Walk the heading sequence; each descent moves by at most one level | Section nesting a parser cannot reconstruct |
Every image carries alt text | Each image element has a non-empty alt attribute, or an empty one paired with an explicit decorative marker | Meaning locked inside a binary the parser cannot open |
| Anchor text names its destination | Read each link's text with the surrounding sentence hidden, then ask where it goes | Instruction-shaped link text carries no signal about the target |
| Fragment targets resolve | For each in-page fragment link, confirm a matching identifier exists in the same rendered output | Navigation that silently lands nowhere |
Derive alt text from what the image depicts, never from its file name. Where an
image genuinely adds nothing a reader needs, mark it decorative on purpose instead
of inventing a description for it.
Identity and Canonical Address
