Claude Code + SEOMachine: The Right Way to Write SEO Articles with AI

343 stars, 24+ marketing skills, fully automated from research to publishing.

Ever faced these problems when using AI to write SEO articles?

Articles sound too "AI-ish" and get spotted instantly. Can't nail keyword density - either stuffing or too sparse. No idea what competitors wrote, content ends up generic. Still need to manually optimize meta, internal links, and readability.

SEOMachine solves these problems: An SEO workspace designed specifically for Claude Code.

From keyword research to article publishing, fully automated. 2000+ word long-form content, SEO score 0-100, one command does it all.

---

What It Is

SEOMachine is a Claude Code workspace specifically for writing SEO-optimized long-form content.

Core Features:

• 15+ custom commands (/research, /write, /optimize, etc.)
• 10 specialized agents (SEO optimization, meta generation, internal linking, etc.)
• 24+ marketing skills (copywriting, CRO, A/B testing, etc.)
• 5 Python analysis modules (keyword density, readability scoring, etc.)
• Data integrations (Google Analytics, Search Console, DataForSEO)

Workflow:

1. /research - Keyword research + competitor analysis
2. /write - Generate 2000-3000 word article
3. Auto-trigger 4 agents for analysis
4. /optimize - Final optimization
5. /publish-draft - Publish to WordPress

---

Why Choose It

1. Built for Claude Code

Not a generic AI writing tool, but a dedicated workspace for Claude Code.

Advantages:

• Custom commands: /research, /write, /optimize
• Specialized agents: Auto-analyze SEO, meta, internal links
• Context-driven: Brand voice, style guide, SEO standards

2. Fully Automated Workflow

From research to publishing, end-to-end service.

Complete workflow:

# 1. Research
/research content marketing strategies

# 2. Write (auto-triggers 4 agents)
/write content marketing strategies

# 3. Optimize
/optimize drafts/content-marketing-strategies-2026-03-08.md

# 4. Publish
/publish-draft drafts/content-marketing-strategies-2026-03-08.md

3. Data-Driven Decisions

Not guesswork, but based on real data.

Data sources:

• Google Analytics 4: Traffic, conversions
• Google Search Console: Rankings, CTR
• DataForSEO: Competitor data, SERP features

Use cases:

• Find "quick win" opportunities (positions 11-20)
• Identify declining content
• Discover low CTR optimization opportunities

---

Core Commands

/research - Keyword Research

Features:

• Keyword research (primary + secondary keywords)
• Competitor analysis (Top 10)
• Content gap identification
• Recommended outline
• Internal linking strategy

Output:

• Research brief: research/brief-[topic]-[date].md
• Includes: keywords, competitor analysis, content opportunities, recommended outline

Example:

/research content marketing strategies for B2B SaaS

/write - Generate Article

Features:

• Generate 2000-3000+ word article
• Maintain brand voice (from context/brand-voice.md)
• Naturally integrate keywords
• Add internal and external links
• Generate meta elements

Auto-triggers 4 agents:

1. SEO Optimizer: On-page SEO recommendations
2. Meta Creator: Multiple meta title/description options
3. Internal Linker: Internal linking suggestions
4. Keyword Mapper: Keyword distribution analysis

Output:

• Article: drafts/[topic]-[date].md
• 4 agent reports

Example:

/write content marketing strategies

/optimize - Final Optimization

Features:

• Comprehensive SEO audit
• Validate all elements
• Final polish recommendations
• Publishing readiness score

Output:

• Optimization report: drafts/optimization-report-[topic]-[date].md
• SEO score (0-100)
• Priority fixes

Example:

/optimize drafts/content-marketing-strategies-2026-03-08.md

/analyze-existing - Analyze Existing Content

Features:

• Fetch and analyze existing content
• Evaluate SEO performance
• Identify outdated information
• Content health score (0-100)

Output:

• Analysis report: research/analysis-[topic]-[date].md
• Update priority and scope

Example:

/analyze-existing https://yoursite.com/blog/marketing-guide

/rewrite - Update Content

Features:

• Update content based on analysis
• Refresh statistics and examples
• Improve SEO optimization
• Add new sections to fill gaps

Output:

• Updated article: rewrites/[topic]-rewrite-[date].md
• Change summary

---

Specialized Agents

Content Analyzer

The most powerful agent, using 5 Python modules for data-driven analysis.

Analyzes:

1. Search intent classification: informational/navigational/transactional/commercial
2. Keyword density and clustering: TF-IDF + K-means topic detection
3. Content length comparison: vs Top 10 competitors
4. Readability scoring: Flesch Reading Ease, Flesch-Kincaid Grade Level
5. SEO quality rating: 0-100 score with category breakdowns

Output:

