Skip to main content
Context files are the foundation of SEO Machine’s content generation. They define your brand voice, writing style, SEO guidelines, and product information. All content generated by SEO Machine references these files to ensure consistency across your blog.

​
What Are Context Files?

Context files are markdown templates located in the context/ directory that define:
  • Brand voice and messaging - Your unique tone, personality, and key messages
  • Style guidelines - Grammar, formatting, and editorial standards
  • SEO best practices - Keyword optimization, structure, and technical SEO requirements
  • Product features - What your product does and how to position it
  • Internal linking strategy - Priority pages for internal links
  • Competitive intelligence - How to differentiate from competitors
  • CRO guidelines - Conversion optimization best practices

​
Core Context Files

​
brand-voice.md

Defines your brand’s unique voice, tone, and messaging framework. What it contains:
  • Voice pillars (3-5 characteristics that define your brand personality)
  • Tone guidelines by content type
  • Core brand messages
  • Value propositions for each customer segment
  • Writing style preferences
  • Audience understanding
When it’s used: Every piece of content generated references this file to maintain consistent voice and messaging. Learn more →

​
style-guide.md

Establishes grammar, formatting, and editorial standards for all content. What it contains:
  • Grammar and mechanics rules
  • Word choice preferences
  • Formatting standards (bold, italics, lists)
  • Content structure templates
  • Date/time formats
  • Brand-specific terminology
When it’s used: During content creation and editing to ensure consistent formatting and style. Learn more →

​
seo-guidelines.md

Defines SEO optimization standards for maximum search visibility. What it contains:
  • Content length requirements
  • Keyword optimization rules
  • Heading hierarchy standards
  • Meta element guidelines
  • Internal and external linking strategy
  • Readability requirements
  • Featured snippet optimization
When it’s used: During content planning, writing, and optimization phases. Learn more →

​
features.md

Documents your product features and how to position them in content. What it contains:
  • Product features and capabilities
  • Value propositions
  • Use cases and benefits
  • Competitive differentiators
  • Technical specifications
When it’s used: When content mentions your product or needs to position features naturally. Defines your site structure and internal linking priorities. What it contains:
  • Pillar content pages
  • Priority linking targets
  • Topic clusters
  • Site architecture
  • Anchor text suggestions
When it’s used: During content optimization to add strategic internal links.

​
competitor-analysis.md

Captures competitive intelligence to inform content strategy. What it contains:
  • Key competitors
  • Their positioning and messaging
  • Content gaps and opportunities
  • Differentiation strategies
When it’s used: During content planning and competitive research.

​
cro-best-practices.md

Provides conversion optimization guidelines for content. What it contains:
  • CTA best practices
  • Lead generation strategies
  • Landing page optimization
  • Conversion-focused writing techniques
When it’s used: When optimizing content for conversions and lead generation.

​
Template vs. Configured Files

​
Template Files (~/workspace/source/context/)

The context/ directory contains template files with instructions and placeholders: 
# [YOUR COMPANY] Brand Voice & Messaging

### 1. [VOICE PILLAR NAME]
- **What it means**: [Explain the core concept]
- **How it sounds**: [Describe the execution]
These templates include:
  • Instruction comments explaining what to fill in
  • Placeholder text in [BRACKETS]
  • Examples showing the format
  • Guidance on best practices

​
Configured Example (~/workspace/source/examples/castos/)

The examples/castos/ directory shows completed context files for a real podcast hosting company: 
# Castos Brand Voice & Messaging

### 1. Professional Yet Approachable
- **What it means**: We're experts in podcasting, but we're not stuffy
- **How it sounds**: Conversational, warm, knowledgeable
Use the Castos example as a reference when filling out your own context files.

​
How to Configure Context Files

​
Step 1: Start with Templates

Copy the template files from context/ to your working directory: 
cp context/brand-voice.md context/my-brand-voice.md

​
Step 2: Review the Example

Examine the Castos example to see how a complete context file looks: 
cat examples/castos/brand-voice.md

​
Step 3: Fill in Your Details

