Metadata lint

Read a page's head tags and report what's wrong, most serious first, with the minimal fix for each. No scripts or paid tools needed: you check the HTML or the code directly. The output is a short report, not a rewrite of the site.

When to use it

• Before shipping a new page, or after a site migration.
• When a link shared on LinkedIn or Slack shows the wrong title or no image.
• When pages show up in search with odd titles, or not at all.

Don't use it for what the copy should say (that's /website-copy) or for a full marketing review of the page (that's /website-score).

Inputs

• A live URL, an HTML file, or the code for the page (a Next.js metadata export, a layout file, Astro frontmatter, a manual <head>). One page per run; repeat for more.
• context/brand/ if you have it: the brand name and title format the site should use.

Agency users: swap context/ for clients/<client>/context/. If you only have a URL, fetch the raw HTML (view-source, not the rendered text) so you can see the actual tags.

Steps

1. Get the head. Fetch the HTML or open the files that set metadata. Note which system sets it, so fixes match the project's pattern. Produces: the full list of head tags.
2. Check each rule group below, in order. Record every failure with the line or tag where it occurs. Produces: a list of findings.
3. Cross-check the four that must agree: title, description, canonical and og:url. Compare protocol, subdomain and trailing slash exactly. Produces: a match or a mismatch.
4. Check the share preview on the real URL, not localhost, using LinkedIn's Post Inspector or a similar card validator if you can. Produces: a pass or fail with a screenshot or note.
5. Write the minimal fix for each finding, scoped to metadata only. Produces: the report.

The rules, most serious first

1. Duplicates and correctness (critical). One source of metadata per page. No duplicate title, description, canonical or robots tags. Values are stable, not random. Dynamic text is escaped. Every page has a default title and description.
2. Title and description (high). Every page has a title, in one consistent format such as {Page} | {Brand}, roughly 50 to 60 characters. Shareable pages have a plain-text description, roughly 150 to 160 characters.
3. Canonical and indexing (high). The canonical points to the preferred URL. noindex only on private, duplicate or staging pages, and staging should have it. Robots matches what you actually want indexed.
4. Social cards (high). Open Graph title, description and image on every shareable page. Images use absolute URLs, ideally 1200 by 630. og:url matches the canonical. og:type is website or article. twitter:card is summary_large_image by default.
5. Icons (medium). A working favicon, an apple-touch-icon, a valid manifest if referenced, and a deliberate theme-color.
6. Structured data (medium). JSON-LD only where it matches what's on the page, valid, and never with invented ratings, reviews or prices. JSON-LD injected by JavaScript won't show in raw HTML; check those pages in Google's Rich Results Test.
7. Language and alternates (lower). <html lang> is set. hreflang only for pages that exist, with each language linking back to the others.

What good looks like

• Every critical and high finding names the exact tag and the exact fix.
• The fix follows the project's existing setup and touches nothing else.
• Clean checks are listed too, so the reader knows what was verified.

Mistakes to avoid

• Testing the share card on localhost, where no platform can reach it.
• Missing a mismatch over a trailing slash or www.
• Adding schema for things the page doesn't show.
• Refactoring layout or switching SEO libraries while fixing a tag.
• Reading the rendered page text instead of the raw HTML, and missing tags entirely.

Common fixes

<!-- Relative image: make it absolute -->
<meta property="og:image" content="https://acme.com/og.png" />

<!-- Canonical and og:url disagree on the trailing slash: make them identical -->
<link rel="canonical" href="https://acme.com/pricing" />
<meta property="og:url" content="https://acme.com/pricing" />

<!-- Staging page with no robots tag -->
<meta name="robots" content="noindex,nofollow" />

Output

Save to outputs/website/MMYY-metadata-lint-<page>.md:

# Metadata lint: <page or URL>

## Critical (fix before ship)
- [Duplicates] <title> set in layout.tsx:12 and page.tsx:8. Fix: keep one.
## High (fix this cycle)
- [Social] og:image is relative "/og.png". Fix: use the absolute URL.
## Medium (backlog)
- ...
## Checked and clean
- Title format consistent. Canonical matches og:url.

Attribution

Adapted from the fixing-metadata skill in ibelick/ui-skills (MIT, Julien Thibeaut): https://github.com/ibelick/ui-skills