SEO Machine

A specialized Claude Code workspace for creating long-form, SEO-optimized blog content for any business. This system helps you research, write, analyze, and optimize content that ranks well and serves your target audience.

Overview

SEO Machine is built on Claude Code and provides:

• Custom Commands: /research, /write, /rewrite, /analyze-existing, /optimize, /performance-review, /publish-draft, /article, /priorities, plus specialized research and landing page commands
• Specialized Agents: Content analyzer, SEO optimization, meta element creation, internal linking, keyword mapping, editor, performance analysis, headline generator, CRO analyst, landing page optimizer
• Marketing Skills: 26 marketing skills for copywriting, CRO, A/B testing, email sequences, pricing strategy, and more
• Advanced SEO Analysis: Search intent detection, keyword density & clustering, content length comparison, readability scoring, SEO quality rating (0-100)
• Data Integrations: Google Analytics 4, Google Search Console, DataForSEO for real-time performance insights
• Context-Driven: Brand voice, style guide, SEO guidelines, and examples guide all content
• Workflow Organization: Structured directories for topics, research, drafts, and published content

Getting Started

Prerequisites

• Claude Code installed
• Anthropic API account

Installation

1. Clone this repository:

git clone https://github.com/TheCraigHewitt/seomachine.git
cd seomachine

2. Install Python dependencies for analysis modules:

pip install -r data_sources/requirements.txt

This installs:

• Google Analytics/Search Console integrations
• DataForSEO API client
• NLP libraries (nltk, textstat)
• Machine learning (scikit-learn)
• Web scraping tools (beautifulsoup4)

3. Open in Claude Code:

claude-code .

4. Customize Context Files (Important!):

   All context files are provided as templates. Fill them out with your company's information:

   • context/brand-voice.md - Define your brand voice and messaging (see examples/castos/ for reference)
   • context/writing-examples.md - Add 3-5 exemplary blog posts from your site
   • context/features.md - List your product/service features and benefits
   • context/internal-links-map.md - Map your key pages for internal linking
   • context/style-guide.md - Fill in your style preferences
   • context/target-keywords.md - Add your keyword research and topic clusters
   • context/competitor-analysis.md - Add competitor analysis and insights
   • context/seo-guidelines.md - Review and adjust SEO requirements

   Quick Start: Check out examples/castos/ to see a complete real-world example of all context files filled out for a podcast hosting SaaS company.

Workflows

Creating New Content

1. Start with Research

/research [topic]

What it does:

• Performs keyword research
• Analyzes top 10 competitors
• Identifies content gaps
• Creates comprehensive research brief
• Saves to /research/ directory

Example:

/research content marketing strategies for B2B SaaS

2. Write the Article

/write [topic or research brief]

What it does:

• Creates 2000-3000+ word SEO-optimized article
• Maintains your brand voice from context/brand-voice.md
• Integrates keywords naturally
• Includes internal and external links
• Provides meta elements (title, description, keywords)
• Automatically triggers optimization agents
• Saves to /drafts/ directory

Example:

/write content marketing strategies for B2B SaaS

Agent Auto-Execution: After writing, these agents automatically analyze the content:

• SEO Optimizer: On-page SEO recommendations
• Meta Creator: Multiple meta title/description options
• Internal Linker: Specific internal linking suggestions
• Keyword Mapper: Keyword placement and density analysis

3. Final Optimization

/optimize [article file]

What it does:

• Comprehensive SEO audit
• Validates all elements meet requirements
• Provides final polish recommendations
• Generates publishing readiness score
• Creates optimization report

Example:

/optimize drafts/content-marketing-strategies-2025-10-29.md

Updating Existing Content

1. Analyze Existing Post

/analyze-existing [URL or file path]

What it does:

• Fetches and analyzes current content
• Evaluates SEO performance
• Identifies outdated information
• Assesses competitive positioning
• Provides content health score (0-100)
• Recommends update priority and scope
• Saves analysis to /research/ directory

Examples:

/analyze-existing https://yoursite.com/blog/marketing-guide
/analyze-existing published/marketing-guide-2024-01-15.md

2. Rewrite/Update Content

/rewrite [topic or analysis file]

What it does:

• Updates content based on analysis findings
• Refreshes statistics and examples
• Improves SEO optimization
• Adds new sections to fill gaps
• Maintains what works from original
• Tracks changes made
• Saves to /rewrites/ directory

Example:

/rewrite marketing guide

Commands Reference

/research [topic]

Comprehensive keyword and competitive research for new content.

Output: Research brief in /research/brief-[topic]-[date].md

Includes:

• Primary and secondary keywords
• Competitor analysis (top 10)
• Content gaps and opportunities
• Recommended outline
• Internal linking strategy
• Meta elements preview

---

/write [topic]

Create long-form SEO-optimized article (2000-3000+ words).

Output: Article in /drafts/[topic]-[date].md

Includes:

• Complete article with H1/H2/H3 structure
• SEO-optimized content
• Internal and external links
• Meta elements (title, description, keywords)
• SEO checklist

Auto-Triggers:

• SEO Optimizer agent
• Meta Creator agent
• Internal Linker agent
• Keyword Mapper agent

---

