---
name: metadata
description: HTML metadata and head content. Use when writing or reviewing page head sections including SEO, social sharing, performance hints, and bot control.
allowed-tools: Read, Write, Edit, Bash
---
# Metadata Skill
This skill provides guidance for writing complete, well-structured HTML `` content. It covers essential meta tags, social sharing, performance optimization, and bot control.
## Quick Reference Template
Copy this template and customize for each page:
```html
Page Title - Site Name
```
---
## Element Order in ``
Order matters for performance and correctness:
1. `` - **Must be first** (within first 1024 bytes)
2. `` - Before any CSS
3. `` - Early for perceived performance
4. `<meta name="description">` - SEO critical
5. `<link rel="canonical">` - URL normalization
6. Other meta tags (author, robots, etc.)
7. Open Graph / Twitter meta
8. Performance hints (preconnect, dns-prefetch)
9. Favicon links
10. Stylesheets
11. 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` | Browser tab, search results | 50-60 characters max |
| `` | Search snippets | 150-160 characters |
**Example:**
```html
Widget Pro - DemoCompany
```
### 2. Authorship & Attribution
| Element | Purpose |
|---------|---------|
| `` | Content author |
| `` | Authoritative URL (prevents duplicate content) |
| `` | CMS/tool that generated the page |
| `` | Copyright notice |
**Example:**
```html
```
### 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:**
```html
```
**Google-specific:**
```html
```
### 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:**
```html
```
**Article-specific:**
```html
```
### 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:**
```html
```
### 6. Network Performance Hints
| Element | Purpose | When to Use |
|---------|---------|-------------|
| `` | Pre-resolve DNS | Third-party domains |
| `` | Establish early connection | Critical third-parties |
| `` | High-priority fetch | Fonts, critical CSS |
| `` | Low-priority fetch | Next-page resources |
| `` | Pre-render entire page | Very likely next page |
**Examples:**
```html
```
### 7. Security
| Element | Purpose |
|---------|---------|
| `` | Control referrer information |
| `` | Inline CSP (prefer HTTP header) |
**Referrer values:**
- `no-referrer` - Never send referrer
- `origin` - Send only origin (domain)
- `strict-origin-when-cross-origin` - Full URL same-origin, origin cross-origin (recommended)
**Example:**
```html
```
### 8. Mobile & PWA
| Element | Purpose |
|---------|---------|
| `` | Browser chrome color |
| `` | iOS standalone mode |
| `` | iOS status bar |
| `` | PWA manifest |
**Example:**
```html
```
### 9. Favicon
Modern favicon setup:
```html
```
---
## Page Type Profiles
Different pages need different metadata:
### Homepage
```html
```
### Article/Blog Post
```html
```
### Product Page
```html
```
### Legal/Policy Pages
```html
```
### Search Results
```html
```
### Error Pages (404, 500)
```html
```
---
## Validation
Run metadata validation:
```bash
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
```html
Page
Page
```
### 2. Relative URLs in Open Graph
```html
```
### 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/`:
```json
{
"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:
1. Adding a new JSON file to `profiles/`
2. Setting `extends` to inherit from another profile
3. Adding `required` and `recommended` arrays
## 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