SEO Machine: AI-Powered Content Creation Workspace

In the competitive world of digital marketing, creating high-quality, SEO-optimized content consistently is a significant challenge. SEO Machine, an open-source project with over 4,250 stars on GitHub, addresses this challenge by providing a specialized Claude Code workspace designed for creating long-form, SEO-optimized blog content. This comprehensive system combines the power of AI agents, Python analytics modules, and real-time data integrations to help businesses produce content that ranks well and serves their target audience effectively.

What is SEO Machine?

SEO Machine is a sophisticated content creation workspace built on Claude Code that streamlines the entire content lifecycle from research to publication. Unlike traditional content tools that focus on single aspects of SEO, SEO Machine provides an integrated ecosystem where specialized AI agents work together to analyze, write, optimize, and publish content.

The system is designed for marketing teams, content creators, and businesses who need to produce high-quality blog content at scale. By leveraging Claude’s natural language capabilities combined with custom Python analysis modules, SEO Machine ensures that every piece of content meets rigorous SEO standards while maintaining brand voice and engaging readers.

Architecture Overview

Understanding the Architecture

The architecture diagram above illustrates the multi-layered design of SEO Machine, showcasing how different components interact to create a seamless content creation workflow. Let’s examine each layer and its components in detail.

Core Foundation Layer:

At the foundation lies Claude Code, which serves as the orchestration engine for all operations. This layer provides the natural language processing capabilities that power the intelligent content generation and analysis features. Claude Code interprets user commands, coordinates between different agents, and ensures that the output aligns with the configured brand voice and SEO guidelines.

The foundation also includes the context system, which maintains brand voice guidelines, writing examples, style guides, and SEO requirements. This context-driven approach ensures consistency across all content produced, regardless of which agent or command is used.

Command Layer:

The command layer consists of over 20 workflow commands that users can invoke to perform specific tasks. These commands range from research-focused operations like /research and /research-serp to content creation commands like /write and /rewrite. Each command is designed to handle a specific part of the content lifecycle, allowing users to work efficiently without switching between multiple tools.

Commands are defined in markdown files within the .claude/commands/ directory, making them easy to customize and extend. The modular design allows teams to add new commands specific to their workflow without modifying the core system.

Agent Layer:

The agent layer contains 10 specialized AI agents that provide expert analysis and recommendations. These agents are automatically triggered by commands or can be invoked directly for specific analysis tasks. Each agent focuses on a particular domain:

• Content Analyzer: Comprehensive content analysis using multiple metrics
• SEO Optimizer: On-page SEO analysis and recommendations
• Meta Creator: Generation of meta titles and descriptions
• Internal Linker: Strategic internal linking suggestions
• Keyword Mapper: Keyword placement and density analysis
• Editor: Human-sounding content refinement
• Performance Agent: Data-driven content prioritization
• Headline Generator: High-converting headline variations
• CRO Analyst: Conversion rate optimization analysis
• Landing Page Optimizer: Landing page optimization recommendations

Analysis Modules Layer:

The analysis modules layer contains 25+ Python modules that provide data-driven insights. These modules perform quantitative analysis that complements the qualitative assessments from AI agents. The modules include search intent analyzers, keyword density calculators, readability scorers, and SEO quality raters.

Each module is designed to be independently usable, allowing developers to integrate specific analysis capabilities into their own workflows. The modular architecture also makes it easy to add new analysis capabilities as SEO best practices evolve.

Data Integration Layer:

The data integration layer connects SEO Machine to external data sources including Google Analytics 4, Google Search Console, and DataForSEO. These integrations provide real-time performance data that informs content strategy and prioritization decisions.

By pulling actual performance metrics, SEO Machine can identify quick-win opportunities, track content performance over time, and make data-driven recommendations for content updates and new content creation.

Content Creation Workflow

Understanding the Content Creation Workflow

The workflow diagram above demonstrates the complete content creation process in SEO Machine, from initial topic ideation to final publication. This systematic approach ensures that every piece of content is thoroughly researched, well-written, and optimized before it reaches the audience.

Phase 1: Topic Ideation and Research

The workflow begins with topic ideation, where content creators identify potential topics based on business goals, keyword opportunities, and audience needs. Topics are stored in the topics/ directory as simple markdown files with initial thoughts and target keywords.

Once a topic is selected, the /research command initiates comprehensive research. This command performs keyword research to identify primary and secondary keywords, analyzes the top 10 competitors currently ranking for the target keyword, identifies content gaps and opportunities, and creates a comprehensive research brief that serves as the foundation for content creation.

