Marketplace for trusted AI agent skills

Build a Skill That Writes SEO-Optimized Blog Posts Automatically

You have an agent that can write. You have a blog that needs content. The missing piece is a skill that bridges the gap — one that encodes your SEO standards, keyword patterns, and content structure so the agent produces publish-ready posts without hand-holding.

This tutorial walks through building that skill from scratch. By the end, you’ll have a working seo-content-writer skill that handles keyword placement, heading hierarchy, meta description generation, internal linking, and all the structural SEO work that separates content that ranks from content that sits on page four.

This guide is for developers and content teams already using Claude Code or OpenClaw who want to automate their content pipeline. You’ll need basic familiarity with SKILL.md file structure — if you haven’t built a skill before, start there.

Table of Contents

Why a Dedicated SEO Writing Skill?

Claude already knows what SEO is. It can write blog posts. So why build a skill for this?

Because knowing what SEO is and consistently applying your specific SEO standards are different things. Without a skill, you’ll find yourself repeating the same instructions every session: “Remember to put the keyword in the first 100 words. Don’t forget the meta description. Use H2s for secondary keywords. Add an FAQ section.” That’s exactly the kind of repetitive, context-dependent instruction that skills exist to encode.

A well-built SEO writing skill gives you three things:

  • Consistency — every post follows the same structural standards, whether you’re writing it at 9 AM or your agent is generating it from a cron job at midnight
  • Institutional knowledge — your keyword strategy, internal linking patterns, and content guidelines live in files, not in someone’s head
  • Token efficiency — instead of burning 500+ tokens on SEO instructions every time, the agent loads them once from the skill and gets to work

The best practices from Anthropic’s Thariq apply directly here: this skill contains information that pushes the model out of its default patterns. Left to its own devices, Claude writes perfectly acceptable content. With this skill, it writes content that follows your SEO playbook.

Project Setup and File Structure

Create the skill directory with progressive disclosure in mind. The SKILL.md stays focused on core workflow; heavy reference material lives in separate files.

seo-content-writer/
├── SKILL.md                      # Core instructions (~300 lines)
├── config.json                   # Site-specific settings
├── references/
│   ├── keyword-placement.md      # Where and how to place keywords
│   ├── content-templates.md      # Structures for different post types
│   ├── title-formulas.md         # Proven headline patterns
│   └── seo-checklist.md          # Pre-publish verification list
├── scripts/
│   └── validate-seo.sh           # Automated check script (optional)
└── examples/
    ├── tutorial-post.md          # Example tutorial output
    └── comparison-post.md        # Example comparison output

This structure keeps your core SKILL.md lean. When Claude needs the full keyword placement guide, it reads references/keyword-placement.md. When it needs a template for a comparison article, it pulls references/content-templates.md. The rest of the time, those tokens stay available for the actual writing.

Initialize the directory:

mkdir -p seo-content-writer/{references,scripts,examples}

Writing the Core SKILL.md

The SKILL.md is the brain of your skill. It needs four sections: frontmatter, core workflow, the gotchas, and pointers to reference files. Here’s the complete file:

---
name: seo-content-writer
description: >
  Use when the user asks to "write a blog post", "create SEO content",
  "draft an article", "write content for the blog", or "publish a post".
  Also triggers on: "content calendar", "keyword-optimized article",
  "meta description", "blog post about [topic]". NOT for: editing existing
  published posts (use content-refresher), technical SEO audits (use
  technical-seo-checker), or keyword research (use keyword-research).
version: "1.0.0"
---

# SEO Content Writer

Write SEO-optimized blog posts that follow our content standards.

## Core Workflow

When asked to write a blog post:

1. **Confirm requirements** — get the topic, primary keyword, secondary
   keywords (2-4), target word count, and content type (tutorial, guide,
   comparison, listicle, news, spotlight).

2. **Load the right template** — read `references/content-templates.md`
   for the matching content type structure.

3. **Write the title** — read `references/title-formulas.md` for patterns.
   Title must: include the primary keyword, stay under 60 characters,
   and avoid clickbait.

4. **Write the meta description** — 150-160 characters, include primary
   keyword, include a value proposition. No calls to "discover" or
   "unlock" or "dive into".

