CONTRIBUTING Copy Section

Contributing to SEO Machine

Thank you for your interest in improving SEO Machine! This document provides guidelines for contributing to the project.

How to Contribute Copy Chapter

Reporting Issues Copy Section

Suggesting Improvements Copy Section

For Commands:
- Propose new workflow commands in .claude/commands/
- Explain the use case and workflow
- Provide example command structure

For Agents:
- Suggest new specialized agents in .claude/agents/
- Define the agent's expertise and output format
- Show how it integrates with existing workflow

For Context Files:
- Recommend additions to context templates
- Share successful configurations
- Suggest improvements to guidelines

Submitting Changes Copy Section

1. Fork the Repository

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

2. Create a Feature Branch

git checkout -b feature/your-feature-name

3. Make Your Changes
- Follow existing file structure and conventions
- Update README.md if adding new features
- Test your changes thoroughly

4. Commit Your Changes

git add .
   git commit -m "Add feature: description of your changes"

5. Push and Create Pull Request

git push origin feature/your-feature-name

Code Style Guidelines Copy Chapter

Command Files (.claude/commands/) .claude/commands/)')" title="Copy section prompt for LLMs"> Copy Section

Agent Files (.claude/agents/) .claude/agents/)')" title="Copy section prompt for LLMs"> Copy Section

Context Files (context/) context/)')" title="Copy section prompt for LLMs"> Copy Section

Documentation Copy Section

Testing Your Contributions Copy Chapter

Before submitting:
1. Test the Command/Agent: Run it with real content
2. Verify Output: Ensure output matches expected format
3. Check Integration: Confirm it works with existing workflow
4. Update Documentation: Add usage examples to README.md
5. Test Edge Cases: Try with various content types and scenarios

Content Quality Standards Copy Chapter

Contributions should maintain high quality:
- Clarity: Instructions are easy to understand
- Completeness: All necessary information included
- Consistency: Matches existing style and structure
- Practicality: Provides real value to content creators
- Examples: Includes relevant examples

What We're Looking For Copy Chapter

High Priority:
- Improved command workflows
- New specialized agents for content optimization
- Better context file templates
- Enhanced SEO capabilities
- Time-saving automation features

Always Welcome:
- Bug fixes
- Documentation improvements
- Example content and workflows
- Context file best practices
- Integration with SEO tools

Please Discuss First:
- Major architectural changes
- New dependencies
- Breaking changes to existing workflows
- Significant additions to context templates

Questions? Copy Chapter

- Open a GitHub Issue with "Question:" prefix
- Review existing documentation in README.md
- Check Claude Code documentation

License Copy Chapter

By contributing, you agree that your contributions will be licensed under the same license as the project.

---

Thank you for helping make SEO Machine better! 🎙️📝

---

README Copy Section

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

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

Prerequisites Copy Section

Installation Copy Section

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

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.

Docker Setup Copy Chapter

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

Creating New Content Copy Section

#### 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 Copy Section

#### 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 Copy Chapter

/research [topic] /research [topic]')" title="Copy section prompt for LLMs"> Copy Section

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] /write [topic]')" title="Copy section prompt for LLMs"> Copy Section

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] /rewrite [topic]')" title="Copy section prompt for LLMs"> Copy Section

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 [URL or file]')" title="Copy section prompt for LLMs"> Copy Section

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] /optimize [file]')" title="Copy section prompt for LLMs"> Copy Section

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-draft [file]')" title="Copy section prompt for LLMs"> Copy Section

---

/article [topic] /article [topic]')" title="Copy section prompt for LLMs"> Copy Section

---

/priorities /priorities')" title="Copy section prompt for LLMs"> Copy Section

---

/scrub [file] /scrub [file]')" title="Copy section prompt for LLMs"> Copy Section

---

Research Commands Copy Section

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

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

Specialized agents that automatically analyze content and provide expert recommendations.

Content Analyzer (NEW!) Copy Section

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

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

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

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

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

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

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

Provides:
- 10+ headline variations using proven formulas
- Conversion potential scoring
- A/B testing strategies
- Audience-specific headline options

---

CRO Analyst Copy Section

