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
Installation
- Clone this repository:
git clone https://github.com/TheCraigHewitt/seomachine.git
cd seomachine
Planning to contribute? Fork this repo first, then clone your fork instead:
git clone https://github.com/<your-username>/seomachine.git
- 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)
- Open in Claude Code:
claude-code .
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 sitecontext/features.md - List your product/service features and benefitscontext/internal-links-map.md - Map your key pages for internal linkingcontext/style-guide.md - Fill in your style preferencescontext/target-keywords.md - Add your keyword research and topic clusterscontext/competitor-analysis.md - Add competitor analysis and insightscontext/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.
Docker Setup
Before running Docker, configure data_sources/config/.env with your credentials.
docker-compose build
docker-compose run seomachine bash
Content directories are mounted as volumes, so files in topics/, research/, drafts/, published/, output/, rewrites/, context/, and credentials/ persist on your host.
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 detectionkeyword_analyzer.py - Keyword density, clustering, LSI keywordscontent_length_comparator.py - SERP competitor analysisreadability_scorer.py - Multiple readability metricsseo_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
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
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 options
CRO Analyst
Purpose: Conversion rate optimization analysis for landing pages
Analyzes:
- Above-the-fold effectiveness
- CTA quality and distribution
- Trust signal presence
- Friction points
- Page structure
Landing Page Optimizer
Purpose: Comprehensive landing page optimization recommendations
Provides:
- CRO scoring (0-100) with category breakdowns
- Above-fold, CTA, trust signal, structure, and SEO analysis
- A/B testing recommendations
- Priority action list
Marketing Skills
SEO Machine includes 26 marketing skills accessible as slash commands:
| Category |
Skills |
| Copywriting |
/copywriting, /copy-editing |
| CRO |
/page-cro, /form-cro, /signup-flow-cro, /onboarding-cro, /popup-cro, /paywall-upgrade-cro |
| Strategy |
/content-strategy, /pricing-strategy, /launch-strategy, /marketing-ideas |
| Channels |
/email-sequence, /social-content, /paid-ads |
| SEO |
/seo-audit, /schema-markup, /programmatic-seo, /competitor-alternatives |
| Analytics |
/analytics-tracking, /ab-test-setup |
| Other |
/referral-program, /free-tool-strategy, /marketing-psychology |
Data Sources
Integration with Analytics
SEO Machine integrates with real-time data sources to inform content strategy:
Google Analytics 4:
- Traffic and engagement metrics
- Conversion tracking
- Trend analysis
- Traffic sources
Google Search Console:
- Keyword rankings and positions
- Impressions and clicks
- CTR analysis
- Query performance
DataForSEO:
- Competitive rankings
- SERP features
- Keyword metrics
- Competitor gap analysis
Advanced SEO Analysis Modules (NEW!)
SEO Machine includes 5 specialized Python modules for comprehensive content analysis:
Search Intent Analyzer (search_intent_analyzer.py):
- Classifies queries into informational, navigational, transactional, or commercial intent
- Analyzes SERP features and content patterns
- Provides confidence scores and content alignment recommendations
Keyword Analyzer (keyword_analyzer.py):
- Calculates exact keyword density and distribution
- Detects keyword stuffing risk with warnings
- Performs topic clustering using TF-IDF and K-means
- Generates distribution heatmap by section
- Identifies LSI (semantically related) keywords
SEO Quality Rater (seo_quality_rater.py):
- Rates content against SEO best practices (0-100 score)
- Category breakdowns: content, keywords, meta, structure, links, readability
- Identifies critical issues, warnings, and suggestions
- Determines publishing readiness
Content Length Comparator (content_length_comparator.py):
- Fetches and analyzes top 10-20 SERP competitor word counts
- Calculates median, 75th percentile, and optimal length
- Shows competitive positioning and gap to target
- Provides data-driven expansion recommendations
Readability Scorer (readability_scorer.py):
- Flesch Reading Ease and Flesch-Kincaid Grade Level
- Sentence and paragraph structure analysis
- Passive voice detection and ratio calculation
- Complex word identification
- Transition word usage analysis
- Overall readability score (0-100)
All modules can be used directly in Python or through the Content Analyzer agent.
CRO Analysis Modules
Six Python modules for landing page conversion optimization:
above_fold_analyzer.py - Above-the-fold content analysis (headline, value prop, CTA, trust)cta_analyzer.py - CTA effectiveness scoring (quality, distribution, goal alignment)trust_signal_analyzer.py - Trust signal detection (testimonials, social proof, risk reversals)landing_page_scorer.py - Overall landing page scoring (0-100 with category breakdowns)landing_performance.py - Landing page performance tracking via GA4/GSCcro_checker.py - CRO best practices checklist validation
Additional Analysis Modules
opportunity_scorer.py - 8-factor opportunity scoring for content prioritizationcontent_scorer.py - 5-dimension content quality scoring (humanity, specificity, structure, SEO, readability)engagement_analyzer.py - Content engagement pattern analysiscompetitor_gap_analyzer.py - Competitive content gap identificationarticle_planner.py - Data-driven article planningsection_writer.py - Section-level content guidancesocial_research_aggregator.py - Social media research aggregation
Python Research Scripts
Run from repo root:
# Content research
python3 research_quick_wins.py
python3 research_competitor_gaps.py
python3 research_performance_matrix.py
python3 research_priorities_comprehensive.py
python3 research_serp_analysis.py
python3 research_topic_clusters.py
python3 research_trending.py
# SEO analysis (config-driven - set up config/competitors.json first)
python3 seo_baseline_analysis.py
python3 seo_bofu_rankings.py
python3 seo_competitor_analysis.py
# Test API connectivity
python3 test_dataforseo.py
Note: SEO analysis scripts load competitor lists and keywords from config/competitors.json. Copy config/competitors.example.json and customize for your business.
WordPress Integration
Publishing uses the WordPress REST API with a custom MU-plugin that exposes Yoast SEO fields.
Setup:
- Install
wordpress/seo-machine-yoast-rest.php as an MU-plugin on your WordPress site
- Add
wordpress/functions-snippet.php to your theme's functions.php
- Configure WordPress credentials in
.env:WP_URL=https://yoursite.com
WP_USERNAME=your_username
WP_APP_PASSWORD=your_application_password
See wordpress/README.md for detailed setup instructions.
See data_sources/README.md for analytics setup instructions.
Directory Structure
seomachine/
├── .claude/
│ ├── commands/ # Custom workflow commands
│ │ ├── analyze-existing.md
│ │ ├── research.md
│ │ ├── write.md
│ │ ├── rewrite.md
│ │ ├── optimize.md
│ │ ├── scrub.md
│ │ ├── performance-review.md
│ │ ├── publish-draft.md
│ │ ├── article.md
│ │ ├── priorities.md
│ │ ├── research-serp.md
│ │ ├── research-gaps.md
│ │ ├── research-trending.md
│ │ ├── research-performance.md
│ │ ├── research-topics.md
│ │ ├── landing-write.md
│ │ ├── landing-audit.md
│ │ ├── landing-research.md
│ │ ├── landing-competitor.md
│ │ └── landing-publish.md
│ ├── agents/ # Specialized analysis agents
│ │ ├── content-analyzer.md
│ │ ├── seo-optimizer.md
│ │ ├── meta-creator.md
│ │ ├── internal-linker.md
│ │ ├── keyword-mapper.md
│ │ ├── editor.md
│ │ ├── performance.md
│ │ ├── headline-generator.md
│ │ ├── cro-analyst.md
│ │ └── landing-page-optimizer.md
│ └── skills/ # 26 marketing skills
├── data_sources/ # Analytics integrations
│ ├── modules/ # Python analysis modules
│ │ ├── google_analytics.py
│ │ ├── google_search_console.py
│ │ ├── dataforseo.py
│ │ ├── data_aggregator.py
│ │ ├── search_intent_analyzer.py
│
SEO Machine is a specialized Claude Code workspace for creating long-form, SEO-optimized blog content for any business. It helps you research, write, analyze, and optimize content that ranks well and serves your target audience.