5. **Write the content** following these rules:
   - Primary keyword in the first 100 words (naturally, not forced)
   - Primary keyword in at least one H2
   - Primary keyword in the conclusion
   - Secondary keywords in H2s and H3s
   - Paragraphs of 2-4 sentences maximum
   - At least one code example if the topic is technical
   - At least 2 internal links to other site pages
   - At least 2 external links to authoritative sources
   - FAQ section with 3-4 questions

6. **Run the checklist** — read `references/seo-checklist.md` and verify
   every item before returning the final content.

## Keyword Placement

For detailed keyword placement rules, read `references/keyword-placement.md`.

Quick reference:
- **H1**: primary keyword (only one H1 per post)
- **First paragraph**: primary keyword within first 100 words
- **H2s**: mix of primary and secondary keywords
- **H3s**: secondary and long-tail keywords
- **Conclusion**: primary keyword, naturally restated
- **Meta description**: primary keyword, front-loaded if possible
- **URL slug**: primary keyword, hyphenated

## Gotchas

[See full gotchas section below — this is where the real value lives]

## Output Format

Return the post as WordPress-ready HTML:
- Use <h2> and <h3> tags (never <h1> — WordPress adds that from the title)
- Use <p>, <ul>, <ol>, <pre><code> tags
- Links use target="_blank" rel="noopener" for external
- Internal links are relative paths or full site URLs
- Include the meta description in an HTML comment at the top

A few things to notice about this structure. The description field is detailed and includes explicit trigger phrases — this is what Thariq emphasized as critical for skill activation. The workflow is goal-oriented, not rigidly scripted. And the heavy reference material (templates, formulas, checklists) lives in separate files that get loaded only when needed.

Building the References Directory

The references directory is where progressive disclosure pays off. Each file handles one specific concern so Claude can load exactly what it needs.

references/keyword-placement.md

This file encodes your keyword density and placement rules. Here’s a practical version:

# Keyword Placement Guide

## Placement Map

| Location         | Keyword Type | Required | Notes                              |
|-----------------|-------------|----------|------------------------------------|
| Title (H1)      | Primary     | Yes      | Front-load when natural            |
| URL slug         | Primary     | Yes      | Hyphenated, no stop words          |
| Meta description | Primary     | Yes      | Within first 80 chars if possible  |
| First paragraph  | Primary     | Yes      | Within first 100 words             |
| H2 headings      | Mixed       | Yes      | Primary in 1-2, secondary in rest  |
| H3 headings      | Secondary   | No       | Use for long-tail variants         |
| Image alt text   | Primary     | Yes      | If featured image exists           |
| Conclusion       | Primary     | Yes      | Natural restatement                |

## Density Guidelines

- Primary keyword: 0.8-1.5% density (roughly 8-15 mentions per 1000 words)
- Don't force it. If a sentence reads awkwardly with the keyword, rewrite
  the sentence or skip that instance.
- Use semantic variants: "agent skills" → "skills for agents",
  "skill creation", "building skills"
- Never repeat the exact keyword in consecutive sentences.

references/content-templates.md

Different content types need different structures. This file gives Claude a skeleton for each:

# Content Structure Templates

## Tutorial Post
1. Introduction: what you'll build + who this is for (100-150 words)
2. Prerequisites / what you need
3. Step-by-step sections (each step = one H2)
4. Testing / verification section
5. Common issues / troubleshooting
6. FAQ (3-4 questions)
7. Conclusion with next steps

## Comparison Post
1. Introduction: what you're comparing and why (100-150 words)
2. Quick comparison table (feature matrix)
3. Detailed section for Option A
4. Detailed section for Option B
5. When to use each (decision framework)
6. FAQ (3-4 questions)
7. Conclusion with recommendation

## Listicle
1. Introduction: what the list covers and selection criteria
2. One H2 per list item (numbered in heading)
3. Each item: 100-200 words, what it does, why it matters
4. FAQ (3-4 questions)
5. Conclusion with "start here" recommendation

