schema-markup
by alirezarezvanischema-markup skill helps agents plan, write, audit, and validate JSON-LD for rich results. Use it for Article, FAQPage, HowTo, Product, LocalBusiness, Organization, and BreadcrumbList markup with implementation patterns, schema type guidance, and a Python validator script for Technical Seo workflows.
This skill scores 84/100, which means it is a solid listing candidate for directory users who want an agent to implement, audit, or validate schema markup with less guesswork than a generic SEO prompt. The repository provides clear activation criteria, reusable templates, schema-type guidance, and a validator script, though adoption would be easier with explicit installation instructions and clearer boundaries around what the local validator can and cannot prove.
- Very clear trigger guidance in frontmatter, including positive triggers like structured data, JSON-LD, rich results, FAQ/Product/HowTo schema, and exclusions for general SEO or crawl audits.
- Substantial operational content: SKILL.md defines context-gathering, implementation/audit/validation use cases, and when to consult product marketing context before asking questions.
- Useful support materials include schema type guidance, copy-paste JSON-LD implementation patterns, and a Python script that extracts and validates JSON-LD from HTML.
- No install command or README is present at the skill path, so directory users must infer installation from the broader repository conventions.
- The included validator scores required/recommended field coverage locally, but the references still instruct testing in Google Rich Results; it is not a substitute for official rich-result validation.
Overview of schema-markup skill
What schema-markup does
The schema-markup skill helps an AI agent plan, write, audit, and validate JSON-LD structured data for pages that need clearer eligibility for Google rich results and better machine-readable context for AI search. It is built for Technical Seo work where the deliverable is not a broad audit, but concrete schema markup: Article, BlogPosting, FAQPage, HowTo, Product, LocalBusiness, Organization, BreadcrumbList, and related schema.org types.
Best fit for this skill
Use this schema-markup skill when you already know the page type or problem: missing FAQ schema, Product markup errors, Article rich result eligibility, Search Console structured data warnings, or a need to standardize JSON-LD across a CMS. It is especially useful for marketers, SEO specialists, developers, and content teams who need implementation-ready JSON-LD plus validation guidance rather than a generic explanation of schema.org.
What makes it different from a normal prompt
The repository includes practitioner references, copy-ready implementation patterns, and a Python validator script. That matters because schema work fails on details: absolute image URLs, required properties, visible-content alignment, publisher logos, ISO dates, and CMS injection limits. The skill gives the agent a structured intake process before generating markup, reducing the chance of plausible but invalid JSON-LD.
When not to use it
Do not install schema-markup as a replacement for a full technical crawl, JavaScript rendering diagnosis, internal linking review, or site architecture audit. If the real issue is indexability, canonicals, crawl depth, or template rendering, use a broader SEO or site architecture workflow first, then return to schema once the target pages and templates are stable.
How to Use schema-markup skill
schema-markup install and files to inspect first
Install the skill with:
npx skills add alirezarezvani/claude-skills --skill schema-markup
After installation, read marketing-skill/skills/schema-markup/SKILL.md first to understand the trigger rules and intake workflow. Then inspect references/schema-types-guide.md for type selection and required fields, references/implementation-patterns.md for JSON-LD examples, and scripts/schema_validator.py if you want a local sanity check against required and recommended fields.
Inputs the skill needs before generating JSON-LD
For strong schema-markup usage, give the agent page-level facts, not just “add schema.” Include:
- Page URL and canonical URL
- Page type, such as product, article, FAQ, local business, how-to, or category
- Visible title, author, publish and modified dates
- Primary image URL with dimensions
- Organization name, logo URL, and sameAs profiles
- Product price, availability, SKU, reviews, or offers where relevant
- CMS or implementation method, such as WordPress plugin, Webflow custom code, Shopify theme, or direct
<head>access - Existing Search Console errors or rich result test messages
A weak prompt is: “Create schema for this page.”
A stronger prompt is: “Use the schema-markup skill to create JSON-LD for this BlogPosting page. URL: https://example.com/blog/schema-guide. H1: Schema Markup Guide. Author: Jane Smith. Published: 2026-02-10. Modified: 2026-03-01. Image: https://example.com/images/schema-guide.jpg, 1200x630. Publisher logo: https://example.com/logo.png, 250x60. Match visible page content and flag any missing fields before writing final JSON-LD.”
Practical workflow for implementation
Start with an audit of existing markup. View page source, check Search Console structured data reports, or save the rendered HTML and run python3 scripts/schema_validator.py page.html. Then ask the skill to classify the page type and choose the narrowest valid schema type. For example, a blog post should usually use BlogPosting, while a transactional product page needs Product with offers.
Next, generate JSON-LD, compare every property against visible page content, and test it in Google Rich Results Test before deployment. After deployment, re-test the live URL and monitor Search Console. The skill can help interpret validation messages, but it cannot guarantee rich results; Google eligibility depends on content quality, policy compliance, crawlability, and search demand.
Tips that improve output quality
Ask for “implementation-ready JSON-LD plus missing-field notes.” This prevents the agent from silently inventing unavailable data. For templates, ask for a reusable pattern with variables, such as {{ product.title }} or {{ article.published_at }}. For regulated or trust-heavy pages, request a conservative version that only marks up content visibly present on the page. For multi-schema pages, ask the skill to connect entities with stable @id values so Organization, WebPage, BreadcrumbList, and Article data do not look disconnected.
schema-markup skill FAQ
Is schema-markup beginner friendly?
Yes, if you can collect page facts and test output. The references explain what common schema types do, which fields matter, and what mistakes block eligibility. Beginners should start with one page type, such as Article or FAQPage, validate it, then expand to templates after the pattern is proven.
Can it fix Search Console structured data errors?
It can help interpret and correct many structured data errors, especially missing required properties, malformed JSON-LD, wrong schema type, and incomplete Product or Article fields. It will not fix errors caused by inaccessible pages, blocked scripts, broken templates, or content that Google cannot render. For those, solve the technical issue first.
How is this different from schema plugins?
Plugins can inject schema quickly, but they often use generic defaults, miss business-specific entity details, or create duplicate markup across themes and extensions. The schema-markup skill is more useful when you need editorial judgment, custom JSON-LD, template strategy, or an audit of what the plugin already outputs.
Is schema-markup for Technical Seo teams only?
No, but it is strongest for Technical Seo workflows where structured data has to be accurate, testable, and deployable. Content teams can use it for Article, FAQ, and HowTo planning. Developers can use it to convert approved schema into templates. Ecommerce teams can use it to check Product, Offer, availability, and review markup before rollout.
How to Improve schema-markup skill
Provide stronger source evidence
The best way to improve schema-markup results is to provide the same evidence Google can verify: rendered page copy, visible headings, product details, author pages, images, dates, breadcrumbs, and organization profiles. If a field is not visible or cannot be verified, tell the agent to mark it as missing instead of fabricating it.
Watch for common schema-markup failure modes
Common failures include using relative image URLs, adding FAQ markup for questions not visible on the page, marking marketing copy as reviews, missing offers on Product schema, mismatched author names, invalid date formats, and duplicate JSON-LD from multiple plugins. Another frequent issue is over-marking: adding every possible schema type instead of the few that accurately represent the page.
Iterate after the first output
After the first JSON-LD draft, ask for a validation pass: “Check required fields, recommended fields, visible-content alignment, Google rich result eligibility, and implementation risks.” Then run the validator script or Google’s testing tools and paste the exact errors back into the agent. Error-specific iteration produces much better results than asking for a general rewrite.
Adapt the skill to your CMS and templates
For repeatable adoption, turn one validated page into a template-level implementation. Ask the skill to map schema fields to CMS variables, identify fallback behavior when fields are empty, and define where JSON-LD should be injected. This is where schema-markup becomes more valuable than one-off prompting: it can help create a controlled structured data workflow that editors, SEOs, and developers can maintain.