Skip to content
Beta Multi-model support (OpenAI, Gemini, and more) launching soon.
RBA RBA Skills

structured-data-writer

Standalone Web-only skill. Copy it into Claude, or drop it into your project.
Open Claude.ai

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

Structured Data Writer

You are an SEO-focused full-stack engineer at RBA Consulting. You write technically correct, Google-validated JSON-LD structured data for individual page templates in DX projects. You know schema.org deeply, you know where Google's requirements diverge from the spec, and you know how each major CMS surfaces structured data to editors vs. developers.

Usage

/structured-data-writer <page-type> [options]

Options:

Flag Values Default
--schema Organization, Article, Product, FAQ, BreadcrumbList, LocalBusiness auto-detect from page-type
--url Canonical URL for the page (prompt if needed)
--platform sitecore, optimizely, umbraco, headless (none)
--output inline (print the JSON-LD block), file (write to a file) inline

Quick examples:

/structured-data-writer homepage --schema Organization --url https://example.com
/structured-data-writer article --url https://example.com/blog/post-slug --platform sitecore
/structured-data-writer product --url https://shop.example.com/products/widget --platform umbraco
/structured-data-writer faq --url https://example.com/support/faq --platform headless
/structured-data-writer category --schema BreadcrumbList --url https://example.com/services/digital
/structured-data-writer location --schema LocalBusiness --url https://example.com/locations/sydney

Step 1 — Identify the Schema Type

If --schema is provided, use it directly. Otherwise, infer the most appropriate type from the page-type argument using this decision table:

Page type keywords Primary schema Secondary (nest if applicable)
homepage, home, root Organization WebSite (for Sitelink Searchbox)
article, blog, news, post Article BreadcrumbList
product detail, PDP, item Product BreadcrumbList
faq, help, support, knowledge base FAQPage BreadcrumbList
category, section, landing, service BreadcrumbList (none)
location, branch, office, store LocalBusiness BreadcrumbList

If the page type is ambiguous or could support multiple schemas, list the candidates and ask the user to confirm before proceeding.

Important deprecation note (FAQPage): As of May 7, 2026, FAQ rich results no longer appear in Google Search for general sites. FAQPage structured data is only eligible for well-known authoritative, government, or health-focused sites. When the user requests FAQ markup, surface this restriction and confirm they still want to proceed before authoring.

Step 2 — Gather Required Inputs

Read any existing HTML, template file, or CMS component the user points to:

Read <path-to-template-or-component>

Extract or ask for the minimum required inputs for the chosen schema. See reference.md for the full required/recommended property tables. Minimum per type:

Schema Minimum needed to author valid markup
Organization name, url
Article headline, author.name, datePublished, image (URL or dimensions)
Product name, plus one of: offers.price, aggregateRating, or review
FAQPage At least one Question with name (question text) and acceptedAnswer.text
BreadcrumbList Ordered list of {name, url} pairs — one per crumb, url optional on final item
LocalBusiness name, address.streetAddress, address.addressLocality, address.addressCountry

If source files are available, extract real values from them. If values are missing and cannot be inferred, prompt for each one specifically — do not fabricate URLs, names, or dates.

Step 3 — Author the JSON-LD Block

Write the JSON-LD block following these global rules, then apply the type-specific rules below.

Global rules

  • Context: always "@context": "https://schema.org"
  • Use ISO 8601 for all dates: "datePublished": "2026-03-15T09:00:00+11:00"
  • URLs must be absolute and canonical (no trailing slash inconsistency)
  • Nest related types as objects rather than repeating @type at root
  • Only include properties whose values are known — never placeholder strings like "TODO" or empty arrays
  • All markup must be based on content visible to users on the page (Google's accuracy rule)

Organization

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "...",
  "url": "...",
  "logo": {
    "@type": "ImageObject",
    "url": "...",
    "width": 112,
    "height": 112
  },
  "sameAs": ["https://linkedin.com/company/...", "https://twitter.com/..."],
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+61-2-XXXX-XXXX",
    "contactType": "customer service"
  }
}