## News/Analysis
1. The news: what happened (lead paragraph)
2. Why it matters (context and impact)
3. What it means for [audience]
4. Expert reactions or data points
5. What to expect next
6. FAQ if relevant

references/seo-checklist.md

This is the pre-publish gate. Every post must clear it:

# SEO Pre-Publish Checklist

## Required (post fails without these)
- [ ] Title contains primary keyword and is under 60 characters
- [ ] Meta description is 150-160 characters with primary keyword
- [ ] H1 is set (from title) and contains primary keyword
- [ ] Primary keyword appears in first 100 words
- [ ] At least one H2 contains primary keyword
- [ ] URL slug contains primary keyword (hyphenated, no stop words)
- [ ] At least 2 internal links to other site pages
- [ ] At least 2 external links to authoritative sources
- [ ] FAQ section with 3+ questions
- [ ] Conclusion restates primary keyword

## Recommended
- [ ] Featured image with alt text containing primary keyword
- [ ] Table of contents for posts over 1200 words
- [ ] At least one code example for technical topics
- [ ] Paragraphs under 4 sentences
- [ ] No orphan H3s (every H3 has a parent H2)
- [ ] Word count within target range

The Gotchas Section: SEO-Specific Failure Modes

This is the section that separates a useful skill from a mediocre one. These gotchas come from real failures — posts that looked fine but performed poorly, or content that broke SEO rules in subtle ways.

Add this to your SKILL.md:

## Gotchas

### Keyword Stuffing in Headings
Claude tends to put the primary keyword in EVERY H2. Don't. Use the
primary keyword in 1-2 H2s maximum. Other H2s should use secondary
keywords or natural phrasing. Google penalizes over-optimized heading
structures.

### The "Introduction to" Title Pattern
Claude defaults to titles like "Introduction to X" or "A Guide to X".
These are weak for CTR. Read `references/title-formulas.md` for
patterns that actually get clicks.

### Meta Descriptions That Are Too Short
Claude often generates meta descriptions of 100-120 characters. This
wastes SERP real estate. Always hit 150-160 characters. If the first
draft is short, add a value proposition or specificity.

### Orphaned Internal Links
Don't link to pages that don't exist yet. Verify every internal link
target is a real, published page on the site. Broken internal links
hurt crawl efficiency and user experience.

### Missing Semantic Variants
Using the exact same keyword phrase every time sounds robotic to both
readers and search engines. After the first 2-3 uses of the exact
primary keyword, switch to semantic variants. "Build an agent skill"
→ "create a skill for your agent" → "skill development."

### FAQ Answers That Are Too Long
FAQ answers targeting featured snippets should be 40-60 words. Claude
tends to write 150+ word answers. Keep them concise — the full
explanation belongs in the body content, not the FAQ.

### Forgetting the CTA
Every post needs a call to action in the conclusion. Not a generic
"subscribe to our newsletter" — a specific next step related to the
post topic. "Install the skill from ASE" or "Try building your own
using this template."

### HTML Entity Issues in WordPress
When writing <pre><code> blocks for WordPress, angle brackets
inside code must be HTML-encoded (&lt; and &gt;). If you output
raw < and > inside code blocks, WordPress will interpret them as
HTML tags and break the formatting.

Each of these gotchas addresses a specific failure mode with a concrete correction. This is the pattern Thariq identified as the highest-signal content in any skill. Over time, you’ll add more entries as you discover new failure patterns in your generated content.

Making It Portable with config.json

Your SEO skill shouldn’t hardcode your site’s URL, categories, or brand voice. That information belongs in config.json:

{
  "site_url": "https://example.com",
  "blog_path": "/blog/",
  "default_author": "Editorial Team",
  "brand_voice": "Professional but conversational. No jargon without explanation.",
  "categories": {
    "tutorials": 45,
    "guides": 48,
    "comparisons": 46,
    "news": 47,
    "best-practices": 43,
    "spotlights": 49,
    "deep-dives": 44
  },
  "internal_link_targets": [
    "/build-your-first-agent-skill-in-15-minutes/",
    "/how-to-write-agent-skills-that-actually-work/",
    "/top-10-agent-skills-every-developer-should-install/",
    "/mcp-vs-agent-skills-whats-the-difference/"
  ],
  "seo_defaults": {
    "min_word_count": 1200,
    "max_word_count": 2000,
    "min_internal_links": 2,
    "min_external_links": 2,
    "meta_description_min": 150,
    "meta_description_max": 160
  }
}

