SKILL.md
Schema Markup: Detect, Validate, Generate
Schema only counts if it is valid JSON-LD, uses a type search engines still reward, and states facts the page can back up. Everything else is noise or a penalty risk.
Workflow
- Detect. Fetch the page source. Find JSON-LD (
<script type="application/ld+json">), Microdata (itemscope/itemprop), and RDFa (typeof/property). Recommend JSON-LD as the target format, it is Google's stated preference. - Check type status. Read references/schema-status.md before recommending or flagging any type. Some types earn rich results, some help AI answer engines only, some are dead. Never recommend HowTo. Never pitch FAQPage for SERP benefit, flag existing FAQPage at Info severity, not Critical, because it still aids AI answer engines.
- Validate. For each block found, check:
@contextpresent and correct@typevalid and not deprecated- Required properties for the type present
- Absolute URLs, not relative
- ISO 8601 dates
- No placeholder or fabricated values
- Generate. Identify the page type from content, pick the matching schema type, fill required plus recommended properties. Templates live in references/schema-status.md. Only include claims the page visibly supports. Mark anything you cannot verify as
<FILL_ME>for the user. - Placement. Tell the user to ship JSON-LD in the initial server-rendered HTML. JS-injected structured data can face delayed processing, which matters most for Product and Offer markup.
- Report. Output a validation table (schema, type, status, issues) plus generated snippets and missing-schema opportunities.
Verification
Run the generated block through a parser: python3 -c "import json,sys; json.load(sys.stdin)" < generated-schema.json. Expect silent success. If it errors, fix the reported syntax issue (trailing comma, unquoted key, missing bracket) and re-run before presenting anything to the user.
Then confirm every URL value starts with https:// and every @type appears in the ACTIVE list in references/schema-status.md. If a type is not listed, verify it against schema.org before recommending.
Good vs Bad
Bad: Page has no reviews. You generate AggregateRating with "ratingValue": "4.8" as a placeholder. The user ships it. That is fabricated markup and a manual-action risk.
Good: Page has no reviews. You skip rating markup, note "add AggregateRating only after real reviews exist on-page", and generate Organization plus Article markup the page actually supports.
Error handling
| Scenario | Action |
|---|---|
| URL unreachable | Report status code. Suggest checking auth walls or DNS. |
| No markup found | Say so, then recommend types based on page content. |
| Invalid JSON-LD | Report the exact syntax error and provide corrected output. |
| Deprecated type found | Flag it, name the replacement, or advise removal if none exists. |
Footguns
- JS-injected JSON-LD. Markup added client-side can be processed late or inconsistently. Fix: move it into server-rendered HTML, especially Product and Offer.
- Relative URLs.
"url": "/about"fails validation silently in some tools. Fix: always absolute URLs. - Recommending retired types. HowTo and several others no longer earn rich results. Fix: check references/schema-status.md every time, do not rely on memory.
- Markup contradicting the page. Schema claiming data not visible on-page invites penalties. Fix: only encode what a human can see on the rendered page.
Completion checklist
- [ ] Every existing block validated with specific issues listed
- [ ] Generated JSON-LD parses clean and uses only active types
- [ ] No fabricated values, unknowns marked
<FILL_ME> - [ ] Placement guidance (server-rendered HTML) stated
- [ ] Validation table and recommendations delivered
Any box unchecked: not done. Fix or say so.