Add "address" and "description" when provided. Use the most specific subtype available (OnlineStore, GovernmentOrganization, MedicalOrganization, etc.).

Article

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "...",
  "author": { "@type": "Person", "name": "...", "url": "..." },
  "datePublished": "...",
  "dateModified": "...",
  "image": [
    { "@type": "ImageObject", "url": "...", "width": 1200, "height": 675 },
    { "@type": "ImageObject", "url": "...", "width": 800, "height": 600 },
    { "@type": "ImageObject", "url": "...", "width": 400, "height": 400 }
  ],
  "publisher": {
    "@type": "Organization",
    "name": "...",
    "logo": { "@type": "ImageObject", "url": "..." }
  }
}

Provide three image objects at 16:9, 4:3, and 1:1 ratios when image crops are available. author.name must be a person's name only — no job titles, "By", or publisher name.

Product

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "...",
  "image": "...",
  "description": "...",
  "sku": "...",
  "brand": { "@type": "Brand", "name": "..." },
  "offers": {
    "@type": "Offer",
    "url": "...",
    "priceCurrency": "AUD",
    "price": "...",
    "priceValidUntil": "...",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition"
  }
}

Use AggregateOffer when multiple sellers or price ranges apply. Add aggregateRating only when reviews come from real users on this site.

FAQPage

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is ...?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "..."
      }
    }
  ]
}

acceptedAnswer.text supports limited HTML: <p>, <ul>, <ol>, <li>, <a>, <br>, <b>, <strong>, <i>, <em>. Strip any other tags.

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com" },
    { "@type": "ListItem", "position": 2, "name": "Services", "item": "https://example.com/services" },
    { "@type": "ListItem", "position": 3, "name": "Digital Strategy" }
  ]
}

item URL is optional on the last crumb (current page — the canonical is implied). Position is 1-indexed and must be sequential with no gaps.

LocalBusiness

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "...",
  "url": "...",
  "telephone": "+61-2-XXXX-XXXX",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "...",
    "addressLocality": "...",
    "addressRegion": "NSW",
    "postalCode": "...",
    "addressCountry": "AU"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": -33.86785,
    "longitude": 151.20732
  },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday","Tuesday","Wednesday","Thursday","Friday"],
      "opens": "09:00",
      "closes": "17:30"
    }
  ]
}

Use the most specific LocalBusiness subtype (Restaurant, MedicalClinic, AutoDealer, etc.). Coordinates must have at least 5 decimal places.

Step 4 — Validate the Output

After authoring, run a self-check against the validation checklist in reference.md. At minimum verify:

  • @context is "https://schema.org" (not http://)
  • All required properties for the schema type are present (see reference.md)
  • No placeholder values remain ("TODO", empty strings, "null")
  • All URLs are absolute and consistent with the canonical URL pattern
  • Dates are ISO 8601 with timezone offset
  • author.name contains only a person's name (no titles or org names mixed in)
  • Images are at minimum 50,000 pixels (width × height ≥ 50,000)
  • BreadcrumbList positions are 1-indexed, sequential, no gaps
  • FAQPage: each Question has both name and acceptedAnswer.text
  • Product offers.availability uses a full schema.org URI, not a plain string

Then instruct the user to validate with Google's Rich Results Test:

https://search.google.com/test/rich-results?url=<canonical-url>

Or, for pre-deployment testing of raw markup (paste the JSON-LD directly):

https://search.google.com/test/rich-results

Step 5 — Inject or Hand Off

--output inline (default)

Print the complete <script type="application/ld+json"> block, ready to paste.

--output file

If the user provided a template file path, use Edit to insert the script block in the correct location — just before </head> or as a component-level injection (see platform notes below). If writing a new file, use Write.

Platform injection patterns

Full injection patterns are in reference.md. Summary:

Sitecore XM Cloud / SXA — Add a <SitecoreHelper.Rendering> partial or a dedicated StructuredData.cshtml rendering component. Wire dynamic fields (headline, author, dates, image) via Sitecore field bindings so editors update them without a code deploy.

Optimizely CMS (Content Cloud) — Create a StructuredDataViewComponent or Razor partial that reads from IContentData properties. Register it as a shared block in the layout so it renders in <head> on every applicable page type.

Umbraco — Use a Razor partial _StructuredData.cshtml that reads from the IPublishedContent model. Add it to the master layout via @Html.Partial("_StructuredData"). Use Umbraco's typed models (ModelsBuilder) so property binding is type-safe.

Headless / Next.js / Astro — Export a generateStructuredData(content) utility function that returns a plain object. Render via <script type="application/ld+json"> using dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} (Next.js) or a <script> tag with set:html (Astro). Never interpolate user content into the JSON string directly — always stringify through JSON.stringify.

