> JSON-LD Audit Skill for Claude Code

I've been writing JSON-LD by hand for clients since 2015 and keep trying to find better ways to do it. Debuggers/linters were a huge help, and the generator I built was really helpful as well but nothing can beat the power of AI for JSON-LD.

Pop the page into Google's Rich Results Test. Look at what's broken. Hand-rewrite the script tag. Paste it back. For a thirty-page site, that was like a full day of work!

I built this Claude Code skill that I could drop into whatever site I'm working on so I don't have to keep explaining the same thing over and over again.

what it actually does

You install it. Point it at a URL on your site. It reads the page, parses any JSON-LD that's already there, classifies what kind of page it is (Article, Product, Recipe, About, fact-check, whatever), and writes a markdown report telling you what's working, what's broken, what's missing, and what you set on purpose.

Then it walks your sitemap and does the same thing across the site. That's the part nobody else does.

the thing every other JSON-LD tool gets wrong

Existing tools generate from a menu. Pick "Product." Fill in a form. Copy the output. Paste it in. That works the first time you ever wrote schema. It doesn't help you fix what you already have.

Most schema work isn't generation. It's audit. So I built it backwards from the rest of the market.

embarrassing finding from my own site

I ran this against jsonld.com first. The site-wide pass caught a real issue I didn't know about.

I had https://jsonld.com/#organization declared as the publisher on every single article. But I never defined that Organization canonically anywhere - not on the homepage, not on /about-us/, nowhere. The publisher reference pointed to an entity that had no home page.

I'd been running it that way for months. Never noticed. No single-page validator catches this because the per-article JSON looks fine in isolation. The skill catches it because it builds a registry across the whole sitemap and flags any @id that's referenced but never defined.

That's exactly the kind of cross-page issue you can't catch by hand on a thirty-page site. You'd have to manually open every page and remember what every other page declared. Nobody does this.

what the report actually looks like

It's a markdown file. The top is one of:

• STRONG, no required changes
• STRONG with site-wide note (the page is fine but the broader graph has an issue)
• Required changes, with a list

Below that you get an entity registry table, per-block audit, validator status, Rich Results eligibility per declared type, optional enrichments (clearly marked optional - not errors), and a section called "Notably already present (don't change)" so a future run doesn't keep suggesting changes to things you set on purpose.

That last section matters more than it sounds. Most schema tools nag forever about a missing Person.gender or some KG signal you deliberately skipped. This one writes down what you've decided and stops bothering you about it.

honest about deprecations

Google killed the FAQ rich result in May 2026. Most schema tools haven't updated their advice yet. The skill flags it correctly: FAQPage is still valid schema.org, still parsed by LLMs and Bing AI and Perplexity and voice assistants and scrapers. Just not surfaced as a snippet in Google search anymore.

It's a judgment call whether you keep the markup. Schema doesn't die because Google stops showing it. The skill says so.

Same story with HowTo (deprecated for desktop in 2023). Same with QAPage for general sites.

what it doesn't do

Lots.

• Not a bulk generator. If you have a 200-page site with zero JSON-LD anywhere, generators specialized for templates are still faster. This is audit-first by design.
• Doesn't hit the schema.org validator over HTTP yet. Validation is by inspection, which catches most things but isn't a hard CI gate. Real wiring is on the roadmap.
• Won't tell you why your traffic dropped. Schema is one signal among many.
• Only has detailed rubrics for 9 archetypes right now (Person/About, Article, Product, Recipe, Event, LocalBusiness, JobPosting, ClaimReview, FAQPage). Everything else falls back to a universal meta-rubric. Coverage will grow.

install it

Three commands.

# Grab the latest release
curl -L https://github.com/patrickcoombe/json-ld-claude-skill/releases/latest/download/jsonld-audit.tar.gz -o ~/jsonld-audit.tar.gz

# Install as a Claude Code skill
mkdir -p ~/.claude/skills
cd ~/.claude/skills && tar xzf ~/jsonld-audit.tar.gz

Open Claude Code in any project directory and say something like "audit my JSON-LD on https://yoursite.com" or "check my schema markup on the homepage." The skill loads on those triggers.

It creates a .jsonld/ folder in whatever directory you ran it from. That holds the site-index cache and your persistent answers. Add it to .gitignore unless you want the entity registry committed.

Note: it does NOT edit your files. Report only. You paste the suggested JSON-LD yourself.

what's next

Schema.org validator over HTTP. Standalone CLI sharing the same audit library. Template clustering for sites with 100+ similar pages. More archetype rubrics.

If you try it and find a bug, a wrong finding, or a finding that's right but framed wrong - open an issue. I run it against jsonld.com regularly so improvements land fast.

Repo: github.com/patrickcoombe/json-ld-claude-skill
License: MIT