onpage-optimization · git:20261105.12a3bbd · 2026-11-05 · sha256 6f8f00041b295c30

onpage-optimization git:20261105.12a3bbdA

Immutable. This exact content never changes and is served at /api/v1/blob/6f8f00041b295c30.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_lx62s2xdmqtojac5/6f8f00041b295c30b92bd51ff8039ad7265bc22e8d30ccff4191e93f4a685637.json

Then /plugin install onpage-optimization@markdownregistry-lx62s2xdmqtojac5 in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: onpage-optimization
description: Audit and optimize page titles, meta descriptions, H1-H6 heading hierarchies, image alt text and dimensions, favicon, and Open Graph / Twitter social cards.
---

# onpage-optimization — On-Page Metadata & Heading Optimization

## 1. Description & Activation Criteria

Activate `onpage-optimization` when the user wants to:

- Audit or improve `<title>`, `<meta name="description">`, `<h1>`–`<h6>` structure, image `alt` and `width`/`height` attributes, favicons, and Open Graph / Twitter social sharing tags.
- Fix snippet truncation, missing metadata, skipped heading levels (`O04-headings`), empty headings (`O04-heading-empty`), or H1-to-title topical drift (`O03-h1-drift`).
- Run a focused on-page audit via `--skills onpage-seo` (or alias `--skills onpage-optimization`).

## 2. Inputs & Prerequisites

- **Target**: URL, local `.html` file, or build directory.
- **Calibrated thresholds (`lib/checks.mjs` -> `THRESHOLDS`)**:
  - `<title>`: `30–60` characters (`O01-title-missing` P0, `O01-title-short` P2, `O01-title-long` P2).
  - `<meta name="description">`: `120–155` characters (`O02-meta-missing` P1, `O02-meta-short` P2, `O02-meta-long` P2).
  - `<h1>`: Exactly 1 per page (`O03-h1-missing` P1, `O03-h1-multi` P1) sharing key terms with `<title>` (`O03-h1-drift` P3).

## 3. Step-by-Step Workflow

1. **Run an on-page and accessibility audit**:
   - Execute `npx one-step-seo page <target> --skills onpage-seo,accessibility-ux --out ./seo-report`.
2. **Inspect document identity (`O01`, `O02`, `O03`)**:
   - Check `report.page.title` (`report.page.title.length`), `report.page.metaDescription` (`report.page.metaDescription.length`), and `report.page.h1`.
   - Ensure `<title>` and `<h1>` share at least one substantive keyword token so `O03-h1-drift` passes and users see a consistent headline after clicking from search results.
3. **Audit heading hierarchy (`O04-headings`, `O04-heading-empty`, `O05-h2`)**:
   - Verify headings never skip levels (e.g., `<h1>` directly to `<h3>`), contain visible text (`O04-heading-empty`), and divide pages of 600+ words with `<h2>` subheadings (`O05-h2`).
4. **Verify image and social metadata (`O08-alt`, `O09-img-dims`, `O06-og`, `O07-favicon`, `W01-social`, `W02-og-url`)**:
   - Confirm every informative `<img>` has descriptive `alt` text (`alt=""` is valid only for decorative images) and explicit `width` + `height` attributes (`O09-img-dims`) to prevent Cumulative Layout Shift (CLS).
   - Check `og:title`, `og:description`, `og:image`, `og:url`, and `twitter:card`.
5. **Draft or preview fixes**:
   - For local files with missing tags, preview additive fixes with `npx one-step-seo fix <file> --only title,description,og,og-url,twitter-card,favicon`.

## 4. Tools & CLI Commands

```bash
# Audit on-page SEO and accessibility rules
npx one-step-seo page https://example.com --skills onpage-optimization,accessibility-ux --out ./seo-report

# Preview local metadata fixes without modifying files
npx one-step-seo fix ./dist/index.html --url https://example.com/ --lang en
```

## 5. Evidence Requirements

- Quote the exact current `<title>` and its character count (`report.page.title` and `report.page.title.length`, or `O01-*` evidence), current `<meta name="description">` and its character count (`report.page.metaDescription` and `report.page.metaDescription.length`, or `O02-*` evidence), and all `<h1>` texts (`report.page.h1`).
- Quote the exact count of images missing `alt` or `width`/`height` from `O08-alt` and `O09-img-dims` evidence.

## 6. Expected Outputs

1. **Current vs Recommended Metadata Table**: Current value, character count, issue ID, and proposed replacement within calibrated character ranges (`30–60` chars for title, `120–155` chars for meta description).
2. **Heading Outline Audit**: Current H1–H6 progression and fixes for skipped or empty headings.
3. **Image & Social Tag Checklist**: Missing `alt`, `width`/`height`, Open Graph, and Twitter card snippets.

## 7. Limitations & External Data

- **Automated CLI checks**: Title/meta presence and length, H1 count and title overlap, heading level sequence, empty headings, H2 presence on 600+ word pages, image `alt` and `width`/`height` attributes, favicon link, Open Graph, and Twitter card tags.
- **Advisory / manual judgment**: Writing compelling copy or describing specific image contents (`O08-alt`) requires human or agent inspection of the page subject and image asset.
- **External data**: Live SERP pixel-width truncation and click-through rate (CTR) experiments require Google Search Console Performance data.

## 8. Safety & Approval Rules

- Never auto-populate `alt` text with filenames or keyword-stuffed strings; describe the actual image content or use `alt=""` if purely decorative.
- Never overwrite existing `<title>` or `<meta name="description">` tags without showing the user the proposed copy first.

## 9. Examples

```bash
# Run on-page optimization checks on a local HTML file
npx one-step-seo page ./dist/pricing.html --skills onpage-optimization --offline --out ./seo-report
```