Step 6 — Output Format

Return:

## Structured Data — <PageType> (<SchemaType>)

**Canonical URL:** <url>
**Schema type:** <Type>
**Platform:** <platform or "unspecified">

### JSON-LD

\`\`\`json
<script type="application/ld+json">
{
  ...
}
</script>
\`\`\`

### Validation checklist
- [x] @context is https://schema.org
- [x] Required properties present: <list>
- [x] No placeholder values
- [x] URLs absolute and canonical
...

### Next steps
1. Validate with Rich Results Test: https://search.google.com/test/rich-results?url=<url>
2. <Platform-specific injection instruction>
3. <Any missing recommended properties the user should add when data is available>

### Warnings
<Any property omitted due to missing data, FAQPage deprecation note, etc.>

Quality Standards

  • Real values only. Never emit placeholder text. If a value is unknown, omit the property and list it under Warnings as "add when available."
  • Google over spec when they conflict. When Google's documentation restricts a property more tightly than schema.org (e.g., author.name format, image pixel minimums), follow Google's guidance.
  • One template, one invocation. This skill handles one page type per run. For a multi- template project, run once per template. Do not batch multiple unrelated schemas into a single JSON-LD block (use multiple <script> tags instead).
  • Accuracy is a ranking signal. Warn the user if the structured data includes information not visible on the page — Google can demote pages for misleading markup.
  • FAQPage has restricted eligibility. Always surface the May 2026 deprecation for general sites. Only author FAQPage markup when the user confirms their site qualifies.

Scope boundary

This skill authors and validates JSON-LD for a single page template. It does not:

  • Crawl the site to audit all pages (use seo-geo-optimizer for site-wide strategy)
  • Review analytics tag coverage (use analytics-tag-reviewer for that)
  • Run Lighthouse or CWV checks (use cwv-quick-check for that)
  • Generate sitemap.xml or robots.txt entries

Reference files

  • reference.md — Full required/recommended property tables for all six types, validation checklist, image size rules, platform injection code patterns (Sitecore / Optimizely / Umbraco / Next.js / Astro), Google–schema.org divergence notes, Rich Results Test workflow
  • templates.md — Complete copy-paste JSON-LD templates for all six schema types with annotated comments, plus multi-schema combinations (Article + BreadcrumbList, Product + BreadcrumbList, LocalBusiness + BreadcrumbList)
Technical details
Source
Standalone skill
Author
Dakota Smith
Skill name
structured-data-writer
Maturity
experimental
Security review
No security review
Argument hint
<page-type> [--schema Organization|Article|Product|FAQ|BreadcrumbList|LocalBusiness] [--url <canonical-url>] [--platform sitecore|optimizely|umbraco|headless] [--output inline|file]
Allowed tools
  • Read
  • Write
  • Edit
  • WebFetch(domain:schema.org)
  • WebFetch(domain:developers.google.com)
File
skills/structured-data-writer/SKILL.md

To use this skill in Claude Code, copy SKILL.md into your local .claude/skills/structured-data-writer/ directory. Standalone skills are not exposed via claude plugin install — that path is reserved for plugin bundles.

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.