agentleFS
CrawlCoveCrawlCove/claude-seo-plugin/skills/schema-markup/SKILL.md

schema-markup

Skill0 starsChanged yesterdayMITView on GitHub

Check a page's structured data and write correct JSON-LD for its page type, validated against the properties Google requires for rich results. Use when the user asks for schema markup, structured data, JSON-LD, schema.org, rich results, rich snippets, review stars, FAQ schema, Product, Article, Organization, LocalBusiness, Breadcrumb, Event, Recipe, Video or JobPosting markup, 'add schema to my page', 'validate my schema', 'why are my rich results not showing', or a structured data error from Search Console.

67 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use internal-link-audit, product-marketing-context and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • semrushSkill

    internal-link-audit

    Audit internal linking to find orphan pages, broken internal links, crawl-depth problems, and weak anchor distribution, then plan the hub-and-spoke structure that fixes them. Use when the user asks about internal links, orphan pages, site architecture, crawl depth, or how to pass authority to priority pages.

    Also in 3 projects that use this

  • xfstudioSkill

    product-marketing-context

    When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'marketing context,' 'set up context,' 'positioning,' or wants to avoid repeating foundational information across marketing tasks. Creates `.claude/product-marketing-context.md` that other marketing skills reference.

    Also in 19 projects that use this

  • LangChainSkill

    content-brief

    Turn a vague or multi-asset design ask into a brief. Pull what is already known, ask at most two questions with reasons, decide the rest and say what you decided.

    Also in 5 projects that use this

  • ukunal91appSkill

    revops

    When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and processes that connect marketing to revenue. For cold outreach emails, see cold-email. For email drip campaigns, see email-sequence. For pricing decisions, see pricing-strategy.

    Also in 14 projects that use this

  • VercelSkill

    site-architecture

    Use when planning or restructuring what pages a site has and how they connect: hierarchy, navigation, URL patterns, breadcrumbs, and internal linking. Not for XML sitemaps, which are in seo-audit.

    Also in 16 projects that use this

  • alaraakcasizSkill

    technical-seo-audit

    Technical and on-page SEO audit of any website — a client site, your own site, a competitor, or a staging build before a CMS migration. Use this skill whenever the user asks for an SEO audit, technical SEO audit, on-page audit, site health check, crawl analysis, or the SEO section of a broader digital marketing audit. Also trigger for migration/replatform work ("are we losing pages", "build a redirect map", "compare old site vs new site", Webflow to Framer, WordPress to Shopify, any CMS to any CMS), and whenever the user uploads Screaming Frog exports (internal_all.csv, image_details.csv, All Inlinks), a GSC Pages export, or a sitemap and wants them analysed. Covers indexability, canonicals, crawl directives, headings, titles and metas, alt text, schema markup, page speed, robots.txt, llms.txt, internal linking, page-inventory diffing and redirect mapping.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 66 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Look for the Crawl Cove crawl tools: names ending in crawl_site, get_page, list_pages.

    line 12
  2. Very specific:

    Inventory existing markup: every JSON-LD block, plus any microdata (itemscope) or RDFa.

    line 25
  3. Distinctive:

    Markup must match visible content: Do not mark up reviews, prices, FAQs or authors that a visitor cannot see on that page.

    line 35

“Common” is measured: kept by at least 6 in 10 of the 66 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Schema markup: check it and write it

Structured data does two things: it makes a page eligible for specific rich results in Google, and it states plainly what the page's entities are. It is not a ranking boost. Write markup only for content that is visible on the page, in the types Google acts on, with every required property present.

Step 0: which mode are you in, and what the crawl tools can do here

Look for the Crawl Cove crawl tools: names ending in crawl_site, get_page, list_pages.

The crawl tools do not extract JSON-LD. Their job in this skill is to find the pages and templates that need markup. Reading a page's existing markup always needs the page's HTML: fetch it with your web fetch tool or a shell, or ask the user to paste the page source.

  • Crawl mode (tools present): you can survey the site's page types, then fetch representatives.
  • Page mode (tools absent, as in claude.ai chat): work on the page or pages the user gives you. Say you have seen N pages and cannot speak for the rest of the site.

