schema-writer

---
name: schema-writer
description: Writes and validates the JSON-LD that earns a rich result, and refuses to mark up what a visitor cannot see. Use before publishing, or when competitors show stars and prices and you do not.
---

# Get the stars, prices and answers showing in your search listing

Finished JSON-LD, checked against Google's own rules, ready to paste.

## Claude does

1. Asks four things: the page URL or its HTML; what the page IS in one sentence (shop, service, product, article, location); country and language; and for a business page its name, address and phone exactly as the Google Business Profile shows them.
2. Picks the most specific type that applies and writes it as JSON-LD, the format Google recommends, in one script block for the head, carrying every required property and as many recommended ones as are feasible. Plumber beats LocalBusiness; LocalBusiness beats Organization. Microdata is read, never written.
3. Marks up only what a visitor can see. Google: "Don't mark up content that is not visible to readers of the page." Every value is quoted from the visible text, or marked [NEEDS INPUT] and left out: prices, hours, ratings, stock, dates.
4. Copies name, address and phone character for character from that profile. Google requires the real-world name used on the storefront and stationery, on a phone reaching that location, not a call centre.
5. Writes AggregateRating or Review only from reviews already visible on the page; Google names fake and misleading reviews as a violation. Never adds FAQPage expecting stars, retired 7 May 2026, nor HowTo, SpecialAnnouncement or ClaimReview, all deprecated.
6. Ends with one line per page: the type written, the rich result it earns, and what is missing before Google can show it.

## Then Codex does

Codex sweeps the site: fetching every URL, extracting every JSON-LD, microdata and RDFa block, checking required properties, matching each marked-up value against the rendered visible text, and flagging retired types and pages Google cannot read. Bulk comparison, wrong by hand past a few pages.

```
codex exec --sandbox danger-full-access --skip-git-repo-check -C "<working folder>" - < CODEX.md
```

Claude fills these in first: {URL_LIST} (one per line), {SITE_DOMAIN}, {BUSINESS_NAP} (name, address, phone from the Business Profile, or NONE), {OUTPUT_FOLDER}.

## Claude checks

1. Row count equals URL count. A missing row is a failed fetch, not a page without schema.
2. Every "no structured data found" is re-checked on the rendered page. Sites inject schema at runtime, so absence in the source is a lead, not a finding.
3. Every value flagged invisible is read in context. That is the violation Google names first.
4. Any AggregateRating traces to reviews shown on the page; retired types go on the removal list, not the rewrite list.
5. Nothing carrying schema is blocked by robots.txt or noindex.

Reject rule: if a check fails, rerun Codex on the failing URLs only. Never write markup on an incomplete sweep.

## Rules

- Markup describes the page. If the page does not say it, the markup does not either.
- Never invent a rating, a price, a stock level or an opening hour.
- Do not claim a rich result a type no longer earns.
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.

## If Codex is not installed

Claude does the sweep itself, page by page, and says so.

## Built from

- Google Search Central, Structured Data General Guidelines: https://developers.google.com/search/docs/appearance/structured-data/sd-policies (the authority behind every rule above).
- Google Business Profile guidelines: https://support.google.com/business/answer/3038177 (the authority on name, address, phone).
- AgriciDaniel/claude-seo: https://github.com/AgriciDaniel/claude-seo (16,344 stars, api.github.com, 5 Sep 2026; the retirement dates).
- seranking/seo-skills: https://github.com/seranking/seo-skills (135 stars; the numbered workflow and evidence folder).

# Schema writer - Codex task

You are auditing structured data already on a website. You do not write markup and do not give advice.

## You are given

- {URL_LIST} - one URL per line. Fetch every one.
- {SITE_DOMAIN} - the site's own domain, used to separate internal from external references.
- {BUSINESS_NAP} - the business name, address and phone from the Google Business Profile, or NONE. Compare, never correct.
- {OUTPUT_FOLDER} - where the files below are written.

## Produce

1. `{OUTPUT_FOLDER}/schema.csv`, one row per structured data block found, with these columns in this order:
   `url, http_status, format, type, is_nested_in, required_props_present, required_props_missing, recommended_props_present, value_count, invisible_value_count, deprecated_type, blocked_from_googlebot, parse_error`
   - `format` - jsonld, microdata or rdfa.
   - `deprecated_type` - yes for FAQPage, HowTo, SpecialAnnouncement or ClaimReview, otherwise no.
   - `blocked_from_googlebot` - yes if the URL is disallowed in robots.txt or carries noindex.
   - A URL with no structured data still gets one row, with `format` empty.
2. `{OUTPUT_FOLDER}/invisible.csv` with columns `url, type, property, marked_up_value, found_in_visible_text` listing every string value in the markup, one row each, and whether that exact string appears in the rendered visible text of the same page.
3. `{OUTPUT_FOLDER}/nap.csv` with columns `url, schema_name, schema_street, schema_locality, schema_postal, schema_phone, matches_given_nap` comparing every LocalBusiness or Organization block against {BUSINESS_NAP}. Write `no_nap_given` in the last column when {BUSINESS_NAP} is NONE.
4. `{OUTPUT_FOLDER}/evidence/` holding the rendered HTML and the raw extracted JSON of each page, named after the URL slug, so every row can be re-checked.

## Rules

- Fetch each URL once, follow redirects, wait 1 second between requests.
- Capture the rendered page, not just the source. Where rendering is unavailable, write `render_unavailable` in `parse_error` rather than reporting an empty result as fact.
- Compare visible text after collapsing whitespace and normalising quotes. No fuzzy matching beyond that.
- Never repair, reformat or normalise the markup you find. Copy values exactly as served.
- Never skip a URL that 404s, times out or has invalid JSON: write the row with its status and error.
- Public information only: no logins, no paywalls, nothing behind authentication.
- Never invent a fact, a number or a quote. An unknown value is empty and the reason goes in `parse_error`.

## Return

Print, as plain text, in this order:

1. `URLS_GIVEN=<n>` and `URLS_ROWED=<n>`. These must match.
2. `BLOCKS_FOUND=<n>` and `URLS_WITH_NO_SCHEMA=<n>` followed by those URLs.
3. `INVISIBLE_VALUES=<n>` followed by one line each: url, type, property, value.
4. `DEPRECATED_TYPE_PAGES=<n>` followed by those URLs and their types.
5. `BLOCKED_FROM_GOOGLEBOT=<n>` followed by those URLs.
6. `NAP_MISMATCHES=<n>` followed by those URLs.
7. `PARSE_ERRORS=<n>` followed by each URL and its error.
8. The four output file paths.

Print nothing else. No summary, no recommendations.