/rewrite [topic]

Update and improve existing content.

Output: Updated article in /rewrites/[topic]-rewrite-[date].md

Includes:

• Rewritten/updated content
• Change summary
• Before/after comparison
• Updated SEO elements

---

/analyze-existing [URL or file]

Analyze existing blog posts for improvement opportunities.

Output: Analysis report in /research/analysis-[topic]-[date].md

Includes:

• Content health score (0-100)
• Quick wins (immediate improvements)
• Strategic improvements
• Rewrite priority and scope
• Research brief for rewrite

---

/optimize [file]

Final SEO optimization pass before publishing.

Output: Optimization report in /drafts/optimization-report-[topic]-[date].md

Includes:

• SEO score (0-100)
• Priority fixes
• Quick wins
• Meta element options
• Link enhancement suggestions
• Publishing readiness assessment

---

/publish-draft [file]

Publish article to WordPress via REST API with Yoast SEO metadata.

---

/article [topic]

Simplified article creation workflow.

---

/priorities

Content prioritization matrix using analytics data to identify highest-impact content tasks.

---

/scrub [file]

Remove AI watermarks and patterns from content (em-dashes, filler phrases, robotic patterns).

---

Research Commands

Command	Description
/research-serp [keyword]	SERP analysis for a target keyword
/research-gaps	Competitor content gap analysis
/research-trending	Trending topic opportunities
/research-performance	Performance-based content priorities
/research-topics	Topic cluster research

---

Landing Page Commands

Command	Description
/landing-write [topic]	Create conversion-optimized landing page
/landing-audit [file]	Audit landing page for CRO issues
/landing-research [topic]	Research competitors and positioning
/landing-competitor [URL]	Deep competitor landing page analysis
/landing-publish [file]	Publish landing page to WordPress

Agents

Specialized agents that automatically analyze content and provide expert recommendations.

Content Analyzer (NEW!)

Purpose: Comprehensive, data-driven content analysis using 5 specialized modules

Analyzes:

• Search intent classification (informational/navigational/transactional/commercial)
• Keyword density and clustering with topic detection
• Content length comparison vs top SERP competitors
• Readability scoring (Flesch Reading Ease, Flesch-Kincaid Grade Level)
• SEO quality rating (0-100 score with category breakdowns)
• Keyword stuffing risk detection
• Passive voice ratio and sentence complexity
• Distribution heatmap showing keyword placement by section

Output:

• Executive summary with publishing readiness assessment
• Priority action plan (critical/high priority/optimization)
• Competitive positioning analysis
• Detailed recommendations for each analysis area
• Exact metrics and benchmarks for improvements

Powered by:

• search_intent_analyzer.py - Search intent detection
• keyword_analyzer.py - Keyword density, clustering, LSI keywords
• content_length_comparator.py - SERP competitor analysis
• readability_scorer.py - Multiple readability metrics
• seo_quality_rater.py - Comprehensive SEO scoring

---

SEO Optimizer

Purpose: On-page SEO analysis and optimization recommendations

Analyzes:

• Keyword optimization and density
• Content structure and headings
• Internal and external links
• Meta elements
• Readability and user experience
• Featured snippet opportunities

Output: SEO score (0-100) with specific improvement recommendations

---

Meta Creator

Purpose: Generate high-converting meta titles and descriptions

Creates:

• 5 meta title variations (50-60 chars)
• 5 meta description variations (150-160 chars)
• Testing recommendations
• SERP preview
• Conversion-optimized copy

Output: Multiple options with recommendation and reasoning

---

Internal Linker

Purpose: Strategic internal linking recommendations

Provides:

• 3-5 specific internal link suggestions
• Exact placement locations
• Anchor text recommendations
• User journey mapping
• SEO impact prediction

References: context/internal-links-map.md

---

Keyword Mapper

Purpose: Keyword placement and integration analysis

Analyzes:

• Keyword density and distribution
• Critical placement checklist
• Natural language integration quality
• LSI keyword coverage
• Cannibalization risk

Output: Distribution map, gap analysis, specific revision suggestions

---

Editor

Purpose: Transform technically accurate content into human-sounding, engaging articles

Analyzes:

• Voice and personality
• Specificity of examples
• Readability and flow
• Robotic vs. human patterns
• Engagement and storytelling

Provides:

• Humanity score (0-100)
• Critical edits with before/after
• Pattern analysis
• Specific rewrites to inject personality
• Readability improvements

Output: Editorial report with specific improvements to make content sound human

---

Performance

Purpose: Data-driven content prioritization using real analytics

Analyzes:

• Google Analytics traffic and trends
• Google Search Console rankings and CTR
• DataForSEO competitive data
• Quick wins (position 11-20)
• Declining content
• Low CTR opportunities
• Trending topics

Provides:

• Priority queue of content tasks
• Opportunity scores (0-100)
• Impact and effort estimates
• Week-by-week roadmap
• Success metrics

Output: Comprehensive performance report with actionable priorities

---

Headline Generator

Purpose: Generate high-converting headline variations and A/B testing recommendations

Provides:

• 10+ headline variations using proven formulas
• Conversion potential scoring
• A/B testing strategies
• Audience-specific headline option