SEO Optimizer Skill

Operator Context

Hardcoded Behaviors (Always Apply)

• CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
• Voice Preservation: Never suggest changes that compromise the author's authentic tone
• No Keyword Stuffing: Never recommend keyword density above 2.5%
• Honest Descriptions: Meta descriptions must accurately reflect content — no clickbait
• Preview Before Modify: Always show current vs suggested changes before applying modifications
• Over-Engineering Prevention: Focus on high-impact SEO changes only; skip marginal optimizations

Default Behaviors (ON unless disabled)

• Complete Analysis: Show all findings with data, never summarize without evidence
• Alternative Generation: Provide 3 title alternatives using different title patterns
• Internal Link Discovery: Scan related posts for linking opportunities
• Confirmation Required: Require explicit user confirmation before modifying any file

Optional Behaviors (OFF unless enabled)

• Auto-Apply: Apply changes without confirmation (requires explicit --apply flag)
• Batch Mode: Analyze multiple posts at once (requires explicit --batch flag)
• Generate Missing: Create meta descriptions for posts that lack them

What This Skill CAN Do

• Analyze keyword placement across title, headers, first paragraph, and body
• Calculate keyword density and flag over-optimization
• Evaluate title length, specificity, and click potential
• Generate or improve meta descriptions within 150-160 character targets
• Audit header hierarchy (H1/H2/H3 structure and nesting)
• Identify internal linking opportunities to related posts
• Show before/after comparisons for all proposed changes

What This Skill CANNOT Do

• Modify post body content beyond front matter and headers — voice belongs to the author
• Guarantee search rankings — SEO is one factor among many
• Replace human judgment on content quality or brand fit
• Auto-publish changes without explicit user review and confirmation
• Handle site-wide technical SEO (robots.txt, sitemap, redirects)

Instructions

Phase 1: ASSESS — Analyze Current SEO State

• Title from front matter
• Existing description/summary (if any)
• All headers (H2, H3, etc.) and their hierarchy
• First paragraph content (first 100 words)
• Full body text for keyword analysis

1. Most repeated relevant phrase (excluding stop words)
2. Topic implied by the title
3. Technical term most central to the content

Primary keyword: "hugo debugging"
Secondary keywords: "template errors", "build failures", "hugo troubleshooting"

Density = (keyword occurrences / total words) * 100
Target: 1-2%  |  Warning: > 2.5%  |  Critical: > 3%

• Identify relevant anchor text in current post
• Note the link target
• Flag if current post is an orphan (zero inbound links)

Phase 2: DECIDE — Prioritize Changes

1. Add or fix meta description
2. Optimize title if needed
3. Add internal links
4. Adjust headers only if clearly beneficial

Phase 3: APPLY — Present Recommendations and Execute

===============================================================
 SEO ANALYSIS: {file_path}
===============================================================

 CURRENT STATE:

 Title: "{current_title}" ({char_count} chars)
   {assessment}

 Description: "{current_description}" or "(missing)"
   {assessment}

 Primary Keyword: "{keyword}"
   - In title: yes/no
   - In H2s: {count} of {total}
   - In first paragraph: yes/no
   - Density: {percentage}%

 Headers: H2({count}), H3({count})
   {assessment}

 Internal Links: {count}
   {assessment}

===============================================================
 SUGGESTIONS:

 Title (pick one):
   1. "{alternative_1}" ({chars} chars) — [pattern used]
   2. "{alternative_2}" ({chars} chars) — [pattern used]
   3. "{alternative_3}" ({chars} chars) — [pattern used]

 Description:
   "{generated_description}" ({chars} chars)

 Internal Links:
   - Link "{anchor_text}" -> {target_post}

 Keyword Improvements:
   - {specific_suggestion}

===============================================================
 Apply changes? [preview / apply / skip]
===============================================================

• preview: Show exact diff of all proposed front matter and content changes
• apply: Make changes to front matter fields and insert internal links
• skip: Exit without changes

• title

  in front matter (if user selected an alternative)

• description

  in front matter (add or update)

• summary

  in front matter (sync with description for Hugo/PaperMod)
• Internal link insertions at suggested anchor points

Phase 4: VERIFY — Confirm Changes Are Valid

hugo --quiet

git checkout {file_path}

Error Handling

Error: "Post File Not Found"

1. List available posts in the content directory
2. Present candidates to user
3. Ask user to specify correct filename

Error: "Hugo Build Failed After Changes"

1. Revert changes with

   git checkout {file_path}

2. Show the Hugo error output
3. Identify which specific change caused the failure
4. Re-apply changes individually to isolate the problem

Error: "Keyword Density Exceeds Threshold"

1. Do not add any changes that increase keyword frequency
2. Suggest removing redundant keyword occurrences instead
3. Focus recommendations on structural improvements (title, description, links)

Anti-Patterns

Anti-Pattern 1: Keyword Stuffing

Anti-Pattern 2: Clickbait Titles

references/title-patterns.md

Anti-Pattern 3: Generic Meta Descriptions

Anti-Pattern 4: Forcing Changes on Good Structure

Anti-Pattern 5: Optimizing Without Data

References

• Anti-Rationalization — Prevents shortcut rationalizations
• Verification Checklist — Pre-completion checks

Domain-Specific Anti-Rationalization

Reference Files

• ${CLAUDE_SKILL_DIR}/references/seo-guidelines.md

  : Length requirements, density targets, and best practices

• ${CLAUDE_SKILL_DIR}/references/keyword-placement.md

  : Priority locations and placement techniques

• ${CLAUDE_SKILL_DIR}/references/title-patterns.md

  : Effective title structures for technical blogs