The research phase is critical because it ensures that the content is strategically positioned to rank well. By understanding what competitors are doing and where gaps exist, content creators can produce content that provides unique value.

Phase 2: Content Writing

With the research brief complete, the /write command creates the initial article draft. This command generates 2,000-3,000+ word articles that are SEO-optimized from the start. The writing process considers brand voice from context/brand-voice.md, integrates keywords naturally throughout the content, includes internal and external links strategically, and provides meta elements including title, description, and keywords.

After writing, multiple agents automatically analyze the content. The SEO Optimizer provides on-page SEO recommendations, the Meta Creator generates multiple meta title and description options, the Internal Linker suggests specific internal linking opportunities, and the Keyword Mapper analyzes keyword placement and density.

Phase 3: Review and Optimization

The review phase involves human editors reviewing the draft and agent recommendations. Editors make improvements based on agent feedback, addressing high-priority issues first. The /optimize command then performs a final SEO audit, validating all elements meet requirements and providing a publishing readiness score.

This phase also includes the /scrub command, which removes AI watermarks and patterns from the content. This includes eliminating em-dashes, filler phrases, and robotic patterns that can make content feel artificial.

Phase 4: Publication

The final phase uses the /publish-draft command to publish content to WordPress via the REST API. The system includes Yoast SEO metadata integration, ensuring that all SEO elements are properly configured in the content management system.

After publication, content moves to the published/ directory for archival and tracking. The system maintains a complete history of all content, making it easy to track performance and make updates when needed.

Phase 5: Content Maintenance

SEO Machine also supports content updates through the /analyze-existing and /rewrite commands. These commands analyze existing content for improvement opportunities, identify outdated information, assess competitive positioning, and provide recommendations for updates.

This maintenance workflow ensures that content remains relevant and continues to perform well over time. Regular content audits can identify declining performance and trigger timely updates.

Data Sources Integration

Understanding Data Sources Integration

The data sources diagram illustrates how SEO Machine connects to external analytics platforms to inform content strategy with real-time performance data. This integration is what separates SEO Machine from static content tools, enabling data-driven decision making throughout the content lifecycle.

Google Analytics 4 Integration:

The Google Analytics 4 (GA4) integration provides comprehensive traffic and engagement metrics. Through the google_analytics.py module, SEO Machine can retrieve page views, unique visitors, and session duration data. This information helps identify which content performs well and which needs improvement.

The GA4 integration also tracks conversion events, allowing content creators to understand which articles drive business outcomes. By correlating content characteristics with conversion performance, teams can identify patterns and replicate success across future content.

Trend analysis features enable teams to spot declining or growing content performance. This proactive approach allows for timely content updates before performance significantly drops, maintaining organic traffic levels over time.

Google Search Console Integration:

The Google Search Console (GSC) integration, implemented in google_search_console.py, provides critical SEO performance data. This includes keyword rankings and position tracking, impressions and clicks data, click-through rate (CTR) analysis, and query performance metrics.

GSC data is particularly valuable for identifying quick-win opportunities. Keywords ranking in positions 11-20 represent content that could move to page one with targeted optimization. SEO Machine’s Performance Agent uses this data to prioritize content tasks based on potential impact.

The integration also helps identify content with high impressions but low CTR, indicating potential issues with meta titles or descriptions. This insight enables targeted improvements that can significantly increase traffic without creating new content.

DataForSEO Integration:

DataForSEO provides competitive intelligence through the dataforseo.py module. This third-party API integration offers competitive ranking data, SERP feature analysis, keyword metrics including search volume and difficulty, and competitor gap analysis.

The competitive data enables content creators to understand the competitive landscape before writing. By analyzing what competitors are doing, teams can identify opportunities to create superior content that addresses gaps in the existing search results.

SERP feature analysis helps identify opportunities for featured snippets, people also ask boxes, and other enhanced search results. Creating content optimized for these features can significantly increase visibility and click-through rates.

Data Aggregation Layer:

The data_aggregator.py module combines data from all sources into unified reports. This aggregation enables cross-platform analysis, such as correlating GA4 traffic with GSC rankings to understand the full picture of content performance.

Aggregated data feeds into various analysis modules and agents, ensuring that recommendations are based on actual performance data rather than assumptions. This data-driven approach increases the likelihood of content success.

WordPress REST API Integration:

The WordPress integration enables seamless content publication. The wordpress_publisher.py module handles authentication, content formatting, and metadata management. The system includes a custom MU-plugin that exposes Yoast SEO fields through the REST API.