Analyzes:
- Above-the-fold effectiveness
- CTA quality and distribution
- Trust signal presence
- Friction points
- Page structure

---

Landing Page Optimizer Copy Section

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

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

Integration with Analytics Copy Section

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!) Copy Section

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

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/GSC
- cro_checker.py - CRO best practices checklist validation

Additional Analysis Modules Copy Section

- opportunity_scorer.py - 8-factor opportunity scoring for content prioritization
- content_scorer.py - 5-dimension content quality scoring (humanity, specificity, structure, SEO, readability)
- engagement_analyzer.py - Content engagement pattern analysis
- competitor_gap_analyzer.py - Competitive content gap identification
- article_planner.py - Data-driven article planning
- section_writer.py - Section-level content guidance
- social_research_aggregator.py - Social media research aggregation

Python Research Scripts Copy Section

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

Publishing uses the WordPress REST API with a custom MU-plugin that exposes Yoast SEO fields.

Setup:
1. Install wordpress/seo-machine-yoast-rest.php as an MU-plugin on your WordPress site
2. Add wordpress/functions-snippet.php to your theme's functions.php
3. 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 Copy Chapter

/ Detailed source-code truncated for AI context efficiency. /

Context Files (Important!) Copy Chapter

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

context/brand-voice.md context/brand-voice.md')" title="Copy section prompt for LLMs"> Copy Section

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

---

context/writing-examples.md context/writing-examples.md')" title="Copy section prompt for LLMs"> Copy Section

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

---

context/style-guide.md context/style-guide.md')" title="Copy section prompt for LLMs"> Copy Section

Must include:
- Grammar and mechanics rules
- Capitalization conventions
- Formatting standards
- Preferred terminology

Purpose: Maintains consistency across all content

---

context/seo-guidelines.md context/seo-guidelines.md')" title="Copy section prompt for LLMs"> Copy Section

Includes:
- Content length requirements
- Keyword optimization rules
- Meta element standards
- Link strategy guidelines
- Readability requirements

Purpose: Ensures all content meets SEO standards

---

context/target-keywords.md context/target-keywords.md')" title="Copy section prompt for LLMs"> Copy Section

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

Purpose: Guides keyword targeting for new content

---

context/internal-links-map.md context/internal-links-map.md')" title="Copy section prompt for LLMs"> Copy Section

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

---

context/competitor-analysis.md context/competitor-analysis.md')" title="Copy section prompt for LLMs"> Copy Section

Must include:
- Primary competitors
- Their content strategies
- Keyword gaps
- Differentiation opportunities

Purpose: Informs content strategy and competitive positioning

Content Quality Standards Copy Chapter

Every article must meet these requirements:

Content Copy Section

SEO Copy Section

Readability Copy Section

Structure Copy Section

Best Practices Copy Chapter

Before Writing Copy Section

During Writing Copy Section

After Writing Copy Section

For Rewrites Copy Section

Workflow Examples Copy Chapter

Example 1: Creating New Content from Scratch Copy Section

Step 1: Add topic idea

Create file in topics/ directory with initial thoughts
Step 2: Research the topic

/research content marketing strategies
Step 3: Review research brief

Read research/brief-content-marketing-strategies-[date].md
Step 4: Write article

/write content marketing 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/content-marketing-strategies-[date].md
Step 8: Publish to WordPress (optional)

/publish-draft drafts/content-marketing-strategies-[date].md

Example 2: Updating Existing Content Copy Section

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

Example 3: Quick Content Audit Copy Section

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

Tips & Tricks Copy Chapter

Maximizing Content Quality Copy Section

SEO Optimization Copy Section

Workflow Efficiency Copy Section

Avoiding Common Mistakes Copy Section

Maintenance Copy Chapter

Weekly Copy Section

Monthly Copy Section

Quarterly Copy Section

Troubleshooting Copy Chapter

"Content doesn't sound like my brand" Copy Section

"Keyword density too high/low" Copy Section

"Internal links aren't relevant" Copy Section

"Articles too similar to competitors" Copy Section

Support & Contributions Copy Chapter

Getting Help Copy Section

Contributing Copy Section

License Copy Chapter

[Add your license information]

Credits Copy Chapter

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.

Examples & Community Copy Chapter

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

---