Quick Start Guide

Get SEO Machine running and create your first article in 10 minutes ⚡

Step 1: Install Dependencies (2 minutes)

Install the Python dependencies for analysis modules:

pip install -r data_sources/requirements.txt

If you haven’t completed the full installation yet, see the Installation Guide for detailed setup instructions.

Step 2: Configure Context Files (5 minutes)

SEO Machine needs to understand your brand before creating content. Fill out these 3 essential files:

1. Brand Voice (`context/brand-voice.md`)

Define how your brand communicates:

# Brand Voice

## Voice Pillars

1. **Authentic & Honest**: We speak plainly about challenges and solutions
2. **Empowering**: We help creators take control of their content
3. **Technical but Accessible**: We explain complex topics in simple terms

## Tone Guidelines

- **Educational Content**: Informative, supportive, patient
- **Product Content**: Confident, clear, benefit-focused
- **Comparison Content**: Objective, data-driven, fair

## Do's and Don'ts

✅ Use "you" and "your" (direct address)
✅ Use contractions (we're, you'll, it's)
✅ Include real examples and scenarios

❌ Avoid jargon without explanation
❌ Don't make unsubstantiated claims
❌ Never speak negatively about competitors

Quick Start Tip: Check examples/castos/brand-voice.md in the repository for a complete real-world example from a podcast hosting SaaS company.

2. Features (`context/features.md`)

List your product or service features:

# Product Features

## Core Features

- **Unlimited Uploads**: Upload unlimited audio files of any length
- **Private Podcasting**: Create password-protected private shows
- **Built-in Website**: Customizable podcast website included
- **Advanced Analytics**: Detailed listener analytics and insights
- **Distribution Tools**: Publish to all major podcast directories

## Key Differentiators

- Unlimited everything (no hidden limits on bandwidth or storage)
- Superior audio quality (320kbps vs industry standard 128kbps)
- White-glove migration service included
- 24/7 support with real humans

3. Writing Examples (`context/writing-examples.md`)

Copy 3-5 of your best existing blog posts:

# Writing Examples

## Example 1: [Article Title]

**URL**: https://yoursite.com/blog/article-name

**What makes this great**:
- Opens with a compelling scenario, not a definition
- Uses specific numbers and data throughout
- Includes real customer examples
- Natural product mentions without being salesy

**Full Content**:

[Paste the complete article here]

---

## Example 2: [Article Title]

...

Include the full content of each example article, not just excerpts. The AI learns your style by reading complete pieces.

Optional But Recommended

Internal Links Map (context/internal-links-map.md)

Map your key pages for strategic internal linking:

# Internal Links Map

## Product Pages
- [Podcast Hosting](https://yoursite.com/hosting) - Main hosting service
- [Private Podcasting](https://yoursite.com/private) - Private podcast feature
- [Pricing](https://yoursite.com/pricing) - Pricing plans

## Pillar Content
- [Complete Podcasting Guide](https://yoursite.com/blog/podcasting-guide)
- [How to Start a Podcast](https://yoursite.com/blog/start-podcast)

## Topic Clusters

### Podcast Growth
- Growing Your Audience
- Podcast Marketing Strategies
- Monetization Guide

Target Keywords (context/target-keywords.md)

Organize your keyword research by topic cluster:

# Target Keywords

## Cluster: Podcast Hosting

**Pillar Keyword**: podcast hosting (12,000/mo, Medium)

**Cluster Keywords**:
- best podcast hosting (5,400/mo, High)
- podcast hosting platforms (2,900/mo, Medium)
- podcast hosting comparison (1,600/mo, Medium)

**Long-tail Variations**:
- best podcast hosting for beginners (720/mo, Low)
- unlimited podcast hosting (480/mo, Low)

Step 3: Create Your First Article (3 minutes)

Now you’re ready to create content!

Open Claude Code

claude-code .

Research a Topic

Start with comprehensive research:

/research [your topic]

/research podcast editing software

What this does:

Performs keyword research for the topic
Analyzes top 10 competitors in search results
Identifies content gaps and opportunities
Creates a comprehensive research brief
Saves to /research/brief-[topic]-[date].md

Review the research brief before writing. It contains the outline, competitor insights, and SEO strategy for your article.

Write the Article

Create a complete, SEO-optimized article:

/write [your topic]

/write podcast editing software

What this does:

Creates a 2,000-3,000+ word article
Maintains your brand voice (from brand-voice.md)
Integrates keywords naturally
Includes internal and external links
Provides meta elements (title, description, keywords)
Automatically triggers optimization agents
Saves to /drafts/[topic]-[date].md

The /write command automatically invokes several specialized agents after creating the article:

Content Analyzer: Search intent, keyword density, length comparison
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

All agent reports are saved to the /drafts/ directory alongside your article.

Check Your Results

Your /drafts/ directory now contains:

drafts/
├── podcast-editing-software-2025-03-04.md          # Main article
├── content-analysis-podcast-editing-software-2025-03-04.md
├── seo-report-podcast-editing-software-2025-03-04.md
├── meta-options-podcast-editing-software-2025-03-04.md
├── link-suggestions-podcast-editing-software-2025-03-04.md
└── keyword-analysis-podcast-editing-software-2025-03-04.md

That’s It! 🎉

You now have:

Complete Article

2,000+ words of SEO-optimized content in your brand voice

Meta Elements

Optimized title, description, and keywords ready for publishing

SEO Analysis

Comprehensive SEO optimization report with recommendations

Multiple Options

Multiple meta title/description variations to choose from

Next Steps

To Publish Your Article

Review the Article

Open the article in /drafts/[topic]-[date].md and read through it

Review Agent Feedback

Check the analysis reports for any high-priority recommendations

Make Edits

Apply any necessary improvements based on agent feedback

Final Optimization

Run /optimize [file] for a final SEO audit:

/optimize drafts/podcast-editing-software-2025-03-04.md

Publish

Copy to your CMS or use /publish-draft [file] to publish directly to WordPress

To Improve Content Quality

The more context you provide, the better your content will be:

Add More Writing Examples

Add 2-3 more examples to context/writing-examples.md. The AI learns your style by studying real examples.

Refine Your Brand Voice

Update context/brand-voice.md with more specific guidance about tone, terminology, and messaging.

Map Internal Links

Fill out context/internal-links-map.md with your key pages. This enables strategic internal linking in every article.

Add Target Keywords

Organize your keyword research in context/target-keywords.md by topic cluster for better content planning.

Configure SEO Guidelines

Adjust context/seo-guidelines.md to match your specific SEO requirements.

Common Commands Reference

Here are the most frequently used commands:

Core Workflow

/research [topic]           # Research before writing
/write [topic]              # Create new article
/optimize [file]            # Final SEO polish
/scrub [file]               # Remove AI watermarks

Research Commands

/research-serp [keyword]    # SERP analysis for keyword
/research-gaps              # Competitor content gaps
/research-trending          # Trending topic opportunities
/research-topics            # Topic cluster research
/research-performance       # Performance-based priorities

Landing Page Commands

/landing-write [topic]      # Create landing page
/landing-audit [file]       # Audit for CRO issues
/landing-research [topic]   # Research positioning
/landing-competitor [URL]   # Analyze competitor landing page

Analysis & Strategy

/performance-review         # Analytics-driven priorities
/priorities                 # Content prioritization matrix

Real-World Example

Want to see a complete example? Check the examples/castos/ directory in the repository:

examples/castos/
├── brand-voice.md          # Complete brand voice guide
├── features.md             # Product features
├── writing-examples.md     # 5 real blog post examples
├── internal-links-map.md   # Internal linking strategy
└── target-keywords.md      # Keyword research by cluster

This shows how a real podcast hosting SaaS company uses SEO Machine for their content.

Troubleshooting

Content doesn't sound like my brand

Problem: Articles don’t match your brand voiceSolution:

Add more specific guidance to context/brand-voice.md
Include more diverse examples in context/writing-examples.md
Reference specific examples when using commands: /write [topic] using style from example 2

Keywords feel forced or unnatural

Problem: Keyword integration sounds roboticSolution:

Review context/seo-guidelines.md and adjust target density (1-2% recommended)
Use /optimize [file] to get specific keyword placement suggestions
Run the Keyword Mapper agent for distribution analysis

Internal links aren't relevant

Problem: Suggested internal links don’t fit the contentSolution:

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

Articles too similar to competitors

Problem: Content doesn’t stand out from competitorsSolution:

Update context/competitor-analysis.md with differentiation opportunities
Add your unique advantages to context/features.md
Use the research phase to identify content gaps: /research [topic]

Pro Tips

Always research first: Run /research [topic] before /write [topic]. Research briefs provide the foundation for high-quality, competitive content.

Review agent feedback: The automated agents provide valuable insights. Don’t skip reading the analysis reports in your /drafts/ directory.

Iterate on context files: Your context files are living documents. Update them regularly as your brand voice evolves and you publish more content.

Use the examples directory: Study examples/castos/ to see how a real company configured their context files for production content.

Need Help?

Full Documentation

Read the complete README for advanced features

Configuration Guide

Deep dive into context files and settings

API Setup

Configure Google Analytics and Search Console

Report Issues

Found a bug? Report it on GitHub Issues

Ready to scale your content? With SEO Machine configured, you can create high-quality, SEO-optimized articles in a fraction of the time it takes manually. Happy writing! 📝

Getting Started

Core Concepts

Workflows

Commands

Advanced Commands

Agents

Data Sources

Integrations

​Quick Start Guide

​Step 1: Install Dependencies (2 minutes)

​Step 2: Configure Context Files (5 minutes)

​1. Brand Voice (context/brand-voice.md)

​2. Features (context/features.md)

​3. Writing Examples (context/writing-examples.md)

​Optional But Recommended

​Step 3: Create Your First Article (3 minutes)

​Open Claude Code

​Research a Topic

​Write the Article

​Check Your Results

​That’s It! 🎉

Complete Article

Meta Elements

SEO Analysis

Multiple Options

​Next Steps

​To Publish Your Article

​To Improve Content Quality

​Common Commands Reference

​Core Workflow

​Research Commands

​Landing Page Commands

​Analysis & Strategy

​Real-World Example

​Troubleshooting

​Pro Tips

​Need Help?

Full Documentation

Configuration Guide

API Setup

Report Issues

Build docs developers (and LLMs) love

Quick Start Guide

Step 1: Install Dependencies (2 minutes)

Step 2: Configure Context Files (5 minutes)

1. Brand Voice (`context/brand-voice.md`)

2. Features (`context/features.md`)

3. Writing Examples (`context/writing-examples.md`)

Optional But Recommended

Step 3: Create Your First Article (3 minutes)

Open Claude Code

Research a Topic

Write the Article

Check Your Results

That’s It! 🎉

Next Steps

To Publish Your Article

To Improve Content Quality

Common Commands Reference

Core Workflow

Research Commands

Landing Page Commands

Analysis & Strategy

Real-World Example

Troubleshooting

Pro Tips

Need Help?