How to use the SEO Schema Markup Checker agent skill

What the seo-schema skill makes the agent do

An agent skill is a folder of instructions that an AI agent loads when a task matches it. The seo-schema skill covers three jobs: detecting structured data on a supplied page or entity, validating it, and generating new Schema.org JSON-LD. It is meant to be used only when structured data or rich-result markup is requested.

During detection the agent extracts JSON-LD blocks from the page and flags any block without @context or @type, because Google cannot attach such a block to an entity. It also checks for Microdata and RDFa, and always recommends JSON-LD as the primary format, citing Google's stated preference.

• Validation checks required properties per schema type, missing @context, invalid @type, wrong data types, placeholder text, relative URLs, and invalid date formats.
• Deprecated types are flagged. Examples in the source include HowTo, whose rich results were removed in September 2023, and FAQPage, which Google retired as a rich result.
• Generation produces JSON-LD with placeholders such as [Company Name] for you to fill in, and only includes data it can present as truthful and verifiable.
• Review markup is checked: fake reviews and undisclosed incentivized reviews are rejected.

How do you install the seo-schema skill?

Download the ZIP file from the seo-schema page on this directory, then unzip it. Put the resulting seo-schema folder in one of two places: your personal skills folder at ~/.claude/skills/, or a project's .claude/skills/ folder if you want the skill only for that project.

If you use the Claude apps instead of a local setup, you can upload the skill under Settings, then Capabilities, then Skills.

The skill's SKILL.md file calls a script through ${CLAUDE_PLUGIN_ROOT}, so the skill expects the claude-seo plugin to be installed (see the requirements section below).

• Personal install: ~/.claude/skills/seo-schema/
• Project install: the .claude/skills/ folder inside your project
• Apps install: Settings, then Capabilities, then Skills, then upload

What do you need before the skill works?

The skill needs Claude Code or another agent with the claude-seo plugin installed, because the script path uses ${CLAUDE_PLUGIN_ROOT}. It also needs Python available to run the parse_html.py script, and network access so it can fetch the target URL.

The skill runs scripts and uses the network. Only point it at pages you own or are permitted to analyse, since it fetches the page from the internet.

• Claude Code or another agent with the claude-seo plugin installed
• Python available to run parse_html.py
• Network access to fetch the target URL

How do you trigger the skill with a natural request?

You do not need special syntax. Ask in plain language and name the page. The skill is user-invocable and takes a URL as its argument hint, so including the address helps. Make it clear that you want structured data checked or generated, because the skill is only meant to run when that is requested.

Good requests name the goal and the page type. For example, you might ask the agent to check the structured data on a product page, or to write Article JSON-LD for a blog post you are about to publish, and then fill in the placeholders yourself.

• Check the structured data on https://example.com/product-page and tell me what is broken.
• Generate LocalBusiness JSON-LD for my clinic with placeholders for the address and phone.
• Audit the Article markup on this post and list any relative URLs or invalid dates.
• Is the FAQPage markup on this page still useful for Google?

What does a report look like?

The skill's output is a SCHEMA-REPORT.md file with detection and validation results, and a generated-schema.json file with ready-to-use JSON-LD snippets. The report uses a table with Schema, Type, Status and Issues columns, marked with a check, warning or cross, followed by recommendations for missing opportunities, validation fixes and generated code.

When something goes wrong, the skill has set responses. An unreachable URL produces a connection error with the status code and advice to check the address and whether the page needs a login. A page with no markup gets a report saying no JSON-LD, Microdata or RDFa was found, along with suggested types. Invalid JSON-LD syntax is reported with specific errors and a corrected version.

What are the safety notes?

Fetched pages are treated as untrusted data. If a page contains text that addresses the agent, the skill reports it as a finding rather than obeying it. It will not run commands, install anything or change settings because fetched content asks it to.

Because the skill fetches pages from the internet and runs a Python script, read the SKILL.md file and the scripts before you rely on it in sensitive environments. The skill is MIT licensed, and the LICENSE.txt in the download points to the full terms in the repository.

• Analyse only pages you own or have permission to analyse.
• Treat fetched content as data, not instructions.
• Use the skill on your own machine where Python and network access are acceptable.

Tips for getting reliable results

Put JSON-LD in the initial server-rendered HTML for time-sensitive markup. Google supports JavaScript-generated structured data, but its guidance warns that dynamically generated Product markup can make Shopping crawls less frequent and less reliable for price and availability changes.

Always replace placeholders before publishing. The skill is designed to leave clearly marked fields for you to fill with truthful data, so check each one. Keep in mind that the skill's status list reflects the time it was written, so confirm current Google guidance for anything that affects a live site.

• Give the agent the full page URL, not just the domain.
• Ask for one page type at a time for cleaner output.
• Use the references folder's deprecated-types notes to check old markup before removing or replacing it.
• Remember that valid markup does not guarantee rich results, since Google decides what it displays.