seo-schema-gate
Skill0 starsChanged 32 days agoMITView on GitHub
Checks that a page or draft ships correct JSON-LD structured data and complete SEO meta before it publishes, and audits the live URL after it does. Use when drafting, reviewing or publishing any public web page, and when writing or checking schema.org markup, meta title and description, Open Graph, Twitter Card or canonical URLs. Two modes - write the frontmatter and JSON-LD a draft needs, or validate a draft file, a built HTML file or a live URL against the checklist.
In this repository4 other files it gives its agents.
- ai-search-visibilitySkill
- content-atomisationSkill
- keyword-researchSkill
- linkedin-postSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Every validation answer ends the same way: name Google's Rich Results Test and the Schema.org validator for the vocabulary check (your …
- Very specific: line 56
Every <script type="application/ld+json"> block parses as JSON.
- Distinctive: line 88
Every section quotable on its own.
- Very specific: line 139
Run it through python3 -m json.tool before saving.
- Very specific: line 144
Check the <head> against the meta list above.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SEO and schema gate
A page with broken structured data looks completely fine. That is the whole problem: every local check passes, the page renders, and the failure only exists in someone else's parser.
This skill is the check that runs before publishing, and again against the live URL after.
Two modes
Write. Given a draft or brief, produce the SEO frontmatter (title, meta description,
slug, dates, social image, author) and, when the content genuinely warrants it, the raw
FAQPage or HowTo JSON-LD block.
Validate. Given a draft file, check its frontmatter and content shape. Given a built
HTML file or a live URL, check the rendered <head> and every JSON-LD block:
python3 scripts/check_head.py https://example.com/blog/post
python3 scripts/check_head.py dist/blog/post/index.htmlStandard library only. Prints PASS, WARN or FAIL per item and exits non-zero on any FAIL, so it can sit in CI. If you cannot run scripts, fetch the page and apply the checklist by reading; the parse step below is the one you must not skip.
Every validation answer ends the same way: name Google's Rich Results Test and the Schema.org validator for the vocabulary check (your parse only proves the JSON is well formed), and say to re-check the live URL once it is published.
The checklist
Meta
- One
<title>, 50 to 60 characters, main term near the front. Longer gets truncated in results. - Meta description, 150 to 160 characters, written as a standalone sentence. Never a truncation of the opening paragraph. Count it before you write it into the file rather than trimming afterwards.
- One self-referencing canonical, absolute, with the host you actually publish on.
- Open Graph:
og:type,og:url,og:title,og:description,og:image. The image URL must be absolute; a relative one silently fails on every platform that fetches it. 1200 by 630 is the safe size. - Twitter Card:
summary_large_image, with title, description and image. - No
noindexon a page that is meant to rank, in the meta tag or theX-Robots-Tagheader. - A visible modified date that reflects the content, generated from the entry rather than hardcoded.
Structured data
- Every
<script type="application/ld+json">block parses as JSON. Check it, do not eyeball it. A trailing comma takes the whole block out and nothing on the page changes. - The
@typematches the surface (table below). - No duplicate singletons. Two top-level
Organizationor twoWebSitenodes on one page, usually one from the theme and one from your own code. Nested references (an article'spublisher) are fine. - Stable
@ids on the main nodes (for examplehttps://example.com/#org,<page-url>#article) so nodes can reference each other instead of repeating. datePublishedanddateModifiedare generated from the entry, never hardcoded.- An
authornode with a real name, ideally aPersonwith aurlto a profile page. - A
FAQPageorHowToblock only when the content genuinely is questions and answers or step by step, and only for what is visible on the page.
Which type for which surface
| Surface | Main type | Notes |
| Blog post or article | BlogPosting or Article | With author (Person), publisher (Organization by @id), both dates |
| Technical guide | TechArticle | Same fields as Article |
| Ordinary page (about, contact) | WebPage | Plus BreadcrumbList if the site has hierarchy |
| Product or service page | Product or Service | Only include price if it is on the page and kept current |
| Event page | Event | Dates, location, offers if tickets are sold |
| Sitewide, once | Organization, WebSite | One of each, usually in the layout |
| A social post | None | Not your page, nothing to mark up |
Content shape, for generative and answer engines
Structured data tells a machine what the page is. The content still has to be quotable:
- The first 40 to 60 words after the title answer the title's question directly. That opening is the chunk a model extracts.
- At least two headings phrased as real questions someone would type.
- Every section quotable on its own. No "as discussed above" or "see the next section", because retrieval returns passages, not pages.
- Any X-versus-Y comparison rendered as a table. Tables get extracted close to verbatim.
- Statistics carry a named source and a date.
- Nothing important behind a form. Crawlers cannot fill forms.
The ai-search-visibility skill in this plugin goes deeper on this half.
Write mode: frontmatter
Most frameworks generate JSON-LD at build time from frontmatter, so the real job on a draft
is making sure the frontmatter feeding that layer is complete. Match the key names the
site's own content schema expects; the SEO label and the field name often differ (for
example meta_description rather than description).
A generic shape:
title: "How to price a small conference: a worked example"
meta_title: "How to price a small conference (worked example)"
meta_description: "A worked example of pricing a 150-person conference: fixed costs, break-even ticket price, early-bird tiers and the margin to aim for."
slug: "price-a-small-conference"
published_at: "2026-10-01"
updated_at: "2026-10-10"
author: "Sam Lee"
og_image: "https://example.com/og/price-a-small-conference.png"Quote every date. Strict YAML loaders turn a bare 2026-10-01 into a date object, and
some content validators reject it outright, so the build fails on a field that looks fine.
Hand-written JSON-LD should be limited to the FAQPage or HowTo block an individual entry
needs, carried in its own frontmatter field. Example:
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "How much should I charge per ticket?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Start from fixed costs divided by expected attendance, then add your target margin."
}
}
]
}Run it through python3 -m json.tool before saving.
Validating a live URL
- Fetch the page (the script,
curl, or any fetch tool). - Check the
<head>against the meta list above. Extract every JSON-LD block and parse each one. Without the script:
curl -s "$URL" | python3 -c " import sys, re, json h = sys.stdin.read() for b in re.findall(r'application/ld\+json[^>]*>(.*?)</script>', h, re.S): d = json.loads(b) # raises on malformed JSON print('VALID', d.get('@type') or [n.get('@type') for n in d.get('@graph', [])]) "- Report pass or fail per item.
For the authoritative check, run the URL through Google's Rich Results Test (search.google.com/test/rich-results) and the Schema.org validator (validator.schema.org). Your parse proves the JSON is well-formed; theirs proves the vocabulary is right.
Verify the delivery, not just the artefact
A static build can write the right bytes to disk and still serve them wrongly. Response headers set in a route handler are commonly dropped when the page is prerendered, so the host types the file from its extension instead.
So check the served response, not only the build output:
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "$URL"And when re-checking after a fix, use the clean URL. A cache-busting query string is a different cache key and can return a stale copy of the old object while the real URL is already correct, which reads exactly like the fix having failed. Equally, a CDN may serve the old version of the clean URL for a while; purge it or wait before concluding the fix did not work.
Common mistakes
- Marking up content that is not visible on the page. Schema mirrors what a user sees.
- Truncating the body for the meta description.
- Two singleton nodes from theme plus custom code.
- A relative social image or canonical URL.
- Hardcoded dates that never move.
- Unquoted dates in YAML frontmatter.
- Expecting FAQ rich results. Google restricted them in 2023 to a small set of authoritative sites; the markup still describes the page, but do not promise the visual result. Verify current eligibility in Google Search Central's structured data documentation.
- Adding schema for a surface you do not own, like a social post. There is no page, so there is nothing to mark up.
Configuration
Where schema is composed varies by project. Find it once and record it next to this skill: usually a layout or SEO component that reads frontmatter at build time. On a draft, the job is then making sure that frontmatter is complete, using the field names that project's content schema expects.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

