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.

SEO Machine is built on Claude Code and provides:

• Custom Commands: /research, /write, /rewrite, /analyze-existing, /optimize, /performance-review
• Specialized Agents: Content analyzer, SEO optimization, meta element creation, internal linking, keyword mapping, editor, performance analysis
• 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

• Claude Code installed
• Anthropic API account

1. Clone this repository:

git clone https://github.com/[your-username]/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.

/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

/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

/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

/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

/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

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

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

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 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

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

Specialized agents that automatically analyze content and provide expert recommendations.

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

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

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

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

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

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

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.

See data_sources/README.md for setup instructions.

seomachine/
├── .claude/
│   ├── commands/          # Custom workflow commands
│   │   ├── analyze-existing.md
│   │   ├── research.md
│   │   ├── write.md
│   │   ├── rewrite.md
│   │   ├── optimize.md
│   │   └── performance-review.md
│   └── agents/            # Specialized analysis agents
│       ├── content-analyzer.md    # NEW! Comprehensive analysis
│       ├── seo-optimizer.md
│       ├── meta-creator.md
│       ├── internal-linker.md
│       ├── keyword-mapper.md
│       ├── editor.md
│       └── performance.md
├── data_sources/          # Analytics integrations
│   ├── modules/          # Python integration modules
│   │   ├── google_analytics.py
│   │   ├── google_search_console.py
│   │   ├── dataforseo.py
│   │   ├── data_aggregator.py
│   │   ├── search_intent_analyzer.py    # NEW!
│   │   ├── keyword_analyzer.py          # NEW!
│   │   ├── seo_quality_rater.py         # NEW!
│   │   ├── content_length_comparator.py # NEW!
│   │   └── readability_scorer.py        # NEW!
│   ├── config/           # API credentials (not in git)
│   ├── utils/            # Helper functions
│   ├── cache/            # Cached API responses
│   └── README.md         # Setup instructions
├── context/               # Configuration and guidelines
│   ├── brand-voice.md          # Your brand voice and messaging (template)
│   ├── writing-examples.md     # Example blog posts
│   ├── style-guide.md          # Writing style conventions
│   ├── seo-guidelines.md       # SEO requirements
│   ├── target-keywords.md      # Keyword research and clusters
│   ├── internal-links-map.md   # Key pages for internal linking
│   └── competitor-analysis.md  # Competitive intelligence
├── topics/                # Raw topic ideas
├── research/              # Research briefs and analysis reports
├── drafts/                # Work in progress articles
├── published/             # Final versions ready to publish
├── rewrites/              # Updated existing content
└── README.md              # This file

The quality of your content depends on well-configured context files:

Defines your brand voice, tone, and messaging framework.

Must include:

• Voice pillars
• Tone guidelines by content type
• Core brand messages
• Writing style guidelines
• Terminology preferences

Purpose: Ensures all content sounds like your brand

Contains 3-5 exemplary blog posts from your site.

Must include:

• Full article content
• What makes each example great
• Key takeaways for voice and structure

Purpose: Teaches AI your specific writing style through examples

Editorial and formatting standards.

Must include:

• Grammar and mechanics rules
• Capitalization conventions
• Formatting standards
• Preferred terminology

Purpose: Maintains consistency across all content

SEO best practices and requirements.

Includes:

• Content length requirements
• Keyword optimization rules
• Meta element standards
• Link strategy guidelines
• Readability requirements

Purpose: Ensures all content meets SEO standards

Keyword research organized by topic cluster.

Must include:

• Pillar keywords by cluster
• Cluster keywords (subtopics)
• Long-tail variations
• Search intent classification
• Current rankings

Purpose: Guides keyword targeting for new content

Catalog of key pages from your site for internal linking.

Must include:

• Product pages and features
• Pillar content URLs
• Top performing blog articles
• Topic cluster mapping
• Recommended anchor text

Purpose: Enables strategic internal linking in every article

Competitive intelligence and content gaps.

Must include:

• Primary competitors
• Their content strategies
• Keyword gaps
• Differentiation opportunities

Purpose: Informs content strategy and competitive positioning

Every article must meet these requirements:

• Minimum 2,000 words (2,500-3,000+ preferred)
• Provides unique value vs. competitors
• Factually accurate and current
• Actionable advice for your target audience
• Brand voice maintained

• 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

• 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

• Compelling introduction (hook, problem, promise)
• Logical section flow
• Clear conclusion with CTA
• Examples and data included

1. Research first: Always run /research before /write
2. Review context: Read brand-voice.md and relevant writing-examples.md
3. Check keywords: Verify target keyword in target-keywords.md
4. Plan internal links: Review internal-links-map.md for linking opportunities

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

