---
name: seo-context
description: Manage per-project context files (brand voice, keywords, guidelines). Each website has its own context/ folder in the website repo.
---

# 📝 SEO Context - Per-Project Configuration

**Skill Name:** `seo-context`  
**Category:** `quick`  
**Load Skills:** `[]`

---

## 🚀 Purpose

Manage context files for each website project:

- ✅ **brand-voice.md** - Brand voice, tone, messaging (Thai + English)
- ✅ **target-keywords.md** - Keyword clusters by intent
- ✅ **seo-guidelines.md** - SEO requirements (Thai-specific)
- ✅ **internal-links-map.md** - Key pages for internal linking
- ✅ **data-services.json** - Analytics service configurations
- ✅ **style-guide.md** - Writing style, formality levels

**Location:** Each website has its own `context/` folder in the repo root.

**Use Cases:**
1. Create context files for new website project
2. Update context from existing content
3. Analyze current brand voice from published content
4. Generate keyword clusters from performance data
5. Export/import context between projects

---

## 📁 Context File Structure

```
website-name/
└── context/
    ├── brand-voice.md           # Brand voice, tone, formality
    ├── target-keywords.md       # Keyword clusters, search intent
    ├── seo-guidelines.md        # Thai SEO requirements
    ├── internal-links-map.md    # Priority pages for linking
    ├── data-services.json       # Analytics configurations
    └── style-guide.md           # Writing style, examples
```

---

## 🔧 Context File Templates

### **brand-voice.md**

```markdown
# Brand Voice & Messaging

## Voice Pillars

### 1. เป็นกันเอง (Casual/Friendly)
- **What it means**: พูดเหมือนเพื่อนช่วยเพื่อน ไม่ทางการเกินไป
- **Example**: "มาเริ่ม podcast กันเลย! ไม่ต้องรอให้พร้อม 100%"
- **Avoid**: ภาษาทางการแบบเอกสารราชการ

### 2. น่าเชื่อถือ (Trustworthy)
- **What it means**: ให้ข้อมูลที่ถูกต้อง มีหลักฐานรองรับ
- **Example**: "จากการทดสอบ 10+ แพลตฟอร์ม เราพบว่า..."
- **Avoid**: อ้างอิงไม่มีแหล่งที่มา

## Tone Guidelines

**General Tone**: เป็นกันเอง แต่ยังคงความน่าเชื่อถือ

**Content Types**:
- How-To Guides: สอนเป็นขั้นตอน ใช้ภาษาง่ายๆ
- Review Content: เปรียบเทียบตรงไปตรงมา มีข้อมูลสนับสนุน
- News/Updates: กระชับ ได้ใจความ

## Formality Level

**Default**: ปกติ (Normal) - ผสมกันเองและทางการตามเหมาะสม

**For Social Media**: กันเอง (Casual) - ใช้คำฟุ่มเฟือยได้บ้าง

**For Blog**: ปกติ (Normal) - อ่านง่ายแต่ยังคงความน่าเชื่อถือ
```

### **target-keywords.md**

```markdown
# Target Keywords

## Primary Keyword Clusters

### Cluster: Podcast Hosting

**Intent**: Commercial Investigation

**Keywords (Thai)**:
- บริการ podcast
- host podcast
- แพลตฟอร์ม podcast
- podcast hosting ที่ดีที่สุด

**Keywords (English)**:
- podcast hosting
- best podcast platform
- podcast host

**Search Volume**: 2,900/month (TH)

**Difficulty**: Medium

## Secondary Clusters

### Cluster: Podcast Equipment

[Similar structure]
```

### **seo-guidelines.md**

```markdown
# SEO Guidelines (Thai-Specific)

## Content Requirements

### Word Count
- **Thai**: 1,500-3,000 words
- **English**: 2,000-3,000 words

### Keyword Density
- **Thai**: 1.0-1.5%
- **English**: 1.5-2.0%

### Readability
- **Thai Grade Level**: ม.6-ม.12
- **Formality**:Auto-detect from brand-voice.md

## Meta Elements

### Title
- Length: 50-60 characters
- Must include primary keyword
- Thai-friendly (no truncation issues)

### Description
- Length: 150-160 characters
- Include CTA
- Thai or English matching content language

## URL Slug
- Format: lowercase-with-hyphens
- Thai: Keep Thai or use transliteration
- Max 5 words
```

### **data-services.json**