This integration allows content to flow directly from SEO Machine to WordPress without manual copying and pasting. All SEO elements, including meta titles, descriptions, and focus keywords, are properly configured during publication.

Analysis Pipeline

Understanding the Analysis Pipeline

The analysis pipeline diagram shows how content flows through SEO Machine’s five core analysis modules, each providing specialized insights that contribute to a comprehensive content quality assessment. This modular approach ensures thorough analysis while maintaining flexibility for future enhancements.

Module 1: Search Intent Analyzer

The Search Intent Analyzer (search_intent_analyzer.py) is the first module in the pipeline, responsible for classifying the search intent behind target keywords. Understanding search intent is crucial because content must match what users are actually looking for to rank well.

The module classifies queries into four primary intent types:

• Informational: Users seeking information or answers (e.g., “how to write a blog post”)
• Navigational: Users looking for a specific website or page (e.g., “GitHub login”)
• Transactional: Users ready to make a purchase (e.g., “buy SEO software”)
• Commercial: Users researching before a purchase decision (e.g., “best SEO tools 2024”)

The analyzer examines SERP features and content patterns to determine intent with confidence scores. It then provides recommendations for content alignment, ensuring that the content structure and approach match user expectations.

Module 2: Keyword Analyzer

The Keyword Analyzer (keyword_analyzer.py) performs detailed keyword analysis including density calculations, distribution analysis, and topic clustering. This module ensures keywords are used effectively without triggering keyword stuffing penalties.

Key functions include:

• Density Calculation: Exact keyword density percentages with warnings for over-optimization
• Distribution Heatmap: Visual representation of keyword placement across content sections
• Topic Clustering: TF-IDF and K-means clustering to identify related topics and LSI keywords
• Stuffing Detection: Automatic warnings when keyword usage appears unnatural

The module also identifies semantically related keywords (LSI keywords) that should be included for comprehensive topic coverage. This helps content rank for a broader range of related queries.

Module 3: Content Length Comparator

The Content Length Comparator (content_length_comparator.py) analyzes SERP competitors to determine optimal content length. This data-driven approach ensures content is competitive in terms of depth and comprehensiveness.

The module fetches and analyzes the top 10-20 SERP results for the target keyword, calculating median word count, 75th percentile length, and optimal length range. It then positions the current content against these benchmarks and provides specific expansion recommendations.

Understanding competitive content length helps content creators make informed decisions about how much detail to include. Content that is significantly shorter than competitors may be seen as less comprehensive, while overly long content may lose reader engagement.

Module 4: Readability Scorer

The Readability Scorer (readability_scorer.py) evaluates content readability using multiple metrics to ensure content is accessible to the target audience. Readability is both a user experience factor and an SEO consideration.

The module calculates:

• Flesch Reading Ease: A 0-100 score indicating reading difficulty
• Flesch-Kincaid Grade Level: The educational level required to understand the content
• Sentence Structure Analysis: Average sentence length and complexity
• Paragraph Structure: Paragraph length and organization
• Passive Voice Ratio: Percentage of passive voice constructions
• Complex Word Identification: Percentage of difficult words
• Transition Word Usage: Analysis of flow and coherence

Recommendations are provided to improve readability, typically targeting an 8th-10th grade reading level for general audience content. This ensures content is accessible while still providing value to knowledgeable readers.

Module 5: SEO Quality Rater

The SEO Quality Rater (seo_quality_rater.py) provides a comprehensive SEO score from 0-100, broken down by category. This final module synthesizes all previous analysis into an actionable assessment.

Category breakdowns include:

• Content Quality (25 points): Uniqueness, depth, accuracy, actionability
• Keyword Optimization (20 points): Density, placement, LSI coverage
• Meta Elements (15 points): Title length, description length, keyword presence
• Structure (15 points): Heading hierarchy, content organization, formatting
• Links (15 points): Internal links, external links, anchor text quality
• Readability (10 points): Reading level, sentence structure, scannability

The module identifies critical issues that must be fixed, warnings that should be addressed, and suggestions for optimization. It also provides a publishing readiness assessment, helping teams understand when content is ready to go live.

Pipeline Integration:

All five modules work together in sequence, with each module’s output informing subsequent analysis. The Content Analyzer agent orchestrates this pipeline, combining results into a unified report with an executive summary, priority action plan, and detailed recommendations.

This integrated approach ensures that no aspect of content quality is overlooked. By the time content reaches the end of the pipeline, teams have a complete picture of strengths, weaknesses, and specific improvements needed.