Procedure

  1. Establish the page type. One page, or the whole site?
    • Whole site, crawl mode: crawl_site { "url": "<home page>", "maxPages": 100 }, then list_pages { "indexable": true, "limit": 200 }. Group URLs by path pattern into templates (home, category, product, article, location, contact, about). Pick one representative URL per template.
    • One page: use the URL or pasted source given.
  2. Get the HTML of each representative page. Prefer a raw fetch (curl -sL <url>) over a summarising fetch, since you need the exact <script type="application/ld+json"> blocks. Note that markup injected by JavaScript will be missing from a raw fetch; if the user says markup exists and you see none, that is why. Google can read injected JSON-LD, though less reliably for fast-changing data such as price.
  3. Inventory existing markup: every JSON-LD block, plus any microdata (itemscope) or RDFa. For each block record @type, whether it parses as JSON, and its properties.
  4. Validate each block against the rules and the type table below.
  5. Decide what the page should have from the table. Remove or stop maintaining types that earn nothing.
  6. Write the JSON-LD, filled with values taken from the page. Where a required value is not on the page, put a clearly marked placeholder and list it under "You need to supply".
  7. Report in the output format.

Rules that apply to every type

  • JSON-LD in a <script type="application/ld+json"> is the format Google recommends. Head or body are both fine.
  • Valid JSON: double quotes, no trailing commas, no comments, special characters escaped. One syntax error voids the whole block.
  • Markup must match visible content. Do not mark up reviews, prices, FAQs or authors that a visitor cannot see on that page. This is the commonest cause of a manual action for structured data.
  • Mark up the page's main thing, on that page. Product markup belongs on the product page, not on a category page listing twenty products.
  • Absolute URLs for url, image, logo, @id, sameAs.
  • Dates in ISO 8601 with a timezone where time matters: 2026-03-14T09:00:00+00:00.
  • Connect entities with @id (for example https://example.com/#organization) and reference that @id from publisher, author, brand, so parsers see one organisation and not five. Several types can share one block inside "@graph": [...].
  • Required properties are a gate: missing one means no rich result for that item. Recommended properties improve eligibility and display.
  • Eligible is not guaranteed. Google decides per query whether to show a rich result.

Types worth writing, and what Google needs

Google changes this list several times a year. Treat the table as a starting point and confirm against Google's structured data gallery (https://developers.google.com/search/docs/appearance/structured-data/search-gallery) before promising a rich result.

PageTypeRequired by GoogleAdd if on the page
Home or aboutOrganization (or a subtype)none strictly; give name, urllogo, sameAs, contactPoint, legalName, description
HomeWebSitename, urlalternateName (site name shown in results)
Any page below the home pageBreadcrumbListitemListElement with position, name, item (the last item may omit item)
Blog post, news, guideArticle, BlogPosting or NewsArticlenone strictlyheadline, image, datePublished, dateModified, author with name and url
Product page that sellsProduct with offersname, image, offers with price, priceCurrencyavailability, sku, gtin, brand, aggregateRating, review, shippingDetails, hasMerchantReturnPolicy
Product page that reviewsProductname plus one of review, aggregateRating, offers
Physical businessLocalBusiness (most specific subtype)name, addresstelephone, openingHoursSpecification, geo, priceRange, url, image
EventEventname, startDate, locationendDate, eventStatus, eventAttendanceMode, offers, image, organizer
Job advertJobPostingtitle, description, datePosted, hiringOrganization, jobLocation (or remote fields)validThrough, baseSalary, employmentType
RecipeRecipename, imagerecipeIngredient, recipeInstructions, times, nutrition, aggregateRating
Page whose main content is a videoVideoObjectname, thumbnailUrl, uploadDatedescription, duration, contentUrl or embedUrl
Software or app pageSoftwareApplicationname, offers.price (0 for free), and aggregateRating or reviewapplicationCategory, operatingSystem
Author or member profileProfilePagemainEntity (a Person or Organization) with namesameAs, description, image
Forum thread or single user questionDiscussionForumPosting, QAPagesee Google's page for each

Review stars: aggregateRating needs ratingValue and ratingCount or reviewCount. Ratings must be about the specific item, collected on that page. Stars are not shown for LocalBusiness or Organization when the business marks up reviews of itself on its own site.

Types that no longer earn a rich result

Say this plainly when the user asks for one, so they do not wait for a result that will not come.

  • FAQPage: since August 2023 the FAQ rich result is shown only for well-known government and health sites. For anyone else it earns no rich result. The markup is harmless and still states question and answer pairs for machines, so write it if asked and say what it will not do.
  • HowTo: the rich result was removed in 2023.
  • Sitelinks search box (WebSite with SearchAction): removed in late 2024.
  • Google announced in 2025 that it was retiring several minor types, among them Course Info, Claim Review, Estimated Salary, Learning Video, Special Announcement and Vehicle Listing. Check the gallery before writing any of these.

Common faults when validating existing markup

  1. JSON syntax error: trailing comma, curly quotes pasted from a document, unescaped quote inside a description.
  2. Wrong nesting: price on Product in place of on offers; author as a bare string where Person with name is wanted (a string is tolerated, an object is better).
  3. @type misspelt or wrong case (Localbusiness), or an invented property name. schema.org names are case-sensitive.
  4. Relative image or url values.
  5. aggregateRating with no visible reviews, or copied from a third-party site.
  6. Several blocks describing the same organisation with different names, logos or URLs, usually from a theme and a plugin both emitting markup. Keep one.
  7. datePublished in a local format (14/03/2026).
  8. Product markup on a category page, or Article on a product page.
  9. availability as free text. Use https://schema.org/InStock, OutOfStock, PreOrder and so on.
  10. Price with a currency symbol or thousands separator: use "price": "1299.00", "priceCurrency": "GBP".

Output format

# Schema markup: <page or site>
Seen: <N> page(s): <URLs>. <In crawl mode: chosen as representatives of T templates from a crawl of M pages.>

## What is there now
| Page | Type found | Valid JSON | Problems |

## What to change
1. <fix or addition, the page or template it applies to, and what it makes the page eligible for>

## JSON-LD
### <page type or URL>
<one fenced json code block, complete and ready to paste, inside the script tag>

## You need to supply
- <each placeholder left in the markup, and where the value should come from>

## Test it
Paste the page URL or the code into Google's Rich Results Test (https://search.google.com/test/rich-results) for rich result eligibility, and the Schema Markup Validator (https://validator.schema.org/) for schema.org syntax.

Placeholders use the form "REPLACE: opening hours for Monday" so they cannot be shipped unnoticed.

Wrong conclusions to avoid

  • "Schema will improve rankings." It makes pages eligible for richer display and clarifies entities. Promise eligibility, never position.
  • "I validated it." You checked it against the rules here. Only the Rich Results Test confirms what Google accepts. Always send the user there.
  • Inventing values to satisfy a required property. A made-up rating, price or address is worse than no markup. Leave a placeholder.
  • Adding every type that could apply. More types do not mean more results. One correct primary type per page, plus BreadcrumbList, and Organization once on the home page, covers most sites.
  • Assuming the template is consistent. You checked one representative per template. Say so. If the user needs every page verified at scale, that is a job for a crawler that extracts structured data, which the bundled tools here do not do.
  • No rich result a week after adding markup is normal. Google needs to recrawl, and may still choose not to show it.

Page mode notes

Without the crawl tools nothing in this skill changes except the survey step: you cannot list the site's templates. Work from the pages given, ask for the page source (View Source) when you cannot fetch, and state "I have seen N pages" in the report.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.