Schema Markup Generator
Write JSON-LD structured data (Article or TechArticle, FAQPage, HowTo, SoftwareApplication, Product, BreadcrumbList, Organization) from the content that is actually visible on a page, fill the required and recommended properties from Google's structured-data documentation, link the nodes in one @graph, and validate the result with the Schema.org validator and the Rich Results Test before it ships. Use when a page needs structured data written, or an existing block checked property by property.
This skill reads a page, picks the Schema.org type from what the page is, fills required and recommended properties only from content a visitor can see, links the nodes in one @graph, validates with the Schema.org validator and Google's Rich Results Test, and returns the block with its insertion point. It audits an existing block the same way.
Install to ~/.claude/skills/schema-markup-generator/SKILL.md
npx agentscamp add skills/schema-markup-generatorStructured data has one rule that most generators break: every value in the JSON-LD must correspond to something a visitor can see on the page. A FAQPage whose questions appear nowhere in the HTML, a datePublished the byline does not show, an aggregateRating with no visible reviews: these are the patterns Google's spam policies describe as structured data abuse. This skill reads the page first, chooses the type from what the page is, fills properties from visible content, links the nodes in a single @graph, and validates the block before it goes into the template. It audits an existing block the same way.
When to use this skill
- A page type (guide, docs article, FAQ, tutorial, product, tool listing) has no JSON-LD and the template owner wants it done once, correctly.
- An existing block fails in Search Console with missing-field or invalid-value errors.
- A site moved CMS or framework and the structured data must be re-expressed in the new template.
- A pass with geo-content-auditor found a visible FAQ section that is not yet marked up.
When NOT to use this skill
- Titles, canonicals, sitemaps, redirects, and crawl hygiene: the seo-technical-auditor skill. It checks that JSON-LD is present; this one writes it.
- Making the prose itself quotable by answer engines: the geo-content-auditor skill.
- Rich-result bait: if the page has no FAQ, add the visible content first.
Instructions
-
Read the rendered page and name what it is. One primary type per page:
ArticleorTechArticlefor editorial and docs;FAQPageonly when a visible question-and-answer section exists;HowToonly for a visible step-by-step procedure;SoftwareApplicationfor a page about an app or tool;Productfor something sold with a visible price or reviews;BreadcrumbListon any page that shows breadcrumbs;Organizationonce, on the home or about page. Secondary nodes hang off the primary one. -
Extract values from visible content only. Headline from the H1, dates from the byline, author from the visible author line, FAQ questions and answers verbatim from the FAQ section, steps from the numbered procedure, price and currency only if printed. If a value is not on the page, omit the property and list it under "not present on page" in the report. Never pull a date from the git log or an author from a config file and call it visible.
-
Fill required properties, then recommended ones. Required is what Google's documentation lists for the rich result; a missing recommended property is a warning, not an error. Quick reference, to be checked against the current Search Central docs for the type before you promise anything:
Type Required for Google's rich result Commonly recommended Article / TechArticle none; headline,image,datePublished,authorare recommendeddateModified,author.url,publisherFAQPage mainEntityofQuestionnodes withnameandacceptedAnswer.textone node per visible pair HowTo name,step(eachHowToStepwithtext)image,totalTime,tool,supplySoftwareApplication name, anoffersprice withpriceCurrency(use0for free), a visible rating or reviewapplicationCategory,operatingSystemProduct name, plus one ofreview,aggregateRating,offersimage,description,sku,brandBreadcrumbList itemListElementofListItemwithposition,name,item(optional on the last)Organization name,urllogo,sameAs -
Use one
@graphwith stable@ids. PutOrganization,WebSite,WebPage, the primary node, andBreadcrumbListin one script with@idvalues such ashttps://example.com/#organization, so nodes reference each other instead of repeating. Dates in ISO 8601 with an offset; URLs absolute. -
Check what the template already emits.
rg -l 'application/ld\+json' srcand read it. TwoArticlenodes, or a plugin block whosedateModifieddisagrees with yours, send conflicting signals. Merge or remove; do not add a third. -
Validate three ways. Syntax:
node -e 'JSON.parse(require("fs").readFileSync(0,"utf8"))' < block.json. Vocabulary: the Schema.org validator at https://validator.schema.org/ accepts a URL or a pasted block. Eligibility: Google's Rich Results Test at https://search.google.com/test/rich-results reports only the types Google surfaces. Fix every error; explain each remaining warning in the report. -
Insert where the template renders. A
<script type="application/ld+json">in the head or body. In Next.js, render it from a Server Component viadangerouslySetInnerHTMLand escape<in the JSON (JSON.stringify(data).replace(/</g, "\\u003c")) so a</script>inside an answer cannot break out; Astro'sset:htmlneeds the same escape. Edit a file only when the user asked for insertion; otherwise return the block and the exact insertion point.
WARNING
Google's structured data guidelines require that marked-up content be visible to users on the page and that it describe that page, not a different one. Markup for content that is hidden, absent, or on another URL is the one thing this skill will refuse to write, because a manual action costs more than a missing rich result.
NOTE
Google has narrowed FAQ rich results to a small set of authoritative sites and no longer shows HowTo rich results. FAQPage and HowTo remain valid Schema.org and still describe the page to other consumers, including answer engines; do not promise a visible rich result from either.
Output
The JSON-LD block; a property table with columns Property, Where it appears on the page, and Status (present, omitted, or not on page); the three validator results; and the insertion point or the applied diff. For an audit of an existing block, the same table plus the list of values that have no visible counterpart.
Filed under
claude · seo · structured-data · json-ld · marketers · developers
Related
- SEO Technical AuditorAudit a website's source or built output (Next.js, Astro, or static HTML) for technical on-page and crawl hygiene: title and meta description length and uniqueness, self-referencing canonicals, one H1 and an unbroken heading hierarchy, presence of JSON-LD, sitemap and robots.txt, redirect chains, internal-link click depth, and image alt text, then return one findings table ordered by severity with the file or route to fix. Use when you want the crawl and markup plumbing checked across a whole site, not the quality of the writing or the correctness of the structured data.
- SEO SpecialistUse this agent to review a site or a set of pages for search and answer-engine performance and get one prioritized plan: it checks technical hygiene with the seo-technical-auditor skill, the match between each page's title, H1, and lead and the query it targets, title and meta wording, internal linking, answer-first structure with the geo-content-auditor skill, and structured data with the schema-markup-generator skill, then ranks the fixes by effect and effort. Read-only; it never edits a page or invents a search volume. Examples: "review our docs site for SEO and tell me what to fix first", "why does this guide rank but never get cited by AI Overviews", "audit the ten pages in this folder and give me a plan".
- GEO Content AuditorAudit one published page or draft for answer-engine and LLM-citation readiness: an answer-first lead, question-shaped headings each answered in their first sentence, one fact per sentence, figures with a date and a source beside them, definitions that can be quoted whole, consistent entity names, and a visible FAQ block, then return a pass-or-fix scorecard and an ordered rewrite plan with replacement text. Use when you want to know why a page is not being quoted by AI Overviews or chat assistants and what to change in the prose, not in the markup or the crawl setup.
- 9 Best Claude Skills for SEO (and AI Search)Compare Claude skills, commands, and agents for technical SEO audits, structured data, answer-engine readiness, llms.txt, content briefs, landing pages, Core Web Vitals, and brand voice.
- SEO CheckRun a single-page SEO and AEO check on a file or URL (title and meta lengths, one H1, heading order, answer-first lead, FAQ, structured data, canonical, internal links, alt text) and return a pass-or-fix table.
- An SEO Content Workflow in Claude Code: Brief, Draft, On-Page CheckA repeatable SEO content workflow in Claude Code: a content repo with CLAUDE.md, SERP research over Exa and Firecrawl MCP, a brief, a draft, and on-page checks.
- Answer Engine Optimization (AEO)Answer engine optimization (AEO) is structuring content so search engines and AI assistants can lift a direct answer from it for AI Overviews and chatbots.