# json-ld — AI agent skill

> Scan the codebase for every entity worth marking up, verify against the live schema.org release — never model memory — and wire JSON-LD to your real data flow.

- Category: SEO
- Version: 1.1.2 (updated July 2026)
- License: MIT
- Author: Alex Kharchenko — Mavens Tech Lab (https://mavenslab.tech/)
- Tested on: Claude Code
- Also compatible with: Cursor, Codex, GitHub Copilot, Windsurf, dozens more via skills.sh
- Source: https://github.com/Mavens-Tech-Lab/skills/tree/main/json-ld
- Human-readable page: https://mavenslab.tech/skills/json-ld

## Install

Claude Code (plugin):

```
/plugin install json-ld@mavens-skills
```

Any other agent (Cursor, Codex, and 70+ more) — via the skills.sh CLI:

```
npx skills add Mavens-Tech-Lab/skills --skill json-ld
```

Or add the whole Mavens Tech Lab marketplace once, then pull any skill on demand:

```
/plugin marketplace add Mavens-Tech-Lab/skills
```

## What it does

It treats structured data as an engineering problem, not a copy-paste snippet. First it scans your codebase — ORM schemas, CMS content types, content collections, routes — and builds an inventory of every entity that should carry markup, including the ones you didn't mention. Then it fetches the **live** schema.org release and Google's **current** rich-results documentation, because both change out from under trained models: schema.org ships new versions continuously, and Google retires rich-result types without deprecating the vocabulary. A property that wasn't verified against a definition fetched *that day* doesn't get emitted.

Every value is then wired to your real data flow — the same database column, CMS field, or frontmatter key the page renders — through one shared builder module with stable `@id`s and one connected `@graph` per page. A property whose source is empty is omitted and reported, never filled with a plausible guess: no invented dates, no fabricated ratings (a documented Google manual-action trigger), no markup for content that isn't visibly on the page.

> If it can't verify a definition online, it stops and says so rather than emitting from stale memory — and anything your data can't support ships as a gap report ("add an `updatedAt` column → unlocks `dateModified`"), not as an invented value.

## When to use it

When product pages have no markup and you want rich-result eligibility done properly. When Search Console starts flagging structured-data errors after a redesign. When you inherit hand-rolled JSON-LD that's drifted from the database, or microdata from 2015 that should become JSON-LD. Or when an audit tool says "add schema" and you want the version that survives a validator — and the next schema.org release.

## What you get

- **An entity inventory** (`jsonld-scan.md`) covering the whole site: every entity, its data source, its pages, its candidate types, what markup already exists and whether it's wrong — including justified *skip* rows, so lean output reads as decisions.
- **Fresh-definition traceability**: every emitted type and property recorded against the schema.org page and Google doc it was verified on, with the release version and fetch date.
- **One round of questions** for what code can't know — ambiguous types with the consequences spelled out, organization identity, `sameAs` profiles, data-exposure choices — each with a recommended default.
- **Production code in your stack's conventions** — Next.js (App/Pages router), Astro, Nuxt, SvelteKit, SSGs like Hugo or Eleventy, Django, Rails, Laravel, WordPress (extending Yoast/Rank Math/WooCommerce graphs through their filters instead of fighting them), or Shopify Liquid themes (any theme — native `structured_data` filter where it fits, per-property `| json` for the rest, cents→price handled, theme + SEO-app emitters deduplicated, Liquid data structures verified via the Shopify Dev MCP) — with XSS-safe serialization throughout.
- **Repairs, not duplicates**: existing markup is fixed in place or deepened; formats are converted only with your OK; one node per `@id`, everywhere.
- **Validation against rendered HTML** — the markup is re-extracted and re-parsed from what crawlers actually receive (a zero-dependency script ships with the skill), checked for Google-required coverage, and run through live validators when browser tooling is available.
- **An honest closing report**: coverage per page type (*n of m* recommended properties, with the missing ones named), every gap tied to the data change that would unlock it, everything deliberately omitted with the reason, and the follow-ups code can't do — like watching Search Console after deploy.

---

Built by [Mavens Tech Lab](https://mavenslab.tech/) — a software studio that builds, deploys, and maintains custom agent skills. Need this wired into your stack? info@mavenslab.tech