Key Features

20+ Workflow Commands

SEO Machine provides over 20 specialized commands for different content tasks:

Command	Description
/research	Comprehensive keyword and competitive research
/write	Create long-form SEO-optimized articles
/rewrite	Update and improve existing content
/analyze-existing	Analyze existing posts for improvement opportunities
/optimize	Final SEO optimization pass before publishing
/publish-draft	Publish to WordPress with Yoast SEO metadata
/article	Simplified article creation workflow
/priorities	Content prioritization using analytics data
/scrub	Remove AI watermarks and patterns
/research-serp	SERP analysis for target keywords
/research-gaps	Competitor content gap analysis
/research-trending	Trending topic opportunities
/research-performance	Performance-based content priorities
/research-topics	Topic cluster research
/landing-write	Create conversion-optimized landing pages
/landing-audit	Audit landing pages for CRO issues
/landing-research	Research competitors and positioning
/landing-competitor	Deep competitor landing page analysis
/landing-publish	Publish landing pages to WordPress

10 Specialized AI Agents

Each agent provides expert analysis in a specific domain:

Content Analyzer: Comprehensive analysis using all five analysis modules, providing executive summaries and priority action plans.

SEO Optimizer: On-page SEO analysis covering keyword optimization, content structure, links, meta elements, and featured snippet opportunities.

Meta Creator: Generates multiple meta title and description variations with testing recommendations and SERP previews.

Internal Linker: Provides strategic internal linking suggestions with exact placement locations and anchor text recommendations.

Keyword Mapper: Analyzes keyword placement, density, distribution, and identifies LSI keyword opportunities.

Editor: Transforms technically accurate content into human-sounding, engaging articles with personality and storytelling.

Performance Agent: Uses real analytics data to prioritize content tasks based on traffic potential and effort required.

Headline Generator: Creates high-converting headline variations using proven formulas and provides A/B testing strategies.

CRO Analyst: Analyzes landing pages for conversion rate optimization opportunities including above-fold effectiveness and CTA quality.

Landing Page Optimizer: Provides comprehensive landing page optimization with CRO scoring and priority action lists.

25+ Python Analysis Modules

The analysis modules provide quantitative insights:

Module	Purpose
search_intent_analyzer.py	Search intent classification
keyword_analyzer.py	Keyword density and clustering
content_length_comparator.py	SERP competitor length analysis
readability_scorer.py	Multiple readability metrics
seo_quality_rater.py	Comprehensive SEO scoring
opportunity_scorer.py	8-factor opportunity scoring
content_scorer.py	5-dimension content quality
engagement_analyzer.py	Content engagement patterns
competitor_gap_analyzer.py	Competitive gap identification
article_planner.py	Data-driven article planning
section_writer.py	Section-level content guidance
social_research_aggregator.py	Social media research aggregation
above_fold_analyzer.py	Above-the-fold content analysis
cta_analyzer.py	CTA effectiveness scoring
trust_signal_analyzer.py	Trust signal detection
landing_page_scorer.py	Overall landing page scoring
landing_performance.py	Landing page performance tracking
cro_checker.py	CRO best practices validation

26 Marketing Skills

SEO Machine includes 26 marketing skills organized by category:

Copywriting Skills: /copywriting, /copy-editing

CRO Skills: /page-cro, /form-cro, /signup-flow-cro, /onboarding-cro, /popup-cro, /paywall-upgrade-cro

Strategy Skills: /content-strategy, /pricing-strategy, /launch-strategy, /marketing-ideas

Channel Skills: /email-sequence, /social-content, /paid-ads

SEO Skills: /seo-audit, /schema-markup, /programmatic-seo, /competitor-alternatives

Analytics Skills: /analytics-tracking, /ab-test-setup

Other Skills: /referral-program, /free-tool-strategy, /marketing-psychology

Installation and Setup

Prerequisites

Before installing SEO Machine, ensure you have:

• Claude Code installed (available from claude.com/claude-code)
• An Anthropic API account with appropriate access
• Python 3.8 or higher for analysis modules
• A WordPress site (optional, for publishing integration)

Installation Steps

Step 1: Clone the Repository

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

Step 2: Install Python Dependencies

pip install -r data_sources/requirements.txt

This installs all required packages including:

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

Step 3: Open in Claude Code

claude-code .

Step 4: Configure Context Files

The most important step is customizing the context files for your business:

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

Step 5: Configure Data Sources (Optional)

For analytics integration, set up API credentials:

