seo-optimizer

When to use

Trigger this skill when the request includes any of:

“SEO review this draft before it goes live”
“Do keyword research for [topic]”
“Optimize this landing page”
“What should the meta tags be for the new case study?”
A finished draft plus a request to “make sure this ranks”

Do not use for paid search copy (different playbook), technical SEO audits of a whole domain (that is a separate engagement), or link-building outreach.

Inputs

Required:

Page URL or draft content — the thing being optimized.
Primary goal — one of: rank for a specific query, capture organic traffic for a topic cluster, or improve CTR on an existing page.

Optional:

Seed keyword — if known. If not, the skill will derive one from the content.
Target audience intent — helps disambiguate between a “how to” and “best X tools” angle.
Competitor URLs already ranking for the query.

Outputs

A single SEO brief containing:

Keyword map — seed keyword, 8-15 related queries grouped by intent (informational, navigational, commercial, transactional).
On-page recommendations:
- Title tag (≤60 chars).
- Meta description (≤155 chars).
- H1 (exactly one, matches intent).
- H2/H3 outline with keywords in natural placement.
- Internal links (minimum 3, to relevant cluster pages).
- External links (minimum 1 to a high-authority source).
- Image alt text suggestions for every image.
Schema.org markup — the JSON-LD block to embed (Article, FAQPage, HowTo, Product, or BreadcrumbList as appropriate).
Core Web Vitals checklist — what to verify before publish.
Gap note — 2-3 bullets on what the current draft is missing vs the top-ranking competitors.

Tool dependencies

WebSearch / web-fetch (required) — for SERP checks, competitor pulls, and Google auto-suggest.
Optional: Google Search Console MCP (if available) for existing-page CTR data.

Procedure

1. Keyword research

Start with the seed. If not provided, extract it from the page’s thesis. The seed should be 2-4 words.
Pull related queries. Use WebSearch for:
- Google auto-suggest (seed + a-z) for long-tail variants.
- “People also ask” box for the seed.
- Top 10 SERP results — scan their H1s and H2s for recurring phrases.
Classify intent for each query:
- Informational: “what is X,” “how does X work,” “X explained” — user wants to learn.
- Navigational: “X brand name,” “X login,” “X docs” — user wants a specific site.
- Commercial: “best X,” “X vs Y,” “X alternatives,” “X reviews” — user is comparing.
- Transactional: “buy X,” “X pricing,” “X free trial,” “X demo” — user is ready to act.
Filter to relevance. Drop queries that do not match the page’s goal. A case study should not try to rank for transactional queries.

2. On-page optimization

Title tag: ≤60 characters, primary keyword near the front, brand name at the end only if it fits. Sentence case preferred.
Meta description: ≤155 characters, primary keyword once, ends with a clear value statement. Not a sentence truncated from the body.
H1: exactly one per page, matches search intent, close match to the title tag without being identical.
H2/H3 hierarchy:
- H2s cover major sub-topics; each H2 should target a related query from the keyword map.
- H3s break down H2s. Do not skip from H2 to H4.
- Keywords in headings must read naturally. No stuffing.
Internal links: 3+ to relevant cluster pages. Anchor text is descriptive (“CI migration playbook”), never “click here.”
External links: 1+ to a high-authority source (industry report, primary research, spec doc). Never link to a direct competitor.
Image alt text: every image gets descriptive alt text, 6-12 words, includes the keyword only if naturally relevant. Decorative images get alt="".

3. Schema markup

Pick one primary schema type based on the page:

Blog post / educational content: Article with headline, author, datePublished, image.
Case study: Article + optional Review if there is a customer quote with rating.
Product / landing page: Product with name, description, offers.
FAQ section on any page: add FAQPage as secondary schema.
Tutorial / walkthrough: HowTo with step array.
All pages: BreadcrumbList for breadcrumb navigation.

Return the JSON-LD block as a code fence the dev team can paste into <head>.

4. Core Web Vitals checklist

Flag for the dev team:

LCP (Largest Contentful Paint) <2.5s — hero image optimized (WebP/AVIF), not lazy-loaded, preloaded if above the fold.
INP (Interaction to Next Paint) <200ms — defer non-critical JS, avoid long tasks on interaction.
CLS (Cumulative Layout Shift) <0.1 — width/height attributes on every image, reserved space for embeds and ads.
Page tested on PageSpeed Insights for both mobile and desktop.
Core Web Vitals field data reviewed in Search Console if the page has history.