1. Review agent output: Read all agent recommendations carefully
2. Make improvements: Address high-priority issues before optimizing
3. Run optimize: Use /optimize for final polish
4. Self-edit: Read article as if you're the target reader
5. Check quality: Verify all checklist items met

1. Analyze first: Run /analyze-existing to understand scope
2. Determine strategy: Light update vs. major rewrite?
3. Preserve what works: Keep effective sections
4. Focus on gaps: Add what's missing from competitive content
5. Update everything: Stats, examples, screenshots, links

# Step 1: Add topic idea
# Create file in topics/ directory with initial thoughts

# Step 2: Research the topic
/research podcast advertising strategies

# Step 3: Review research brief
# Read research/brief-podcast-advertising-strategies-2025-10-15.md

# Step 4: Write article
/write podcast advertising strategies

# Step 5: Review agent feedback
# Read all agent reports in drafts/

# Step 6: Make improvements
# Edit article based on agent recommendations

# Step 7: Final optimization
/optimize drafts/podcast-advertising-strategies-2025-10-15.md

# Step 8: Final review and move to published/
# Manual review, then move when ready

# Step 1: Analyze existing post
/analyze-existing https://yoursite.com/blog/product-comparison

# Step 2: Review analysis
# Read research/analysis-product-comparison-2025-10-29.md
# Check content health score and priority level

# Step 3: Rewrite content
/rewrite product comparison

# Step 4: Review changes
# Read rewrites/product-comparison-rewrite-2025-10-29.md
# Review change summary

# Step 5: Optimize
/optimize rewrites/product-comparison-rewrite-2025-10-29.md

# Step 6: Publish
# Move to published/ when ready

# Analyze multiple existing posts to prioritize updates
/analyze-existing https://yoursite.com/blog/post-1
/analyze-existing https://yoursite.com/blog/post-2
/analyze-existing https://yoursite.com/blog/post-3

# Review content health scores
# Prioritize rewrites based on:
# - Lowest scores
# - Highest traffic potential
# - Strategic importance

• Study examples: Read your writing-examples.md before each writing session
• Use data: Always include current statistics and cite sources
• Be specific: "40% increase" beats "significant improvement"
• Show, don't tell: Use real podcast examples and scenarios
• Answer questions: Address "People Also Ask" questions from research

• Keywords early: Get primary keyword in first 100 words
• Natural integration: Read content aloud - if keywords sound forced, rewrite
• Vary anchor text: Don't use same anchor text for all internal links
• Link strategically: Link to pillar content and related cluster articles
• Update regularly: Refresh top-performing content every 6-12 months

• Batch research: Research multiple topics in one session
• Follow structure: Use consistent article structure from /write command
• Address high-priority first: Fix critical issues before optimizing details
• Use agents wisely: Let agents handle analysis, you focus on writing
• Build templates: Save commonly used sections for reuse

• ❌ Skipping research phase
• ❌ Ignoring brand voice guidelines
• ❌ Forcing keywords unnaturally
• ❌ Forgetting internal links
• ❌ Not citing data sources
• ❌ Publishing without optimization
• ❌ Copying competitor content instead of differentiating

• Add new topic ideas to /topics/
• Update target-keywords.md with new keyword opportunities
• Check for broken links in internal-links-map.md

• Review published content performance
• Update writing-examples.md if better examples emerge
• Add newly published content to internal-links-map.md
• Track competitor activity in competitor-analysis.md

• Full audit of context files
• Update SEO guidelines based on algorithm changes
• Comprehensive competitor analysis refresh
• Review and update topic clusters in target-keywords.md

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

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

• Solution: Update context/internal-links-map.md with current pages
• Solution: Organize by topic cluster for easier agent matching
• Solution: Provide more context about what each page covers

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

• Review this README thoroughly
• Check context files are properly configured
• Consult Claude Code documentation

• Report issues via GitHub Issues
• Suggest improvements to commands or agents
• Share successful workflows or tips

[Add your license information]

Built with Claude Code by Anthropic.

Originally developed for Castos, now available as an open-source tool for any business to streamline long-form SEO content creation.

See It In Action: Check out examples/castos/ for a complete real-world example of how a podcast hosting SaaS company uses SEO Machine.

Contributions Welcome: Found a bug? Have a feature request? Want to share your own industry example? Contributions and PRs are welcome!

Ready to start creating?

1. Configure your context files (use the templates as your guide)
2. Run /research [your topic]
3. Review the brief
4. Run /write [your topic]
5. Publish amazing content!

Happy writing! 📝