```json
{
  "ga4": {
    "enabled": true,
    "property_id": "G-XXXXXXXXXX",
    "credentials_path": "./credentials/ga4.json"
  },
  "gsc": {
    "enabled": true,
    "site_url": "https://yoursite.com",
    "credentials_path": "./credentials/gsc.json"
  },
  "dataforseo": {
    "enabled": false,
    "login": "your_login",
    "password": "your_password"
  },
  "umami": {
    "enabled": true,
    "api_url": "https://analytics.yoursite.com",
    "api_key": "your_api_key"
  }
}
```

---

## 🔄 Workflows

### **Workflow 1: Create Context for New Project**

```python
Input: Website name, industry, target audience
Process:
  1. Create context/ folder
  2. Generate brand-voice.md from industry standards
  3. Create target-keywords.md with initial research
  4. Set up seo-guidelines.md with Thai-specific rules
  5. Create empty data-services.json
Output:
  - Complete context/ folder structure
  - Ready for customization
```

### **Workflow 2: Analyze Existing Content**

```python
Input: Website URL or content files
Process:
  1. Scrape published content
  2. Analyze brand voice (formality, tone)
  3. Extract keyword usage
  4. Identify top-performing topics
  5. Update context files
Output:
  - Updated brand-voice.md (data-driven)
  - target-keywords.md with actual usage
  - Recommendations
```

---

## 📁 Commands

### **Create Context for New Project:**

```bash
python3 skills/seo-context/scripts/context_manager.py \
  --create \
  --project "./my-website" \
  --industry "podcast" \
  --audience "Thai podcasters" \
  --formality "normal"
```

### **Analyze Existing Content:**

```bash
python3 skills/seo-context/scripts/context_manager.py \
  --analyze \
  --project "./my-website" \
  --content-path "./published-articles/" \
  --language th
```

### **Update from Performance Data:**

```bash
python3 skills/seo-context/scripts/context_manager.py \
  --update-keywords \
  --project "./my-website" \
  --gsc-data "./gsc-export.csv"
```

---

## ⚙️ Environment Variables

**None required** - all configuration is per-project in context files.

---

## 📊 Output Examples

### **Create Context Output:**

```
✅ Context created for: my-website
📁 Location: ./my-website/context/

Created files:
  ✓ brand-voice.md (industry: podcast, formality: normal)
  ✓ target-keywords.md (3 initial clusters)
  ✓ seo-guidelines.md (Thai-specific)
  ✓ internal-links-map.md (empty, ready to populate)
  ✓ data-services.json (all services disabled)
  ✓ style-guide.md (templates)

Next steps:
  1. Customize brand-voice.md with your actual voice
  2. Add target keywords based on your research
  3. Configure analytics services in data-services.json
```

### **Analyze Content Output:**

```
📊 Analyzing existing content...

Found 25 articles (Thai: 18, English: 7)

Brand Voice Analysis:
  - Formality: 65% Normal, 30% Casual, 5% Formal
  - Recommended: ปกติ (Normal)
  - Tone: เป็นกันเอง, น่าเชื่อถือ

Top Keywords:
  1. บริการ podcast (42 occurrences)
  2. podcast hosting (38 occurrences)
  3. แพลตฟอร์ม podcast (25 occurrences)

Recommendations:
  • เพิ่มคำหลัก "podcast hosting" ใน H2 มากขึ้น
  • รักษาระดับความเป็นกันแบบนี้ไว้
  • เพิ่ม internal links ระหว่างบทความ podcast

✅ Context files updated
```

---

## ✅ Context File Checklist

For each project, ensure:

- [ ] **brand-voice.md** - Voice pillars, tone guidelines, formality level
- [ ] **target-keywords.md** - At least 3 keyword clusters with search intent
- [ ] **seo-guidelines.md** - Thai word count, density, readability targets
- [ ] **internal-links-map.md** - Top 10 pages to link to
- [ ] **data-services.json** - At least one analytics service configured
- [ ] **style-guide.md** - Writing examples (good and bad)

---

## 🔄 Integration with Other Skills

- **seo-multi-channel:** Loads brand voice for content generation
- **seo-analyzers:** Uses seo-guidelines for quality scoring
- **seo-data:** Reads data-services.json for analytics connections
- **website-creator:** Context in website repo root

---

**Use this skill when you need to set up or update context files for a website project.**

**Each website should have its own context/ folder with all configuration files.**