Build an AI SEO Agent That Analyzes and Updates Your Blog

mkdir seo-agent && cd seo-agent
pip install anthropic python-frontmatter rich

import os
import glob
import frontmatter  # reads YAML front matter + body
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
POSTS_DIR = "../your-hugo-site/content/posts"

def audit_post(post_path: str) -> dict:
    """
    Returns a dict with the post metadata and a list of SEO issues.
    """
    post = frontmatter.load(post_path)
    issues = []

    title = post.get("title", "")
    description = post.get("description", "")
    content = post.content[:2000]  # First 2000 chars is enough for Claude to assess

    # Rule-based checks (fast, no API call needed)
    if len(title) > 60:
        issues.append(f"Title is {len(title)} chars — trim to 50-60")
    if len(description) > 160:
        issues.append(f"Description is {len(description)} chars — trim to 140-160")
    if len(description) < 100:
        issues.append("Description too short — expand to 140-160 chars")
    if not any(kw.lower() in content.lower() for kw in post.get("keywords", [])):
        issues.append("Primary keyword not found in first 2000 chars of content")

    return {
        "path": post_path,
        "title": title,
        "description": description,
        "keywords": post.get("keywords", []),
        "content_preview": content,
        "issues": issues,
        "post": post,
    }

def fix_post_seo(audit: dict) -> dict:
    """
    Sends the audit to Claude, gets back corrected front matter fields.
    Returns only the fields that need updating.
    """
    if not audit["issues"]:
        return {}  # Nothing to fix

    prompt = f"""You are an SEO specialist. Fix the following Hugo blog post metadata.

CURRENT TITLE: {audit["title"]}
CURRENT DESCRIPTION: {audit["description"]}
KEYWORDS: {", ".join(audit["keywords"])}
ISSUES FOUND: {chr(10).join(f"- {i}" for i in audit["issues"])}

CONTENT PREVIEW:
{audit["content_preview"]}

Return ONLY a JSON object with the corrected fields. Example:
{{
  "title": "Fixed title here",
  "description": "Fixed description here"
}}

Rules:
- Title must be 50-60 characters
- Description must be 140-160 characters  
- Include the primary keyword naturally in both
- Do not change fields that have no issues
- Return valid JSON only, no markdown, no explanation"""

    response = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=500,
        messages=[{"role": "user", "content": prompt}],
    )

    import json
    text = response.content[0].text.strip()
    return json.loads(text)

def apply_fixes(audit: dict, fixes: dict, dry_run: bool = True) -> None:
    """
    Writes corrected front matter back to the markdown file.
    dry_run=True prints changes without saving.
    """
    if not fixes:
        print(f"✓ No changes needed: {audit['path']}")
        return

    post = audit["post"]

    print(f"\n📝 {audit['path']}")
    for key, new_val in fixes.items():
        old_val = post.get(key, "")
        print(f"  {key}:")
        print(f"    Before: {old_val}")
        print(f"    After:  {new_val}")
        if not dry_run:
            post[key] = new_val

    if not dry_run:
        with open(audit["path"], "wb") as f:
            frontmatter.dump(post, f)
        print(f"  ✅ Saved")
    else:
        print(f"  [DRY RUN — not saved]")

def run_agent(posts_dir: str, dry_run: bool = True, limit: int = 10):
    """
    Audits and fixes up to `limit` posts in posts_dir.
    """
    paths = glob.glob(f"{posts_dir}/**/*.md", recursive=True)[:limit]
    print(f"Found {len(paths)} posts to process\n")

    for path in paths:
        audit = audit_post(path)

        if audit["issues"]:
            print(f"⚠️  Issues in: {path}")
            for issue in audit["issues"]:
                print(f"   - {issue}")
            fixes = fix_post_seo(audit)
            apply_fixes(audit, fixes, dry_run=dry_run)
        else:
            print(f"✓ Clean: {path}")

if __name__ == "__main__":
    run_agent(POSTS_DIR, dry_run=True, limit=5)

# Dry run first — safe to run anytime
python agent.py

# When output looks right, apply fixes
python agent.py --apply  # add argparse or just flip dry_run=False

# .github/workflows/seo-audit.yml
- name: Run SEO Agent
  run: python agent.py --output report.json
- name: Open PR with fixes
  uses: peter-evans/create-pull-request@v6