Claude-seo-skills seo-markdown-audit

install

source · Clone the upstream repo

git clone https://github.com/lionkiii/claude-seo-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/lionkiii/claude-seo-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/seo-markdown-audit" ~/.claude/skills/lionkiii-claude-seo-skills-seo-markdown-audit && rm -rf "$T"

manifest: skills/seo-markdown-audit/SKILL.md

source content

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

7. Link Analysis

Find all
```
[text](url)
```
patterns
Flag generic anchor text: "here", "click here", "this link", "read more", "link"
Count internal links (relative paths starting with
```
/
```
or
```
./
```
or
```
../
```
) — warn if zero
Count external links — note if zero (no external references can hurt E-E-A-T)

8. Image Analysis

Find all
```
![alt](url)
```
patterns
Flag empty alt text:
```
![](url)
```
Flag generic alt text: "image", "photo", "screenshot", "picture", "img"
Note total image count — warn if zero for content >500 words

9. Frontmatter Completeness

Check for YAML frontmatter presence (between
```
---
```
markers at top of file)
Required fields:
```
title
```
(flag if missing),
```
description
```
(flag if missing)
Recommended fields:
```
date
```
,
```
author
```
,
```
tags
```
/
```
categories
```
Check
```
title
```
length — warn if >60 chars

10. Technical Issues

Check for broken markdown syntax: unclosed links
```
[text](
```
, unclosed images
```
![alt](
```
Check for raw HTML (not recommended in markdown for SEO — search engines may not parse consistently)
Check for consecutive blank lines >2 (formatting issue)

11. Markdown Syntax Quality Per Markdown Guide (https://www.markdownguide.org/) syntax best practices:

Space after heading hash: flag
```
#Heading
```
(missing space after
```
#
```
) — correct:
```
# Heading
```
Consistent list delimiters: flag mixed
```
-
```
and
```
*
```
within the same list block — pick one delimiter and use it consistently throughout
Blank lines before/after headings: flag any heading that does not have a blank line above it (except the very first line of the file)
Blank lines before/after code blocks: flag fenced code blocks (
```
```
```
) that do not have a blank line immediately before and after them
Ordered list numbering: warn if ordered lists do not start at
```
1
```
(e.g., starting at
```
3
```
) — most Markdown renderers accept any number but starting at 1 is the standard

Output Format

## Markdown SEO Audit: [filename]

**Overall Score: X/11** (count of categories with no critical/high issues)

### Critical Issues
- [List of critical issues with line numbers if possible]

### High Priority
- [Issues that significantly impact SEO]

### Medium Priority
- [Optimization opportunities]

### Low Priority / Suggestions
- [Nice-to-have improvements]

### Summary
| Check | Status | Notes |
|-------|--------|-------|
| Title/H1 | PASS/WARN/FAIL | [brief note] |
| Meta Description | PASS/WARN/FAIL | [brief note] |
| Heading Hierarchy | PASS/WARN/FAIL | [brief note] |
| Keyword Placement | PASS/WARN/FAIL | [brief note] |
| Content Length | PASS/WARN/FAIL | [word count] |
| Readability | PASS/WARN/FAIL | [avg sentence length] |
| Links | PASS/WARN/FAIL | [internal/external count] |
| Images | PASS/WARN/FAIL | [count, alt text status] |
| Frontmatter | PASS/WARN/FAIL | [fields present/missing] |
| Technical | PASS/WARN/FAIL | [issues found] |
| Markdown Syntax | PASS/WARN/FAIL | [issues found] |