# Claude Code integration

TurboSEO includes a complete Claude Code workspace with 10 slash commands and 7 specialized agents for AI-assisted content creation.

## Setup

Copy the `.claude/` directory to your content project:

```bash
cp -r /path/to/turboseo/.claude your-project/
```

Or if using TurboSEO as a submodule or installed package, symlink it:

```bash
ln -s node_modules/turboseo/.claude .claude
# or
ln -s venv/lib/python3.11/site-packages/turboseo/.claude .claude
```

## Slash commands

### /write

Write a new SEO-optimized article that sounds human.

```
/write podcast monetization strategies
/write how to start a food blog
```

**What it does:**
1. Uses research brief from `research/` if available
2. Writes 2000-3000 word article following human writing rules
3. Runs `turboseo check` automatically
4. Revises if score < 80
5. Saves to `drafts/`

**Output:** Full article + meta title + meta description + human writing score

---

### /rewrite

Improve existing content to sound more human.

```
/rewrite drafts/podcast-guide.md
```

**What it does:**
1. Analyzes content with `turboseo check`
2. Identifies AI patterns
3. Rewrites problematic sections
4. Targets score of 85+

---

### /check-human

Run human writing analysis on a file.

```
/check-human drafts/article.md
```

Equivalent to `turboseo check drafts/article.md` but with richer output and inline suggestions.

---

### /analyze

Full SEO analysis with keyword tracking.

```
/analyze drafts/article.md -k "podcast hosting"
```

Shows weighted scores across all categories with actionable recommendations.

---

### /analyze-existing

Fetch and analyze a live URL.

```
/analyze-existing https://example.com/article
```

Useful for competitive analysis or auditing published content.

---

### /research

Gather background information on a topic.

```
/research podcast monetization 2024
```

Creates a research brief in `research/` with:
- Key points to cover
- Competitor analysis
- Keyword suggestions
- Unique angles

---

### /optimize

General optimization pass on content.

```
/optimize drafts/article.md
```

Addresses readability, structure, and SEO issues without full rewrite.

---

### /keywords

Detailed keyword analysis.

```
/keywords drafts/article.md -k "podcast hosting"
```

Shows density, placements, and stuffing risk.

---

### /readability

Analyze readability metrics.

```
/readability drafts/article.md
```

Shows Flesch scores, grade levels, and sentence analysis.

---

### /performance-review

Manual content audit checklist.

```
/performance-review
```

Interactive audit for published content performance.

## Agents

Agents are specialized AI personas with specific expertise. Use them with Claude Code's agent system.

### human-writer

**Purpose:** Rewrite content to eliminate AI patterns.

**Target:** Score 85+

**Process:**
1. Runs `turboseo check` on input
2. Identifies flagged issues
3. Rewrites each problematic section
4. Verifies improvement

**Key rules:**
- Never use banned AI vocabulary
- Avoid puffery patterns
- Be specific, not vague
- Cut unnecessary words

---

### seo-optimizer

**Purpose:** Improve SEO signals without hurting readability.

**Focus areas:**
- Keyword placement optimization
- Heading structure
- Internal linking opportunities
- Meta tag improvements

---

### content-analyzer

**Purpose:** Evaluate content quality and gaps.

**Analyzes:**
- Topic coverage
- Competitive positioning
- Missing sections
- Improvement opportunities

---

### meta-creator

**Purpose:** Generate optimized meta elements.

**Creates:**
- Meta titles (50-60 chars with keyword)
- Meta descriptions (150-160 chars)
- Schema markup suggestions
- Open Graph tags

---

### keyword-mapper

**Purpose:** Research and map keywords.

**Provides:**
- Primary keyword validation
- Secondary keyword suggestions
- Semantic variations
- Placement recommendations

---

### internal-linker

**Purpose:** Suggest internal linking opportunities.

**Analyzes:**
- Existing site structure (from `context/internal-links-map.md`)
- Anchor text opportunities
- Related content connections

---

### editor

**Purpose:** Final editorial pass.

**Focus:**
- Humanity score validation
- Engagement analysis
- Flow and transitions
- Final polish

## Directory structure

TurboSEO uses these directories for content workflow:

```
your-project/
├── .claude/
│   ├── commands/     # Slash command definitions
│   └── agents/       # Agent instructions
├── context/          # Reference files (brand voice, style guide)
├── topics/           # Topic ideas and briefs
├── research/         # Research notes
├── drafts/           # Work in progress
├── rewrites/         # Revised versions
└── published/        # Final content
```

## Context files

Place these in `context/` for better results:

### context/brand-voice.md

Define your brand's tone and style:

```markdown
# Brand Voice

## Tone
- Conversational but professional
- Direct, not preachy
- Helpful, not salesy

## Language
- Use "you" and "your"
- Avoid jargon unless necessary
- Short sentences preferred
```

### context/style-guide.md

Formatting and conventions:

```markdown
# Style Guide

## Formatting
- Sentence case for headings
- Em-dash sparingly (prefer commas)
- Oxford comma: yes

## Words
- "website" not "web site"
- "email" not "e-mail"
```

### context/internal-links-map.md

Your site's key pages for internal linking:

```markdown
# Internal Links

## Pillar Pages
- /podcast-hosting-guide -> "podcast hosting guide"
- /start-podcast -> "how to start a podcast"

## Related Topics
- /podcast-equipment -> "podcast equipment"
- /podcast-monetization -> "monetize your podcast"
```

## Workflow example

1. **Research topic:**
   ```
   /research podcast monetization strategies
   ```

2. **Write draft:**
   ```
   /write podcast monetization guide
   ```

3. **Check human score:**
   ```
   /check-human drafts/podcast-monetization-2024-01-15.md
   ```

4. **Fix AI patterns if needed:**
   ```
   /rewrite drafts/podcast-monetization-2024-01-15.md
   ```

5. **Final SEO check:**
   ```
   /analyze drafts/podcast-monetization-2024-01-15.md -k "podcast monetization"
   ```

6. **Move to published when ready**
