On-Page SEO
Optimize a single page for search relevance, click-through, and crawler comprehension. Stack-agnostic. Works on any CMS, framework, or static site.
When to use
- Auditing or optimizing a single page (homepage, product page, article, landing page)
- Writing or reviewing title tags and meta descriptions
- Fixing header structure or content hierarchy
- Reviewing internal links from or to a page
- Improving a page's CTR from search results
When NOT to use
- Site-wide crawl, indexing, or speed issues (use
seo-technical)
- Keyword research or intent mapping (use
seo-keyword)
- Competitor SERP analysis (use
seo-competitor)
- Auditing many pages at once for prune/merge decisions (use
seo-content-audit)
Required inputs
- The page URL or the draft content if pre-launch
- The primary target query (one phrase the page should rank for)
- The page's role in the site (commercial, informational, navigational)
If the target query is unknown, run seo-keyword first or ask the user to name one.
The framework: 8 dimensions
A complete on-page audit covers eight dimensions. Score each as Pass, Needs work, or Fail. Note the specific fix.
1. Title tag
- One unique title per URL across the site
- Roughly 50 to 60 characters (longer gets truncated in SERPs)
- Primary query near the front
- Brand at the end if it earns inclusion
- Distinct from the H1 (often very similar, but should not be identical word-for-word)
2. Meta description
- One unique description per URL
- Roughly 150 to 160 characters
- Restates the value proposition, not the title
- Includes a soft CTA where natural
- Treats the description as ad copy that earns the click
3. Header structure
- Exactly one H1 per page
- H1 contains or paraphrases the primary query
- H2 sections cover the major sub-topics
- H3+ used only when an H2 has genuine sub-points
- No skipped levels (no H2 followed by H4)
- Headers describe sections accurately enough that a reader could navigate by them alone
4. Body content
- Opens with the primary user intent answered in the first paragraph
- Covers the topic comprehensively (define your competition's depth, then match or exceed it)
- Includes related entities and supporting concepts naturally
- Avoids keyword stuffing (write for the reader, not the bot)
- Reading level matches the audience (run a readability check)
- Paragraphs short enough to scan on mobile (3 to 5 lines)
5. Internal links
- At least 2 to 3 outbound internal links to closely related pages
- At least 2 to 3 inbound internal links from related pages
- Anchor text is descriptive, not "click here" or "learn more"
- Links to canonical URLs, not redirects
- No broken internal links
6. Images and media
- Every meaningful image has descriptive alt text (skip alt for purely decorative images)
- File names are descriptive ("blue-running-shoe.jpg" not "IMG_4032.jpg")
- Modern format used where supported (WebP, AVIF)
- Lazy loading on below-the-fold images
- Width and height attributes set to prevent layout shift
7. URL slug
- Lowercase, hyphen-separated
- Includes the primary query naturally (no stuffing)
- Short (under 60 characters where possible)
- No dates unless the page is genuinely time-bound
- No session IDs, tracking parameters, or random hashes
- Matches the site's URL pattern conventions
8. On-page schema
- Appropriate Schema.org type for the content (Article, Product, FAQPage, HowTo, Recipe, etc.)
- Required properties filled (review Schema.org docs for the type)
- Validates in Google's Rich Results Test or equivalent
- Matches what is visible on the page (do not lie to crawlers)
- Author and publisher schema linked correctly for content pages
Workflow
- Confirm the target query. If unclear, ask. Do not optimize without one.
- Render the page. View it as a user would. Read the content top to bottom.
- View the rendered HTML. Inspect the actual served markup, not just the visual page. Check
<title>, <meta>, headers, and schema in the source.
- Run the 8-dimension framework. Score each, note specific fixes.
- Prioritize. Group fixes into Critical (broken or missing), Important (suboptimal), and Nice-to-have (polish).
- Write the report. Use the template in
references/audit-template.md.
- Offer to draft fixes. If the user wants, draft the new title, meta, headers, or copy directly.
Failure patterns
When you spot one of these, push back before delivering.
- "Make it more SEO." Vague. Ask for the target query and what's broken first.
- "Add the keyword 5 times in the body." Keyword density is not a real ranking signal. Prioritize relevance and topical depth instead.
- Optimizing a page that is not crawlable or indexable. Check
seo-technical first. No on-page work helps a noindexed page.
- Optimizing a page with no clear user intent. A page that does not serve a real query will not rank no matter how well-tagged it is.
- Targeting the same query as another page on the site. This is cannibalization. Use
seo-content-audit to decide which page should rank.
Output format
Default output is a markdown audit at seo-audit-[page-slug].md in the project root. Structure:
- Page summary (URL, target query, role)
- Score across 8 dimensions
- Critical fixes
- Important fixes
- Nice-to-have polish
- Drafted replacements (if requested)
Keep audits under 1500 words. If a page needs more detail, link to deeper appendices.
Reference files
references/audit-template.md - Fillable audit template, copy and use.
references/onpage-checklist.md - Quick-reference checklist for the 8 dimensions.
references/title-and-meta-patterns.md - Patterns for writing strong titles and meta descriptions.
1---2name: "seo-onpage"3description: "Run a comprehensive on-page SEO audit or optimization pass covering title tags, meta descriptions, header structure, content quality, internal links, image optimization, URL hygiene, and on-page schema. Use this skill whenever the user asks to optimize a page, audit on-page SEO, fix titles or meta tags, review header structure, check internal linking, improve a single URL's search performance, or write SEO-friendly copy. Triggers on on-page SEO, page audit, title tag, meta description, H1, header structure, internal links, image alt, URL slug, page optimization, optimize this page, SEO this page. Also triggers for any single-page review where ranking, click-through, or relevance signal quality is the goal, even if the user does not say 'SEO' explicitly."4metadata:5 source: https://skillmd.com/skills/slipcast-dev/seo-onpage6---78# On-Page SEO910Optimize a single page for search relevance, click-through, and crawler comprehension. Stack-agnostic. Works on any CMS, framework, or static site.1112---1314## When to use1516- Auditing or optimizing a single page (homepage, product page, article, landing page)17- Writing or reviewing title tags and meta descriptions18- Fixing header structure or content hierarchy19- Reviewing internal links from or to a page20- Improving a page's CTR from search results2122## When NOT to use2324- Site-wide crawl, indexing, or speed issues (use `seo-technical`)25- Keyword research or intent mapping (use `seo-keyword`)26- Competitor SERP analysis (use `seo-competitor`)27- Auditing many pages at once for prune/merge decisions (use `seo-content-audit`)2829---3031## Required inputs3233- The page URL or the draft content if pre-launch34- The primary target query (one phrase the page should rank for)35- The page's role in the site (commercial, informational, navigational)3637If the target query is unknown, run `seo-keyword` first or ask the user to name one.3839---4041## The framework: 8 dimensions4243A complete on-page audit covers eight dimensions. Score each as Pass, Needs work, or Fail. Note the specific fix.4445### 1. Title tag46- One unique title per URL across the site47- Roughly 50 to 60 characters (longer gets truncated in SERPs)48- Primary query near the front49- Brand at the end if it earns inclusion50- Distinct from the H1 (often very similar, but should not be identical word-for-word)5152### 2. Meta description53- One unique description per URL54- Roughly 150 to 160 characters55- Restates the value proposition, not the title56- Includes a soft CTA where natural57- Treats the description as ad copy that earns the click5859### 3. Header structure60- Exactly one H1 per page61- H1 contains or paraphrases the primary query62- H2 sections cover the major sub-topics63- H3+ used only when an H2 has genuine sub-points64- No skipped levels (no H2 followed by H4)65- Headers describe sections accurately enough that a reader could navigate by them alone6667### 4. Body content68- Opens with the primary user intent answered in the first paragraph69- Covers the topic comprehensively (define your competition's depth, then match or exceed it)70- Includes related entities and supporting concepts naturally71- Avoids keyword stuffing (write for the reader, not the bot)72- Reading level matches the audience (run a readability check)73- Paragraphs short enough to scan on mobile (3 to 5 lines)7475### 5. Internal links76- At least 2 to 3 outbound internal links to closely related pages77- At least 2 to 3 inbound internal links from related pages78- Anchor text is descriptive, not "click here" or "learn more"79- Links to canonical URLs, not redirects80- No broken internal links8182### 6. Images and media83- Every meaningful image has descriptive alt text (skip alt for purely decorative images)84- File names are descriptive ("blue-running-shoe.jpg" not "IMG_4032.jpg")85- Modern format used where supported (WebP, AVIF)86- Lazy loading on below-the-fold images87- Width and height attributes set to prevent layout shift8889### 7. URL slug90- Lowercase, hyphen-separated91- Includes the primary query naturally (no stuffing)92- Short (under 60 characters where possible)93- No dates unless the page is genuinely time-bound94- No session IDs, tracking parameters, or random hashes95- Matches the site's URL pattern conventions9697### 8. On-page schema98- Appropriate Schema.org type for the content (Article, Product, FAQPage, HowTo, Recipe, etc.)99- Required properties filled (review Schema.org docs for the type)100- Validates in Google's Rich Results Test or equivalent101- Matches what is visible on the page (do not lie to crawlers)102- Author and publisher schema linked correctly for content pages103104---105106## Workflow1071081. **Confirm the target query.** If unclear, ask. Do not optimize without one.1092. **Render the page.** View it as a user would. Read the content top to bottom.1103. **View the rendered HTML.** Inspect the actual served markup, not just the visual page. Check `<title>`, `<meta>`, headers, and schema in the source.1114. **Run the 8-dimension framework.** Score each, note specific fixes.1125. **Prioritize.** Group fixes into Critical (broken or missing), Important (suboptimal), and Nice-to-have (polish).1136. **Write the report.** Use the template in [`references/audit-template.md`](references/audit-template.md).1147. **Offer to draft fixes.** If the user wants, draft the new title, meta, headers, or copy directly.115116---117118## Failure patterns119120When you spot one of these, push back before delivering.121122- **"Make it more SEO."** Vague. Ask for the target query and what's broken first.123- **"Add the keyword 5 times in the body."** Keyword density is not a real ranking signal. Prioritize relevance and topical depth instead.124- **Optimizing a page that is not crawlable or indexable.** Check `seo-technical` first. No on-page work helps a noindexed page.125- **Optimizing a page with no clear user intent.** A page that does not serve a real query will not rank no matter how well-tagged it is.126- **Targeting the same query as another page on the site.** This is cannibalization. Use `seo-content-audit` to decide which page should rank.127128---129130## Output format131132Default output is a markdown audit at `seo-audit-[page-slug].md` in the project root. Structure:1331341. Page summary (URL, target query, role)1352. Score across 8 dimensions1363. Critical fixes1374. Important fixes1385. Nice-to-have polish1396. Drafted replacements (if requested)140141Keep audits under 1500 words. If a page needs more detail, link to deeper appendices.142143---144145## Reference files146147- [`references/audit-template.md`](references/audit-template.md) - Fillable audit template, copy and use.148- [`references/onpage-checklist.md`](references/onpage-checklist.md) - Quick-reference checklist for the 8 dimensions.149- [`references/title-and-meta-patterns.md`](references/title-and-meta-patterns.md) - Patterns for writing strong titles and meta descriptions.150