5. Gap analysis

Read the top 3 ranking pages for the primary keyword. Note:

Topics they cover that the current draft does not.
Content formats they use (comparison tables, FAQs, embedded video, calculators).
Freshness signals (publish date visible, “updated 2026”).

Return 2-3 gap bullets.

Examples

Example 1: Blog post SEO brief

Input: Draft post titled “The paved road is beating the portal” targeting platform engineers.

Output (abridged):

## Keyword map

Seed: internal developer portal alternatives

Informational:
- what is a paved road in platform engineering
- internal developer portal vs paved road
- how does a paved road work

Commercial:
- internal developer portal alternatives
- best paved road tools 2026
- backstage alternatives

Transactional:
- paved road template pricing
- northstack pricing

## On-page

Title: Internal developer portal alternatives: why platform teams pick paved roads (59 chars)

Meta: Internal developer portals promised self-service. Paved roads deliver it.
Here is what platform teams learned running both for two years. (148 chars)

H1: Internal developer portal alternatives: why platform teams pick paved roads

H2 outline:
- What a paved road actually is
- Where the portal model broke (targets "backstage alternatives")
- Three signs your portal is becoming a museum
- How teams migrate from portal to paved road
- Paved road vs internal developer portal: the honest comparison

Internal links:
- /docs/paved-road-reference-architecture (anchor: "paved-road reference architecture")
- /blog/backstage-migration-guide (anchor: "Backstage migration")
- /customers/ramp (anchor: "how Ramp rolled out paved roads")

External link:
- CNCF Platform Engineering Maturity Model (anchor: "CNCF platform engineering model")

Image alt text:
- Hero diagram: "Paved road architecture showing template, runner, and policy layers"
- Screenshot: "northstack init command generating a working pipeline on first run"

## Schema

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Internal developer portal alternatives: why platform teams pick paved roads",
  "author": {"@type": "Organization", "name": "Northstack"},
  "datePublished": "2026-04-19",
  "image": "https://northstack.dev/blog/paved-road-hero.png"
}

## Core Web Vitals checklist
- [ ] Hero image under 200KB in WebP
- [ ] Hero not lazy-loaded (above the fold)
- [ ] All images have width/height attributes
- [ ] Tested on PageSpeed Insights

## Gap note
- Top 3 competitors all include a comparison table. This draft does not. Add one.
- Two of the top three have a FAQ block. Add 4-6 FAQs and tag with FAQPage schema.
- All top-ranking pages show a visible "updated 2026" date. Make sure ours does too.

Example 2: Landing page SEO review

Input: Pricing page for Northstack Runners.

Output (abridged):

## Keyword map
Seed: ci runner pricing
Transactional: northstack pricing, ci runner pricing, per-minute ci cost
Commercial: github actions vs northstack, circleci alternatives pricing

## On-page
Title: Runners pricing: $0.004/min, no seat fees (54 chars)
Meta: Transparent per-minute CI pricing. No seat fees. See a cost estimate for
your pipeline volume in 30 seconds. (114 chars)
H1: Runners pricing
...

## Schema
Use Product schema with offers. Add FAQPage for the pricing FAQ at the bottom.

## Gap note
- No pricing comparison vs GitHub Actions or CircleCI. Competitors have this.
- No ROI calculator. Add one — this is a high-intent page.
- Missing trust signals near pricing (SOC 2, uptime).

Constraints

Title tag ≤60 characters, hard limit.
Meta description ≤155 characters, hard limit.
Exactly one H1 per page.
Keyword density target: primary keyword appears naturally 3-8 times in a 1,500 word piece. Never force it.
Internal link anchors are descriptive, never “click here” or “read more.”
No keyword stuffing in alt text, headings, or body copy.
Schema JSON-LD must validate against Google’s Rich Results Test before ship.
Do not optimize for keywords the content cannot honestly deliver on — that is the fastest way to get hit by a helpful content update.

Quality checks

Before returning the brief, confirm:

Department

Safety

Supported stacks