---
name: seo-content-optimizer
description: "Audit pages for on-page SEO, write schema JSON-LD, and generate meta tags that actually rank. Runs a structured audit, scores readability, fixes title/meta, writes JSON-LD for Article / FAQ / HowTo, and outputs an internal linking plan."
license: MIT
---

# SEO Content Optimizer

A skill for shipping pages that pass an on-page SEO review before they go live. It runs a structured audit against a single URL or a local HTML/Markdown file, rewrites titles and meta descriptions to fit pixel/character limits, emits valid schema.org JSON-LD, and hands back a prioritized internal linking plan. Built for content engineers, technical writers, and marketers who edit pages in a repo rather than a CMS dashboard.

## When to use it

- You drafted a blog post or landing page and want a pre-publish on-page check.
- A page ranks on page 2 and you need concrete fixes, not a vague "improve content" note.
- You're adding Article, FAQPage, or HowTo rich results and want JSON-LD that validates.
- You're auditing an existing site section and need an internal linking map across related URLs.

## What it does

The audit walks the page and reports on each lever: title tag length and keyword placement, meta description, a single H1, heading hierarchy (no skipped levels), image `alt` coverage, canonical tag, and Open Graph / Twitter Card presence. Readability is scored with Flesch Reading Ease plus average sentence and paragraph length, flagging passages above grade target.

For structured data it generates JSON-LD blocks for `Article` (headline, author, datePublished, image), `FAQPage` (question/answer pairs pulled from the content), and `HowTo` (ordered steps). Output is plain `<script type="application/ld+json">` you paste into `<head>`, shaped to pass Google's Rich Results Test.

The linking plan groups your supplied pages by topical cluster and suggests anchor text plus source→target pairs, surfacing orphan pages with no inbound links.

## Usage

```
curl -fsSL --create-dirs -o ~/.claude/skills/seo-content-optimizer/SKILL.md https://claudeskil.com/skills/seo-content-optimizer/SKILL.md

# audit a live page against a target query
> audit https://example.com/blog/cold-brew for "cold brew ratio"

# generate FAQ + Article JSON-LD from a local file
> write Article and FAQ JSON-LD for ./content/cold-brew.md

# build a linking plan across a folder
> internal linking plan for the URLs in ./sitemap-blog.txt
```

The skill returns the rewritten title/meta inline, JSON-LD ready to paste, and a table of link suggestions.

## Tips & gotchas

- Titles are scored by pixel width (~580px desktop), not just character count — a 58-char title with wide caps can still truncate.
- FAQ JSON-LD must mirror visible on-page Q&A. Don't inject answers that aren't in the rendered HTML, or you risk a manual action.
- Provide the target keyword explicitly; without it the audit scores structure but can't judge intent match or keyword placement.
- For SPA pages, give the rendered HTML or a prerendered URL — the audit reads markup, not post-hydration DOM.

## FAQ

**Does it crawl my whole site?** No. It works one page at a time; the linking plan operates over a list of URLs you supply.

**Will the JSON-LD validate?** It's structured to pass Rich Results Test, but always paste the final block in and confirm there, since required fields vary by content.

**Can it write new content?** It rewrites titles, metas, and schema, and flags thin or hard-to-read sections — it audits and edits rather than ghostwriting whole articles.