• Executive summary + publishing readiness assessment
• Priority action plan (critical/high priority/optimization)
• Competitive positioning analysis
• Detailed recommendations

SEO Optimizer

Features:

• 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) + specific improvement recommendations

Meta Creator

Features:

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

Internal Linker

Features:

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

Reference: context/internal-links-map.md

Editor

Transforms 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

Output:

• Humanity score (0-100)
• Critical edits (before/after)
• Pattern analysis
• Specific rewrite suggestions

---

24+ Marketing 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

---

Installation

1. Install Claude Code

Visit https://claude.com/claude-code

2. Clone Repository

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

3. Install Dependencies

pip install -r data_sources/requirements.txt

Installs:

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

4. Open in Claude Code

claude-code .

5. Configure Context Files (Important!)

All context files are templates. Fill them with your company information:

Required files:

• context/brand-voice.md - Brand voice and messaging
• context/writing-examples.md - 3-5 exemplary blog posts
• context/features.md - Product/service features and benefits
• context/internal-links-map.md - Key page internal linking map
• context/style-guide.md - Style preferences
• context/target-keywords.md - Keyword research and topic clusters
• context/competitor-analysis.md - Competitor analysis and insights
• context/seo-guidelines.md - SEO requirements

Quick start: Check examples/castos/ for a complete real-world example (podcast hosting SaaS company).

---

Usage Examples

Scenario 1: Write New Article

# 1. Research topic
/research content marketing strategies

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

# 3. Write article
/write content marketing strategies

# 4. Review agent feedback
# Read all agent reports in drafts/

# 5. Make improvements
# Edit article based on agent recommendations

# 6. Final optimization
/optimize drafts/content-marketing-strategies-[date].md

# 7. Publish to WordPress (optional)
/publish-draft drafts/content-marketing-strategies-[date].md

Scenario 2: Update Existing Content

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

# 2. Review analysis report
# Read research/analysis-product-comparison-2026-03-08.md

# 3. Rewrite content
/rewrite product comparison

# 4. Review changes
# Read rewrites/product-comparison-rewrite-2026-03-08.md

# 5. Optimize
/optimize rewrites/product-comparison-rewrite-2026-03-08.md

Scenario 3: Bulk Content Audit

# Analyze multiple existing articles 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

# Prioritize rewrites based on content health scores

---

SEO Requirements

Every article must meet:

Content Quality:

• Minimum 2000 words (2500-3000+ preferred)
• Unique value vs. competitors
• Factually accurate and current
• Actionable advice for target audience
• Maintain brand voice

Keyword Optimization:

• 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 Elements:

• Meta title 50-60 characters
• Meta description 150-160 characters
• Proper H1>H2>H3 hierarchy

Readability:

• 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

Structure:

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

---

Best Practices

Before Writing:

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

During Writing:

• Follow the brief: Use research brief as your outline
• Natural keywords: Integrate keywords naturally, never force them
• Add value: Every section should provide actionable insights
• Use examples: Include real scenarios and use cases from your industry
• Cite sources: Link to statistics and data sources

After Writing:

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

---

FAQ

Q: Article doesn't sound like my brand?
A: Update context/brand-voice.md with more specific guidance, add more diverse examples to context/writing-examples.md.

Q: Keyword density too high or too low?
A: Check seo-guidelines.md target density (1-2%), use /optimize for specific keyword placement suggestions, use Keyword Mapper agent for distribution analysis.

Q: Agent can't find good internal links?
A: Update context/internal-links-map.md with current pages, organize by topic cluster for easier agent matching, provide more context about what each page covers.

Q: Content too similar to competitors?
A: Update differentiation opportunities in competitor-analysis.md, add your unique advantages to brand-voice.md and features.md, reference specific differentiation angles in /research command.

---

Summary

SEOMachine is not a generic AI writing tool, but an SEO workspace designed specifically for Claude Code.

Core Advantages:

• Fully automated workflow (research → write → optimize → publish)
• Data-driven decisions (GA4 + GSC + DataForSEO)
• Specialized agent analysis (10 agents auto-review)
• 24+ marketing skills (copywriting, CRO, strategy, etc.)
• Context-driven (brand voice, style guide, SEO standards)

Who It's For:

• Developers using Claude Code
• SEO content creators
• Marketing teams
• SaaS companies

Get Started:

git clone https://github.com/TheCraigHewitt/seomachine.git
cd seomachine
pip install -r data_sources/requirements.txt
claude-code .

Configure context files, run /research [topic], start creating!

---

Open Source:

• GitHub: https://github.com/TheCraigHewitt/seomachine
• Stars: 343 (as of 2026-03-08)
• Example: examples/castos/ (complete podcast hosting SaaS company case)