# 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.
Walkthrough: https://www.youtube.com/watch?v=Ncj7fGFbmEs
## 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
- [Claude Code](https://claude.com/claude-code) installed
- Anthropic API account
- [DataForSEO account](https://dataforseo.com)
### Installation
1. Clone this repository:
```bash
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:
```bash
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:
```bash
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
Before running Docker, configure `data_sources/config/.env` with your credentials.
```bash
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 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
**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
---
### Meta Creator
**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
---
### Performance
**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/GSC
- `cro_checker.py` - CRO best practices checklist validation
### Additional Analysis Modules
- `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
Run from repo root:
```bash
# 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**:
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
```
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
│ │ ├── keyword_analyzer.py
│ │ ├── seo_quality_rater.py
│ │ ├── content_length_comparator.py
│ │ ├── readability_scorer.py
│ │ ├── opportunity_scorer.py
│ │ ├── content_scorer.py
│ │ ├── engagement_analyzer.py
│ │ ├── social_research_aggregator.py
│ │ ├── competitor_gap_analyzer.py
│ │ ├── article_planner.py
│ │ ├── section_writer.py
│ │ ├── wordpress_publisher.py
│ │ ├── above_fold_analyzer.py
│ │ ├── cro_checker.py
│ │ ├── cta_analyzer.py
│ │ ├── landing_page_scorer.py
│ │ ├── landing_performance.py
│ │ └── trust_signal_analyzer.py
│ ├── config/ # API credentials (not in git)
│ ├── utils/ # Helper functions
│ ├── cache/ # Cached API responses
│ └── README.md # Setup instructions
├── config/ # Configuration files
│ └── competitors.example.json # Competitor config template
├── context/ # Configuration and guidelines
│ ├── brand-voice.md
│ ├── writing-examples.md
│ ├── style-guide.md
│ ├── seo-guidelines.md
│ ├── target-keywords.md
│ ├── internal-links-map.md
│ ├── competitor-analysis.md
│ └── cro-best-practices.md
├── wordpress/ # WordPress integration
│ ├── seo-machine-yoast-rest.php
│ ├── functions-snippet.php
│ └── README.md
├── topics/ # Raw topic ideas
├── research/ # Research briefs and analysis reports
├── drafts/ # Work in progress articles
├── review-required/ # Articles pending review
├── published/ # Final versions ready to publish
├── rewrites/ # Updated existing content
├── landing-pages/ # Landing page content
├── audits/ # Audit reports
└── README.md # This file
```
## Context Files (Important!)
The quality of your content depends on well-configured context files:
### `context/brand-voice.md`
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
---
### `context/writing-examples.md`
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
---
### `context/style-guide.md`
Editorial and formatting standards.
**Must include**:
- Grammar and mechanics rules
- Capitalization conventions
- Formatting standards
- Preferred terminology
**Purpose**: Maintains consistency across all content
---
### `context/seo-guidelines.md`
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
---
### `context/target-keywords.md`
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
---
### `context/internal-links-map.md`
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
---
### `context/competitor-analysis.md`
Competitive intelligence and content gaps.
**Must include**:
- Primary competitors
- Their content strategies
- Keyword gaps
- Differentiation opportunities
**Purpose**: Informs content strategy and competitive positioning
## Content Quality Standards
Every article must meet these requirements:
### Content
- [ ] 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
### SEO
- [ ] 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
- [ ] 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
- [ ] Examples and data included
## Best Practices
### Before Writing
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
### During Writing
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 scenarios and use cases from your industry
5. **Cite sources**: Link to statistics and data sources
### After Writing
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
### For Rewrites
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
## Workflow Examples
### Example 1: Creating New Content from Scratch
```
# 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
```
# 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
```
# 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
### Maximizing Content Quality
- **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 examples and scenarios from your industry
- **Answer questions**: Address "People Also Ask" questions from research
### SEO Optimization
- **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
### Workflow Efficiency
- **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
### Avoiding Common Mistakes
- ❌ 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
## Maintenance
### Weekly
- Add new topic ideas to `/topics/`
- Update `target-keywords.md` with new keyword opportunities
- Check for broken links in `internal-links-map.md`
### Monthly
- 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`
### Quarterly
- 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`
## Troubleshooting
### "Content doesn't sound like my brand"
- **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
### "Keyword density too high/low"
- **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
### "Internal links aren't relevant"
- **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
### "Articles too similar to competitors"
- **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
## Support & Contributions
### Getting Help
- Review this README thoroughly
- Check context files are properly configured
- Consult [Claude Code documentation](https://docs.claude.com/claude-code)
### Contributing
- Report issues via GitHub Issues
- Suggest improvements to commands or agents
- Share successful workflows or tips
## License
[Add your license information]
## Credits
Built with [Claude Code](https://claude.com/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
**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! 📝