# Copy example config
cp config/competitors.example.json config/competitors.json

# Edit with your competitor list and keywords

For WordPress publishing, configure credentials in .env:

WP_URL=https://yoursite.com
WP_USERNAME=your_username
WP_APP_PASSWORD=your_application_password

Usage Examples

Creating New Content

# Step 1: Research your topic
/research content marketing strategies for B2B SaaS

# Step 2: Review the research brief
# Read research/brief-content-marketing-strategies-[date].md

# Step 3: Write the article
/write content marketing strategies for B2B SaaS

# Step 4: Review agent feedback
# Check drafts/ for article and agent reports

# Step 5: Optimize
/optimize drafts/content-marketing-strategies-[date].md

# Step 6: Publish (optional)
/publish-draft drafts/content-marketing-strategies-[date].md

Updating Existing Content

# Step 1: Analyze existing post
/analyze-existing https://yoursite.com/blog/marketing-guide

# Step 2: Review analysis
# Read research/analysis-marketing-guide-[date].md

# Step 3: Rewrite content
/rewrite marketing guide

# Step 4: Optimize
/optimize rewrites/marketing-guide-rewrite-[date].md

Content Prioritization

# Get data-driven content priorities
/priorities

# Output includes:
# - Quick wins (position 11-20)
# - Declining content
# - Low CTR opportunities
# - Trending topics

Content Quality Standards

SEO Machine enforces quality standards across all content:

Content Requirements

• Minimum 2,000 words (2,500-3,000+ preferred)
• Unique value vs. competitors
• Factually accurate and current
• Actionable advice for target audience
• Consistent brand voice

SEO Requirements

• Primary keyword density 1-2%
• Keyword in H1, first 100 words, 2-3 H2s
• 3-5 internal links with descriptive anchor text
• 2-3 external authority links
• Meta title 50-60 characters
• Meta description 150-160 characters
• Proper H1>H2>H3 hierarchy

Readability Requirements

• 8th-10th grade reading level
• Average sentence length 15-20 words
• Paragraphs 2-4 sentences
• Subheadings every 300-400 words
• Lists and formatting for scannability

Best Practices

Before Writing

1. Always run /research before /write
2. Review brand-voice.md and writing-examples.md
3. Verify target keyword in target-keywords.md
4. Plan internal links from internal-links-map.md

During Writing

1. Use research brief as your outline
2. Integrate keywords naturally, never force them
3. Every section should provide actionable insights
4. Include real scenarios and use cases
5. Link to statistics and data sources

After Writing

1. Read all agent recommendations carefully
2. Address high-priority issues before optimizing
3. Run /optimize for final polish
4. Self-edit as if you’re the target reader
5. Verify all checklist items are met

Troubleshooting

“Content doesn’t sound like my brand”

• Update context/brand-voice.md with more specific guidance
• Add more diverse examples to context/writing-examples.md
• Reference specific examples when using /write command

“Keyword density too high/low”

• Review seo-guidelines.md target density (1-2%)
• Use /optimize for specific placement suggestions
• Use Keyword Mapper agent for distribution analysis

“Internal links aren’t relevant”

• Update context/internal-links-map.md with current pages
• Organize by topic cluster for easier matching
• Provide more context about each page’s content

“Articles too similar to competitors”

• Update competitor-analysis.md with differentiation opportunities
• Add unique advantages to brand-voice.md and features.md
• Reference specific differentiation angles in /research command

Conclusion

SEO Machine represents a significant advancement in AI-powered content creation. By combining Claude’s natural language capabilities with specialized agents, Python analytics modules, and real-time data integrations, it provides a comprehensive solution for creating SEO-optimized content at scale.

The system’s modular architecture allows teams to adopt specific components or use the entire workflow. Whether you need help with research, writing, optimization, or publication, SEO Machine provides intelligent assistance at every stage.

For marketing teams struggling to produce consistent, high-quality content, SEO Machine offers a path to scale content operations without sacrificing quality. The data-driven approach ensures that content decisions are based on actual performance metrics rather than guesswork.

The open-source nature of the project means it can be customized to fit specific workflows and requirements. Teams can add new commands, agents, and analysis modules as needed, making it a flexible foundation for content operations.

Resources

• GitHub Repository: TheCraigHewitt/seomachine
• Claude Code Documentation: docs.claude.com/claude-code
• Stars: 4,250+
• Forks: 681

Related Posts

• AgentSkillOS: Skill Orchestration System
• MattPocock Skills: AI Agent Workflows
• DESIGN.md: AI-Powered Design Systems