metadata
Installation
SKILL.md
Metadata Skill
This skill provides guidance for writing complete, well-structured HTML <head> content. It covers essential meta tags, social sharing, performance optimization, and bot control.
Quick Reference Template
Copy this template and customize for each page:
<head>
<!-- Essential (order matters) -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Page Title - Site Name</title>
<meta name="description" content="Concise page description (150-160 chars)."/>
<!-- Canonical URL -->
<link rel="canonical" href="https://example.com/page"/>
<!-- Authorship -->
<meta name="author" content="Author Name"/>
<!-- Bot Control -->
<meta name="robots" content="index, follow"/>
<!-- Open Graph (Social Sharing) -->
<meta property="og:title" content="Page Title"/>
<meta property="og:description" content="Description for social sharing."/>
<meta property="og:image" content="https://example.com/images/share.jpg"/>
<meta property="og:url" content="https://example.com/page"/>
<meta property="og:type" content="website"/>
<meta property="og:site_name" content="Site Name"/>
<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image"/>
<!-- Performance Hints -->
<link rel="preconnect" href="https://fonts.googleapis.com"/>
<link rel="dns-prefetch" href="//analytics.example.com"/>
<!-- Theme -->
<meta name="theme-color" content="#ffffff"/>
<!-- Favicon -->
<link rel="icon" href="/favicon.ico" sizes="32x32"/>
<link rel="icon" href="/icon.svg" type="image/svg+xml"/>
<link rel="apple-touch-icon" href="/apple-touch-icon.png"/>
<!-- Stylesheets -->
<link rel="stylesheet" href="/styles/main.css"/>
</head>
Element Order in <head>
Order matters for performance and correctness:
<meta charset>- Must be first (within first 1024 bytes)<meta name="viewport">- Before any CSS<title>- Early for perceived performance<meta name="description">- SEO critical<link rel="canonical">- URL normalization- Other meta tags (author, robots, etc.)
- Open Graph / Twitter meta
- Performance hints (preconnect, dns-prefetch)
- Favicon links
- Stylesheets
- Scripts (usually at end of body, but critical JS here)
Metadata Categories
1. Essential (Required for All Pages)
| Element | Purpose | Notes |
|---|---|---|
<meta charset="utf-8"/> |
Character encoding | Must be first element |
<meta name="viewport" content="width=device-width, initial-scale=1"/> |
Responsive design | Required for mobile |
<title>Page - Site</title> |
Browser tab, search results | 50-60 characters max |
<meta name="description" content="..."/> |
Search snippets | 150-160 characters |
Example:
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Widget Pro - DemoCompany</title>
<meta name="description" content="The Widget Pro offers enhanced durability and a 5-year warranty. Our best-selling widget for professional use."/>
2. Authorship & Attribution
| Element | Purpose |
|---|---|
<meta name="author" content="..."/> |
Content author |
<link rel="canonical" href="..."/> |
Authoritative URL (prevents duplicate content) |
<meta name="generator" content="..."/> |
CMS/tool that generated the page |
<meta name="copyright" content="..."/> |
Copyright notice |
Example:
<meta name="author" content="DemoCompany Editorial Team"/>
<link rel="canonical" href="https://democompany.com/products/widget-pro"/>
3. Bot Control (Robots)
| Directive | Meaning |
|---|---|
index |
Allow indexing (default) |
noindex |
Prevent indexing |
follow |
Follow links (default) |
nofollow |
Don't follow links |
noarchive |
Don't cache the page |
nosnippet |
Don't show text snippets |
noimageindex |
Don't index images |
Examples:
<!-- Standard public page -->
<meta name="robots" content="index, follow"/>
<!-- Private/internal page -->
<meta name="robots" content="noindex, nofollow"/>
<!-- Legal page (index but don't cache) -->
<meta name="robots" content="index, follow, noarchive"/>
<!-- Search results page -->
<meta name="robots" content="noindex, follow"/>
Google-specific:
<meta name="googlebot" content="notranslate"/>
4. Open Graph (Social Sharing)
Required for rich social media previews on Facebook, LinkedIn, etc.
| Property | Purpose | Recommended |
|---|---|---|
og:title |
Share title | 60 characters |
og:description |
Share description | 200 characters |
og:image |
Share image | 1200x630px |
og:url |
Canonical URL | Absolute URL |
og:type |
Content type | website, article, product |
og:site_name |
Site name | Brand name |
Example:
<meta property="og:title" content="Widget Pro - Professional Grade Widget"/>
<meta property="og:description" content="Enhanced durability, 5-year warranty. Perfect for professional use."/>
<meta property="og:image" content="https://democompany.com/images/widget-pro-share.jpg"/>
<meta property="og:url" content="https://democompany.com/products/widget-pro"/>
<meta property="og:type" content="product"/>
<meta property="og:site_name" content="DemoCompany"/>
Article-specific:
<meta property="og:type" content="article"/>
<meta property="article:published_time" content="2024-01-15T08:00:00Z"/>
<meta property="article:modified_time" content="2024-01-20T10:30:00Z"/>
<meta property="article:author" content="Jane Smith"/>
<meta property="article:section" content="Technology"/>
5. Twitter Cards
| Property | Purpose |
|---|---|
twitter:card |
Card type: summary, summary_large_image, player |
twitter:site |
@username of website |
twitter:creator |
@username of author |
Example:
<meta name="twitter:card" content="summary_large_image"/>
<meta name="twitter:site" content="@democompany"/>
<meta name="twitter:creator" content="@janesmith"/>
6. Network Performance Hints
| Element | Purpose | When to Use |
|---|---|---|
<link rel="dns-prefetch"> |
Pre-resolve DNS | Third-party domains |
<link rel="preconnect"> |
Establish early connection | Critical third-parties |
<link rel="preload"> |
High-priority fetch | Fonts, critical CSS |
<link rel="prefetch"> |
Low-priority fetch | Next-page resources |
<link rel="prerender"> |
Pre-render entire page | Very likely next page |
Examples:
<!-- DNS prefetch for analytics -->
<link rel="dns-prefetch" href="//www.google-analytics.com"/>
<!-- Preconnect for fonts (includes DNS + TCP + TLS) -->
<link rel="preconnect" href="https://fonts.googleapis.com"/>
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous"/>
<!-- Preload critical font -->
<link rel="preload" href="/fonts/brand.woff2" as="font" type="font/woff2" crossorigin="anonymous"/>
<!-- Preload critical CSS -->
<link rel="preload" href="/css/critical.css" as="style"/>
<!-- Prefetch likely next page -->
<link rel="prefetch" href="/products/widget-pro"/>
7. Security
| Element | Purpose |
|---|---|
<meta name="referrer"> |
Control referrer information |
<meta http-equiv="Content-Security-Policy"> |
Inline CSP (prefer HTTP header) |
Referrer values:
no-referrer- Never send referrerorigin- Send only origin (domain)strict-origin-when-cross-origin- Full URL same-origin, origin cross-origin (recommended)
Example:
<meta name="referrer" content="strict-origin-when-cross-origin"/>
8. Mobile & PWA
| Element | Purpose |
|---|---|
<meta name="theme-color"> |
Browser chrome color |
<meta name="apple-mobile-web-app-capable"> |
iOS standalone mode |
<meta name="apple-mobile-web-app-status-bar-style"> |
iOS status bar |
<link rel="manifest"> |
PWA manifest |
Example:
<meta name="theme-color" content="#1a73e8"/>
<meta name="apple-mobile-web-app-capable" content="yes"/>
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent"/>
<link rel="manifest" href="/manifest.json"/>
9. Favicon
Modern favicon setup:
<!-- Standard favicon -->
<link rel="icon" href="/favicon.ico" sizes="32x32"/>
<!-- SVG favicon (modern browsers) -->
<link rel="icon" href="/icon.svg" type="image/svg+xml"/>
<!-- Apple touch icon -->
<link rel="apple-touch-icon" href="/apple-touch-icon.png"/>
<!-- Web app manifest (includes icons) -->
<link rel="manifest" href="/manifest.webmanifest"/>
Page Type Profiles
Different pages need different metadata:
Homepage
<meta name="robots" content="index, follow"/>
<meta property="og:type" content="website"/>
<!-- Include full Open Graph set -->
<!-- Include performance hints for common resources -->
Article/Blog Post
<meta name="author" content="Author Name"/>
<meta name="robots" content="index, follow"/>
<meta property="og:type" content="article"/>
<meta property="article:published_time" content="2024-01-15T08:00:00Z"/>
<meta property="article:author" content="Author Name"/>
Product Page
<meta name="robots" content="index, follow"/>
<meta property="og:type" content="product"/>
<meta property="product:price:amount" content="79.99"/>
<meta property="product:price:currency" content="USD"/>
Legal/Policy Pages
<meta name="robots" content="noindex, follow"/>
<!-- Or if should be indexed: -->
<meta name="robots" content="index, follow, noarchive"/>
Search Results
<meta name="robots" content="noindex, follow"/>
Error Pages (404, 500)
<meta name="robots" content="noindex, follow"/>
Validation
Run metadata validation:
npm run lint:meta
The validator checks:
- Required elements present
- Elements in correct order
- Content meets length requirements
- URLs are absolute where required
- Image dimensions adequate for social sharing
Common Mistakes
1. Charset Not First
<!-- Wrong -->
<title>Page</title>
<meta charset="utf-8"/>
<!-- Correct -->
<meta charset="utf-8"/>
<title>Page</title>
2. Relative URLs in Open Graph
<!-- Wrong -->
<meta property="og:image" content="/images/share.jpg"/>
<!-- Correct -->
<meta property="og:image" content="https://example.com/images/share.jpg"/>
3. Missing Viewport
Results in pages rendering at desktop width on mobile.
4. Duplicate Titles/Descriptions
Each page should have unique title and description.
5. Title Too Long
Search engines truncate after ~60 characters. Put important words first.
6. Missing Canonical
Can cause duplicate content issues, especially with URL parameters.
Extensibility
Metadata profiles are defined in JSON files in profiles/:
{
"name": "article",
"extends": "default",
"required": [
{ "name": "author" },
{ "property": "article:published_time" }
],
"recommended": [
{ "property": "article:author" },
{ "property": "article:section" },
{ "property": "article:tag" }
]
}
Create custom profiles by:
- Adding a new JSON file to
profiles/ - Setting
extendsto inherit from another profile - Adding
requiredandrecommendedarrays
Related Skills
- xhtml-author - Write valid XHTML-strict HTML5 markup
- performance - Write performance-friendly HTML pages
- security - Write secure web pages and applications
- i18n - Write internationalization-friendly HTML pages
Related skills
More from profpowell/vanilla-breeze
api-client
Fetch API patterns with error handling, retry logic, and caching. Use when building API integrations, handling network failures, or implementing offline-first data fetching.
44validation
Validate data with JSON Schema and AJV. Use when validating API requests, form submissions, database inputs, or any data boundaries. Provides deterministic validation with consistent error formats.
43fake-content
Generate realistic fake content for HTML prototypes. Use when populating pages with sample text, products, testimonials, or other content. NOT generic lorem ipsum.
15xhtml-author
Write valid XHTML-strict HTML5 markup. Use when creating HTML files, editing markup, building web pages, or writing any HTML content. Ensures semantic structure and XHTML syntax.
10layout-grid
Design-focused grid layout system with fluid scaling, responsive columns, and resolution-independent patterns. Use when creating page layouts, card grids, or multi-column designs.
8service-worker
Service worker patterns for offline support, caching strategies, and PWA functionality. Use when implementing offline-first features, caching, or background sync.
8