When someone else installs this skill, they update config.json with their site’s details. The SKILL.md references these values: “Link to pages listed in config.json → internal_link_targets” rather than hardcoding specific URLs. This makes the skill reusable across different blogs, teams, and content operations.

For a content team running multiple sites, you could even maintain separate config files per site and pass the target as a parameter.

Testing and Iterating

A skill isn’t done when it’s written. It’s done when it reliably produces good output across different inputs. Here’s how to test your SEO writing skill:

Test 1: Basic Generation

Ask Claude to write a blog post using a simple prompt:

Write a blog post about "how to use environment variables in agent skills"
targeting the keyword "agent skill environment variables"

Check: Did it follow the template structure? Did keyword placement match the rules? Is the meta description the right length?

Test 2: Content Type Switching

Request different content types to verify the templates work:

Write a comparison post: "MCP Servers vs Agent Skills for API Integration"
Write a listicle: "7 Agent Skills That Automate DevOps Workflows"

Check: Did it load and follow the correct template from references/content-templates.md?

Test 3: Gotchas Verification

Deliberately trigger the failure modes listed in your gotchas section. Give it a prompt that would normally cause keyword stuffing, short meta descriptions, or over-long FAQ answers. The skill should prevent these issues.

Test 4: Config Portability

Change the config.json to a different site’s values and regenerate. The output should use the new URLs, categories, and brand voice without any changes to SKILL.md.

Iterating from Results

After each test, update the skill:

  • New failure mode? Add it to the Gotchas section.
  • Template structure not working for a content type? Revise references/content-templates.md.
  • Keyword placement feels unnatural? Adjust the density guidelines in references/keyword-placement.md.

Anthropic’s Skill Creator tool can help with systematic testing if you want to measure skill performance across multiple runs. It tracks metrics like instruction adherence and output quality, which is particularly useful for content skills where “good” is somewhat subjective.

Frequently Asked Questions

Can this skill handle content in languages other than English?

The skill structure is language-agnostic. Keyword placement rules, heading hierarchy, and meta description lengths work across languages. You’d need to adjust references/title-formulas.md for language-specific headline patterns and update config.json with localized categories. The gotchas section might need additions for language-specific SEO quirks (e.g., longer compound words in German affecting title length).

How does this differ from just prompting Claude with SEO instructions each time?

Three ways. First, consistency — the skill applies the same standards every time without you remembering to include them. Second, token efficiency — reference files load on demand instead of you pasting 2,000 words of instructions into every prompt. Third, iteration — when you discover a new failure mode, you add one gotcha entry and it’s fixed for every future post. With manual prompting, you’d have to remember to include that fix every time.

What’s the minimum viable version of this skill?

A SKILL.md with the description field, the core workflow (6 steps), and at least 3-4 gotchas. Skip the references directory for v1 and put everything in SKILL.md. Once the file passes 300 lines, refactor into references/. Start simple, add complexity when the simple version shows gaps.

Should I include the actual content of reference files in SKILL.md?

No. The whole point of progressive disclosure is that reference files load only when needed. Your SKILL.md should say “read references/keyword-placement.md for detailed placement rules” — not copy those rules into SKILL.md itself. This keeps your core file lean and your context window available for the actual writing work.

Putting It All Together

You now have the complete architecture for an SEO content writing skill: a focused SKILL.md with workflow and gotchas, reference files for templates and checklists, a portable config.json, and a testing strategy.

The pattern here generalizes beyond SEO writing. Any content-generation skill benefits from the same structure: core workflow in SKILL.md, domain-specific rules in references/, user-specific configuration in config.json, and a gotchas section that grows from real failures.

If you build this skill and want to share it, submit it to AgentSkillExchange. Check the existing popular skills for quality benchmarks. And if you hit failure modes we didn’t cover, that’s a gotcha worth adding — and worth sharing with the community.