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
One resource, one address; everything else redirects to it.
| Decision |
Rule |
| Which address is canonical |
Pick one form per resource and declare it. The declared value must equal the address actually served |
| Trailing-slash variants |
Choose one form and redirect the other permanently. Serving both splits one resource across two addresses |
| Case, query parameters, tracking suffixes |
Normalize before serving. A parameter that does not change the response must not mint a second address |
| Parameterized routes |
Build the declared value from the resolved parameters, never from a fixed string shared across the whole route |
| Retiring an address |
Redirect permanently from the old form and update the declaration in the same change |
A declaration pointing at an address that redirects, errors, or serves different
content is worse than no declaration at all: it actively steers the reader away from
the page it appears on.
Per-Page Metadata
| Field |
Rule |
Recurring defect |
title |
Unique per page, composed from a page-specific part plus a stable identifier for the site |
The scaffold's default survives to production on every route |
| meta description |
Unique per page, written for a person reading a result snippet |
One description copied everywhere, or prose that describes nothing |
| Indexing directive |
Set a default for public pages, then narrow per page class. Authenticated areas and internal tools are excluded deliberately, not merely left unlinked |
A private surface gets indexed because nothing declared otherwise |
| Social preview fields |
Present and absolute. A relative address in a field a third party fetches resolves against the wrong host |
A share card that renders blank off-site |
Length budgets are a decision rule, not a constant: draft the text, observe where the
consuming surface truncates it, then cut to what you observed. Placeholder detection
belongs in the pre-ship check — scan the emitted output for the scaffold's own
default strings and fail when one survives.
Structured Data
Serialized JSON-LD states what a page is. Its one hard constraint is correspondence
with the visible page.
| Decision |
Rule |
| Which types to emit |
Derive them from the page's actual role — an organization, a product, a piece of software, a place, an article. Emit the site-level type everywhere and the page-specific type only where it applies |
| Required fields |
Each type has a small mandatory core. Emit that core completely rather than emitting several types partially |
| Addresses inside the data |
Absolute, and resolving. Relative values are discarded without a warning |
| Several entities on one page |
Emit one block holding all of them, give each a stable identifier, and cross-reference by identifier instead of nesting duplicate copies |
| Placement |
Keep each type on the page it describes. A type repeated site-wide dilutes rather than reinforces |
Mirroring rule — every claim in the serialized data needs a visible counterpart on
the same page. A name, a description, a rating, or a question-and-answer pair that
exists only in the markup is an assertion the reader cannot check, and it is now
scored as a negative signal rather than a neutral one.
Entity Consistency
Structured data identifies an entity. Consistency is what makes that identity hold
across independent sources.
| Surface |
Requirement |
| Canonical name |
One spelling, one casing, one suffix — the same in the serialized data, the page copy, and the headings |
| Owned profile links |
Restricted to accounts this entity itself administers, each confirmed to resolve rather than bounce to a sign-in wall |
| Contact details |
Name, address, and contact number identical across the serialized data, the visible page, and any third-party listings |
| Omission over approximation |
A field with no accurate value is left out. A partial or invented one fragments the identity it was meant to establish |
Formatting differences that read as trivial to a person are distinct values to a
matcher. Fix one format per field and hold it everywhere the entity appears.
Host-Derived Crawl Artifacts
robots.txt and sitemap.xml are output the site serves, not files carried between
environments.
| Artifact |
Rule |
robots.txt |
Derive the absolute addresses it contains from the incoming request's host, so every environment serves a correct description of itself |
sitemap.xml |
Enumerate the addresses actually served. An entry for a removed page spends crawl attempts and signals staleness |
| Staying in sync |
Adding or removing a route updates the enumeration in the same change. A hand-maintained list drifts within one iteration |
| Per-entry hints |
Freshness and weighting hints attached to entries are advisory and widely discounted. Correctness of the address set matters far more than the hints on it |
Hardcoding one environment's host into either artifact is the defect that keeps
recurring, because it passes review while being correct in exactly one place.
Delivery Chokepoints
| Concern |
Rule |
| Response headers |
Apply them at a single wrapping point every response passes through, error and redirect responses included. A header set only on the success path is missing exactly when a reader is most likely to be misled |
| Rendering mode |
Treat "what does a reader receive in the first response?" as a question the project answers explicitly. Content that appears only after client-side work is content a non-executing reader may never see |
| Redirect chains |
One hop to the canonical address. Each extra hop is another opportunity to lose the reader |
| Third-party origins |
Connection hints for origins the page depends on belong ahead of the resources that use them. Measure the effect on this project's own pages rather than assuming one |
Common Rationalizations
| Rationalization |
Reality |
| "The framework already sets sensible metadata defaults" |
A default is identical on every route by construction. Uniqueness is the entire purpose of the field, so it cannot be inherited. |
| "Both address forms serve the same page, so it makes no difference" |
Two addresses serving one resource are two resources to a crawler. Which one survives is guessed unless a declaration and a redirect settle it deliberately. |
| "Serialized data may say more than the page shows — it is extra context" |
Data with no visible counterpart is an unverifiable claim, and it is scored as one. |
"Heading structure and alt text belong to accessibility, not to indexing" |
They are the parse structure a machine uses to segment and describe a page. Sharing a mechanism with accessibility is not a reason to defer them. |
| "The address enumeration can be updated in a follow-up change" |
A list maintained apart from the routes drifts immediately and then silently. Deriving it from the routes is the only version that stays true. |
| "The staging host in the artifact is fine, we swap it at deploy" |
A hardcoded host is right in one environment and wrong in every other, including the one that gets indexed. |
Red Flags
- Two or more
h1 elements on one page, or a heading sequence that skips a level
- A canonical declaration that does not match the address actually serving the page
- The same
title or meta description reused across more than one route
- An image with no
alt attribute, or alt text that repeats the file name
- Link text that reads as an instruction instead of naming a destination
- An in-page fragment link with no matching identifier in the rendered output
robots.txt or sitemap.xml carrying a hardcoded host instead of one derived from the request
- Serialized JSON-LD asserting a name, description, or offer with no visible counterpart
- A relative address in a field a third party fetches — a share-preview image, a structured-data logo
- Response headers applied on the success path only, leaving redirect and error responses uncovered
Verification
1---
2name: moai-ref-seo
3description: >
4 Search-visibility and crawlability reference for web output: canonical URL
5 discipline, per-page title and meta description uniqueness, robots.txt and
6 sitemap.xml as host-derived artifacts, JSON-LD structured data with entity
7 consistency, and the document-semantics rules that decide whether a machine can
8 read a page at all. Agent-extending skill that amplifies web-output implementation
9 and pre-ship review with production-grade indexing and structured-data patterns.
10 NOT for: keyboard operability, visible focus indicators, and form-control labeling
11 (accessibility owns those; delegated to the accessibility surface); generative-engine
12 optimization, deliberately excluded as insufficiently settled; visual polish and
13 interface detail (see moai-ref-ui-polish); API contract design (see
14 moai-ref-api-patterns); security headers and hardening (see moai-ref-owasp-checklist
15 and moai-ref-secops).
16
17when_to_use: >
18 Use when a project emits pages that a search engine or an automated reader will
19 fetch: choosing canonical addresses, writing per-page metadata, emitting robots.txt
20 or sitemap.xml, adding or reviewing JSON-LD, keeping entity naming consistent
21 between the page and its serialized data, or auditing heading structure, image alt
22 text, anchor text, and in-page fragment targets before shipping. Guidance stays at
23 the protocol and output layer — addresses, response headers, markup, serialized
24 data — so it applies to any stack that produces HTML.
25
26user-invocable: false
27metadata:
28 source: https://skillmd.com/skills/modu-ai/moai-ref-seo
29 version: "1.0.0"
30 category: "domain"
31 status: "active"
32 updated: "2026-08-01"
33 tags: "seo, canonical, structured-data, json-ld, sitemap, robots, metadata, crawlability, reference"
34
35# MoAI Extension: Progressive Disclosure
36progressive_disclosure:
37 enabled: true
38 level1_tokens: 100
39 level2_tokens: 3000
40---
41
42# Search Visibility Reference
43
44## Target Agents
45
46- `manager-develop` — applies these rules while implementing pages, routes, and serialized metadata output
47- `/moai review` — pre-ship indexing review surface; equivalently available as a per-spawn `Agent(general-purpose)` with web-output review instructions
48
49## Core Principle
50
51A page is indexed on what a machine can fetch and parse, not on what a person sees
52once everything has finished loading. Two failures dominate everything below: the
53same content reachable at more than one address, and a claim asserted in serialized
54data that nothing on the page corroborates. Every rule here is a specialization of
55one of those two.
56
57Figures that engines publish and then quietly revise — truncation widths, ranking
58weights, crawl allowances — are deliberately absent. Where a limit matters, this
59reference gives the decision rule and the measurement to take, so the guidance
60outlives the figure.
61
62## Document Semantics
63
64The structure a parser reads before it reaches any content signal. Cheapest class of
65defect to introduce, and the cheapest to detect.
66
67| Rule | How to check it | Failure it prevents |
68|---|---|---|
69| Exactly one `h1` per document | Count `h1` elements in the rendered output of each page | Competing topic signals leave the subject ambiguous |
70| No skipped heading level | Walk the heading sequence; each descent moves by at most one level | Section nesting a parser cannot reconstruct |
71| 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 |
72| 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 |
73| Fragment targets resolve | For each in-page fragment link, confirm a matching identifier exists in the same rendered output | Navigation that silently lands nowhere |
74
75Derive `alt` text from what the image depicts, never from its file name. Where an
76image genuinely adds nothing a reader needs, mark it decorative on purpose instead
77of inventing a description for it.
78
79## Identity and Canonical Address
80
81One resource, one address; everything else redirects to it.
82
83| Decision | Rule |
84|---|---|
85| Which address is canonical | Pick one form per resource and declare it. The declared value must equal the address actually served |
86| Trailing-slash variants | Choose one form and redirect the other permanently. Serving both splits one resource across two addresses |
87| Case, query parameters, tracking suffixes | Normalize before serving. A parameter that does not change the response must not mint a second address |
88| Parameterized routes | Build the declared value from the resolved parameters, never from a fixed string shared across the whole route |
89| Retiring an address | Redirect permanently from the old form and update the declaration in the same change |
90
91A declaration pointing at an address that redirects, errors, or serves different
92content is worse than no declaration at all: it actively steers the reader away from
93the page it appears on.
94
95## Per-Page Metadata
96
97| Field | Rule | Recurring defect |
98|---|---|---|
99| `title` | Unique per page, composed from a page-specific part plus a stable identifier for the site | The scaffold's default survives to production on every route |
100| meta description | Unique per page, written for a person reading a result snippet | One description copied everywhere, or prose that describes nothing |
101| Indexing directive | Set a default for public pages, then narrow per page class. Authenticated areas and internal tools are excluded deliberately, not merely left unlinked | A private surface gets indexed because nothing declared otherwise |
102| Social preview fields | Present and absolute. A relative address in a field a third party fetches resolves against the wrong host | A share card that renders blank off-site |
103
104Length budgets are a decision rule, not a constant: draft the text, observe where the
105consuming surface truncates it, then cut to what you observed. Placeholder detection
106belongs in the pre-ship check — scan the emitted output for the scaffold's own
107default strings and fail when one survives.
108
109## Structured Data
110
111Serialized JSON-LD states what a page *is*. Its one hard constraint is correspondence
112with the visible page.
113
114| Decision | Rule |
115|---|---|
116| Which types to emit | Derive them from the page's actual role — an organization, a product, a piece of software, a place, an article. Emit the site-level type everywhere and the page-specific type only where it applies |
117| Required fields | Each type has a small mandatory core. Emit that core completely rather than emitting several types partially |
118| Addresses inside the data | Absolute, and resolving. Relative values are discarded without a warning |
119| Several entities on one page | Emit one block holding all of them, give each a stable identifier, and cross-reference by identifier instead of nesting duplicate copies |
120| Placement | Keep each type on the page it describes. A type repeated site-wide dilutes rather than reinforces |
121
122**Mirroring rule** — every claim in the serialized data needs a visible counterpart on
123the same page. A name, a description, a rating, or a question-and-answer pair that
124exists only in the markup is an assertion the reader cannot check, and it is now
125scored as a negative signal rather than a neutral one.
126
127## Entity Consistency
128
129Structured data identifies an entity. Consistency is what makes that identity hold
130across independent sources.
131
132| Surface | Requirement |
133|---|---|
134| Canonical name | One spelling, one casing, one suffix — the same in the serialized data, the page copy, and the headings |
135| Owned profile links | Restricted to accounts this entity itself administers, each confirmed to resolve rather than bounce to a sign-in wall |
136| Contact details | Name, address, and contact number identical across the serialized data, the visible page, and any third-party listings |
137| Omission over approximation | A field with no accurate value is left out. A partial or invented one fragments the identity it was meant to establish |
138
139Formatting differences that read as trivial to a person are distinct values to a
140matcher. Fix one format per field and hold it everywhere the entity appears.
141
142## Host-Derived Crawl Artifacts
143
144`robots.txt` and `sitemap.xml` are output the site serves, not files carried between
145environments.
146
147| Artifact | Rule |
148|---|---|
149| `robots.txt` | Derive the absolute addresses it contains from the incoming request's host, so every environment serves a correct description of itself |
150| `sitemap.xml` | Enumerate the addresses actually served. An entry for a removed page spends crawl attempts and signals staleness |
151| Staying in sync | Adding or removing a route updates the enumeration in the same change. A hand-maintained list drifts within one iteration |
152| Per-entry hints | Freshness and weighting hints attached to entries are advisory and widely discounted. Correctness of the address set matters far more than the hints on it |
153
154Hardcoding one environment's host into either artifact is the defect that keeps
155recurring, because it passes review while being correct in exactly one place.
156
157## Delivery Chokepoints
158
159| Concern | Rule |
160|---|---|
161| Response headers | Apply them at a single wrapping point every response passes through, error and redirect responses included. A header set only on the success path is missing exactly when a reader is most likely to be misled |
162| Rendering mode | Treat "what does a reader receive in the first response?" as a question the project answers explicitly. Content that appears only after client-side work is content a non-executing reader may never see |
163| Redirect chains | One hop to the canonical address. Each extra hop is another opportunity to lose the reader |
164| Third-party origins | Connection hints for origins the page depends on belong ahead of the resources that use them. Measure the effect on this project's own pages rather than assuming one |
165
166<!-- moai:evolvable-start id="rationalizations" -->
167## Common Rationalizations
168
169| Rationalization | Reality |
170|---|---|
171| "The framework already sets sensible metadata defaults" | A default is identical on every route by construction. Uniqueness is the entire purpose of the field, so it cannot be inherited. |
172| "Both address forms serve the same page, so it makes no difference" | Two addresses serving one resource are two resources to a crawler. Which one survives is guessed unless a declaration and a redirect settle it deliberately. |
173| "Serialized data may say more than the page shows — it is extra context" | Data with no visible counterpart is an unverifiable claim, and it is scored as one. |
174| "Heading structure and `alt` text belong to accessibility, not to indexing" | They are the parse structure a machine uses to segment and describe a page. Sharing a mechanism with accessibility is not a reason to defer them. |
175| "The address enumeration can be updated in a follow-up change" | A list maintained apart from the routes drifts immediately and then silently. Deriving it from the routes is the only version that stays true. |
176| "The staging host in the artifact is fine, we swap it at deploy" | A hardcoded host is right in one environment and wrong in every other, including the one that gets indexed. |
177
178<!-- moai:evolvable-end -->
179
180<!-- moai:evolvable-start id="red-flags" -->
181## Red Flags
182
183- Two or more `h1` elements on one page, or a heading sequence that skips a level
184- A canonical declaration that does not match the address actually serving the page
185- The same `title` or meta description reused across more than one route
186- An image with no `alt` attribute, or `alt` text that repeats the file name
187- Link text that reads as an instruction instead of naming a destination
188- An in-page fragment link with no matching identifier in the rendered output
189- `robots.txt` or `sitemap.xml` carrying a hardcoded host instead of one derived from the request
190- Serialized JSON-LD asserting a name, description, or offer with no visible counterpart
191- A relative address in a field a third party fetches — a share-preview image, a structured-data logo
192- Response headers applied on the success path only, leaving redirect and error responses uncovered
193
194<!-- moai:evolvable-end -->
195
196<!-- moai:evolvable-start id="verification" -->
197## Verification
198
199- [ ] Every rendered page has exactly one `h1` and a heading sequence with no skipped level — report the counts observed, not the intent
200- [ ] Each route's canonical declaration was fetched and returned that same page with no redirect in between
201- [ ] `title` and meta description were collected across all routes; no duplicates and no scaffold default strings remain
202- [ ] Every image element has an `alt` attribute, and decorative images are marked as such on purpose
203- [ ] Every in-page fragment link was resolved against the rendered output of the page carrying it
204- [ ] `robots.txt` and `sitemap.xml` were fetched from the deployed host and every address in them resolves — quote the address set observed
205- [ ] Serialized JSON-LD parses, its addresses are absolute, and each claim it makes has a visible counterpart quoted from the page
206- [ ] Response headers were observed on a success response, on a redirect response, and on an error response
207
208<!-- moai:evolvable-end -->