# Seo Optimizer

> Use when a page or post needs keyword research, intent classification, and on-page SEO review before publish. Produces a keyword map (seed to related queries with intent), on-page recommendations (title, meta, headings, links, alt text, schema), and a Core Web Vitals checklist.

- **Type:** Skill
- **Install:** `agentstack add skill-tahirraufkeeyu-software-development-agent-stack-sdas-seo-optimizer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tahirraufkeeyu](https://agentstack.voostack.com/s/tahirraufkeeyu)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tahirraufkeeyu](https://github.com/tahirraufkeeyu)
- **Source:** https://github.com/tahirraufkeeyu/software-development-agent-stack--sdas/tree/main/departments/marketing/skills/seo-optimizer

## Install

```sh
agentstack add skill-tahirraufkeeyu-software-development-agent-stack-sdas-seo-optimizer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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:

1. **Keyword map** — seed keyword, 8-15 related queries grouped by intent (informational, navigational, commercial, transactional).
2. **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.
3. **Schema.org markup** — the JSON-LD block to embed (`Article`, `FAQPage`, `HowTo`, `Product`, or `BreadcrumbList` as appropriate).
4. **Core Web Vitals checklist** — what to verify before publish.
5. **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

1. **Start with the seed.** If not provided, extract it from the page's thesis. The seed should be 2-4 words.
2. **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.
3. **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.
4. **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

1. **Title tag:** ≤60 characters, primary keyword near the front, brand name at the end only if it fits. Sentence case preferred.
2. **Meta description:** ≤155 characters, primary keyword once, ends with a clear value statement. Not a sentence truncated from the body.
3. **H1:** exactly one per page, matches search intent, close match to the title tag without being identical.
4. **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.
5. **Internal links:** 3+ to relevant cluster pages. Anchor text is descriptive ("CI migration playbook"), never "click here."
6. **External links:** 1+ to a high-authority source (industry report, primary research, spec doc). Never link to a direct competitor.
7. **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 ``.

### 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:

- [ ] Seed keyword appears in title, meta, H1, and first 100 words of the body.
- [ ] Every related query has an assigned intent.
- [ ] Title ≤60 chars, meta ≤155 chars.
- [ ] Exactly one H1 suggested.
- [ ] H2/H3 hierarchy has no skipped levels.
- [ ] At least 3 internal links with descriptive anchors.
- [ ] At least 1 external link to a non-competitor authority source.
- [ ] Every image in the draft has a proposed alt text.
- [ ] Schema block is valid JSON-LD.
- [ ] Core Web Vitals checklist included.
- [ ] Gap note identifies at least 2 missing elements vs top SERP competitors.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tahirraufkeeyu](https://github.com/tahirraufkeeyu)
- **Source:** [tahirraufkeeyu/software-development-agent-stack--sdas](https://github.com/tahirraufkeeyu/software-development-agent-stack--sdas)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tahirraufkeeyu-software-development-agent-stack-sdas-seo-optimizer
- Seller: https://agentstack.voostack.com/s/tahirraufkeeyu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.