seo-markdown-audit

Markdown SEO Audit

Analyzes a local markdown file for SEO issues before publishing. No MCP connection required.

Inputs

• path: Absolute path to the markdown file to audit. If the user provides a relative path, resolve it using Bash: realpath <path> before calling Read. If the user provides a directory, use Glob: **/*.md to find all markdown files and let the user choose.

Execution

@skills/seo/references/markdown-guide.md

Use the Read tool to load the file content, then run these 11 check categories:

1. Title / H1 Check

• Count lines starting with # (H1) — flag if 0 or >1
• Check H1 character length — warn if >60 chars (Google truncates around 60)
• Extract primary keyword from H1 for use in other checks

2. Meta Description (Frontmatter)

• If YAML frontmatter exists (between --- markers), check for description field
• Flag if missing, warn if <120 chars or >160 chars (optimal: 150-160)
• Check if description contains the primary keyword from H1

3. Heading Hierarchy

• Verify headings follow proper nesting: H1 → H2 → H3 (no H3 before first H2, no skipped levels)
• Flag duplicate heading text (exact same heading appearing twice)
• Warn if no H2 headings exist (flat content with no structure)

4. Keyword Placement

• Extract primary keyword from H1 (longest noun phrase or first 3 meaningful words)
• Check if keyword appears in first 100 words of body content (after H1)
• Check if keyword appears in at least one H2
• Do NOT calculate keyword density percentage (outdated SEO practice)

5. Content Length

• Count words (split on whitespace, exclude frontmatter and code blocks)
• Flag CRITICAL if <300 words
• Warn if <800 words (thin content for most topics)
• Note if >3,000 words (consider splitting into pillar + sub-pages)

6. Readability

• Calculate average sentence length (split on ., !, ?)
• Warn if average >25 words per sentence (too complex for most audiences)
• Flag paragraphs >5 sentences without a subheading break