Replace all [BRACKETED] placeholders with your specific information:
  • Replace [YOUR COMPANY] with your company name
  • Fill in voice pillars with your brand characteristics
  • Define tone guidelines for your audience
  • Add your product-specific terminology

​
Step 4: Remove Instructions

Delete instruction comments marked with <!-- INSTRUCTIONS: ... -->

​
Step 5: Test with Content

Generate sample content to ensure your context files produce the desired output: 
/write "Test Article Topic"
Review the generated content and refine your context files as needed.

​
Context File Best Practices

​
Be Specific

❌ Vague: “Be professional” ✅ Specific: “Professional yet approachable - like an experienced podcaster helping a friend succeed”

​
Provide Examples

Every guideline should include concrete examples: 
**Example**: "Podcast hosting doesn't have to be complicated."
**Avoid**: "Our enterprise-grade solution provides robust functionality."

​
Define What NOT to Do

It’s equally important to define what to avoid: 
- **Avoid**: Overly technical jargon without explanation
- **Avoid**: Corporate-speak and buzzwords
- **Avoid**: Making podcasting seem harder than it is

​
Keep Files Updated

Context files should evolve as your brand and strategy develop:
  • Update when brand messaging changes
  • Add new terminology as your product evolves
  • Refine based on content performance
  • Document lessons learned from successful content

​
Reference Real Content

Include examples from your best-performing content: 
**Excellent Example:**
"Podcast hosting doesn't have to be complicated. Here's what you
actually need to know."

**Why this works:**
- Direct and conversational
- Promises simplicity
- Addresses reader pain point

​
Context Files in the Content Pipeline

Context files are referenced at multiple stages:

​
1. Research Phase

The research commands reference context files to understand:
  • Target keywords and topics
  • Competitive positioning
  • Brand messaging to incorporate

​
2. Writing Phase

The write command uses context files to:
  • Match your brand voice
  • Follow style guidelines
  • Apply SEO best practices
  • Position product features naturally

​
3. Optimization Phase

The optimization agents reference context files to:
  • Check keyword optimization against SEO guidelines
  • Add internal links from link map
  • Ensure meta elements follow standards
  • Verify voice and tone consistency

​
4. Rewriting Phase

The rewrite command uses context files to:
  • Update content while maintaining brand voice
  • Improve SEO based on current guidelines
  • Refresh examples and statistics

​
Advanced Context Configuration

​
Multiple Brand Voices

For companies with multiple brands or product lines:
  1. Create subdirectories in context/: 
    context/
├── brand-a/
│   ├── brand-voice.md
│   └── features.md
└── brand-b/
    ├── brand-voice.md
    └── features.md
  2. Specify which context to use when running commands

​
Industry-Specific Templates

Create specialized context files for different content types:
  • context/technical-guides.md - Voice for technical documentation
  • context/executive-content.md - Tone for C-level audience
  • context/beginner-content.md - Style for introductory content

​
Dynamic Context Updates

Use version control to track context file changes: 
cd context/
git log brand-voice.md
This helps you understand how your brand voice has evolved over time.

​
Troubleshooting

​
Content Doesn’t Match Brand Voice

Problem: Generated content doesn’t sound like your brand. Solution:
  1. Review your brand-voice.md for specificity
  2. Add more examples of your voice in action
  3. Define what to avoid more clearly
  4. Reference your best-performing content as examples

​
Inconsistent Formatting

Problem: Content formatting varies between articles. Solution:
  1. Make style-guide.md more prescriptive
  2. Provide clear formatting examples
  3. Document all capitalization and punctuation rules
  4. Create templates for common content structures

​
SEO Guidelines Not Followed

Problem: Content doesn’t meet SEO standards. Solution:
  1. Review seo-guidelines.md for completeness
  2. Ensure keyword requirements are clearly stated
  3. Add specific examples of proper optimization
  4. Run the SEO Optimizer agent after writing

​
Next Steps

Brand Voice Configuration

Configure your unique brand voice and messaging

Style Guide Setup

Define grammar and formatting standards

SEO Guidelines

Set up SEO optimization requirements

Environment Variables

Configure API credentials and settings

Build docs developers (and LLMs) love

Get started for freeTalk to us