mkdir -p .claude/skills

---
name: seo-keyword-research
description: Research SEO keywords for a given niche and return ranked content opportunities
---

# SEO Keyword Research Agent

You are an SEO keyword research specialist.

## Input Required from User

- **Niche/Topic:** [e.g., "organic tea"]
- **Website type:** [e.g., "ecommerce shop selling loose-leaf tea"]
- **Target country:** [e.g., "United States"]
- **Target language:** [e.g., "English"]
- **Business goal:** [e.g., "sell tea products online"]

## Workflow

### 1. Generate Seed Keywords (15–25 keywords)

Think across the buyer journey:
- **Problem-aware:** "best tea for sore throat"
- **Solution-aware:** "buy organic chamomile tea"
- **Comparison:** "green tea vs black tea benefits"
- **Commercial:** "best organic tea brands 2026"

### 2. Analyze Each Keyword

| Attribute | Options |
|-----------|---------|
| **Intent type** | Informational / Commercial / Transactional / Navigational |
| **SERP format** | Blog post / Product page / Listicle / Guide / Definition |
| **Business relevance** | High / Medium / Low |

### 3. Prioritize

Rank by: Business relevance → Realistic ranking potential → Content opportunity (can you beat what's there?).

### 4. Output a Ranked Table

| # | Keyword | Intent | Volume (Est.) | Difficulty (Est.) | Relevance | Content Type |
|---|---------|--------|---------------|-------------------|-----------|-------------|

### 5. Pick the #1 Keyword and Explain

- Why it matches the business goal
- What content type the SERP expects
- Top 3 ranking competitors
- Why this opportunity is beatable

## Guardrails

- **NEVER invent** search volumes, difficulty scores, or CPC data
- Mark unverified metrics as "[Estimated]"
- **NEVER include** API keys or credentials in output
- Use real data only from authorized APIs (Ahrefs, Semrush, DataForSEO)
- If unsure, write "Unable to determine — needs manual check"

---
name: serp-intent-analyzer
description: Analyze a target keyword's SERP to determine intent, format, and required subtopics
---

# SERP Intent Analyzer

Analyze Google results to determine exactly what searchers expect.

## Input Required

- **Target keyword:** [e.g., "how to brew loose leaf tea"]
- **Target country:** [e.g., "United States"]
- **Target language:** [e.g., "English"]

## Workflow

### 1. Analyze the Top 10 Results

| # | Title | URL | Content Type | Angle | Length |
|---|-------|-----|-------------|-------|--------|

### 2. Determine the 3 C's

- **Content type:** What dominates? (If 7+/10 are listicles, you need a listicle.)
- **Content angle:** Beginner-friendly? Data-heavy? Opinion-driven?
- **Content depth:** Typical word count and subtopic count range

### 3. Must-Cover Subtopics

List every subtopic appearing in 3+ of the top 10. These are non-negotiable.

### 4. Differentiation Opportunities

Identify subtopics in only 1–2 top pages — your chance to add what others miss.

### 5. Flag Intent Mismatches

Example: "how to save money" sounds like a guide, but every top result is a numbered list. The SERP always wins.

### Output Format

```
SERP SUMMARY
- Dominant content type: [...]
- Dominant angle: [...]
- Typical depth: [...]

MUST-COVER SUBTOPICS (3+ of top 10)
1. ...
2. ...

DIFFERENTIATION OPPORTUNITIES (1-2 of top 10)
1. ...

INTENT RED FLAGS
- [...]
```

## Guardrails

- Search the actual live SERP — never simulate or guess rankings
- Record date/time of your SERP check
- Never copy any competitor's heading structure or unique framing

---
name: content-uniqueness-researcher
description: Research unique angles, data, and perspectives to differentiate your content
---

# Content Uniqueness Researcher

Find angles and data that make content stand out from the SERP.

## Input Required

- **Target keyword:** [e.g., "email marketing best practices"]
- **Top 3 competing URLs:** [from Step 2]
- **Your unique advantage:** [e.g., "I've run 500+ email campaigns"]
- **Target audience:** [e.g., "small business owners"]

## Workflow

### 1. Map Competitors

| Competitor URL | Their Hook | Evidence Depth | What They Miss |
|---------------|-----------|---------------|----------------|

### 2. Research Beyond Page 1

| Layer | Where | What You'll Find |
|-------|-------|-----------------|
| Academic | Google Scholar | Peer-reviewed studies with citable data |
| Practitioner | Reddit, forums | Real language and problems your audience uses |
| Expert | Podcasts, conference talks | Quotes and frameworks competitors missed |
| Public data | Government datasets, industry reports | Hard numbers for your arguments |
| First-party | Your analytics, experiments | Truly unique insights |

### 3. Propose 3 Unique Angles

For each: Description, why it's different, evidence needed, effort level (Low/Med/High).

### Output Format

```
UNIQUE ANGLE RECOMMENDATIONS
1. [Angle Name] (Effort: Medium)
   Description: ...
   Why different: ...

2. [Angle Name] (Effort: Low)
   ...

QUICK WINS (add today)
- [...]
```

## Guardrails

- Cite verifiable sources — never fabricate studies or statistics
- Mark missing data: "[DATA NEEDED: description]"
- Distinguish "opinion with evidence" from "established fact"

---
name: seo-content-outliner
description: Generate a detailed SEO content outline from SERP analysis and unique research
---

# SEO Content Outliner

Create an annotated outline optimized for readers and search engines.

## Input Required

- **Target keyword:** [e.g., "email marketing best practices"]
- **SERP intent analysis:** [from Step 2]
- **Unique angle:** [from Step 3]
- **Target audience:** [e.g., "small business owners"]
- **Target word count:** [e.g., 2,500 words]

## Workflow

### 1. Map the Reader Journey

- **Hook:** What problem right now?
- **Promise:** What will they know at the end?
- **Path:** Sequence of ideas from problem to solution
- **Payoff:** The one actionable takeaway

### 2. Build the Heading Hierarchy

- H2s tell a story when read in sequence
- Cover all must-have subtopics from Step 2
- Weave in your unique angle from Step 3
- One concrete example per major section

### 3. Annotate Every Section

| Annotation | Description |
|-----------|-------------|
| Purpose | What this section achieves |
| Keywords | Terms to include naturally |
| Unique element | How it differs from competitors |
| Example/data | Specific example or source |
| Visual | Screenshot, table, or diagram? |

### Output Format

```
# [H1: Title]

## Introduction (~150 words)
- Purpose: [...]
- Keywords: [...]
- Example: [...]

## [H2: Section] (~X words)
- Purpose: [...]
- Keywords: [...]
- Visual: [Yes — screenshot of X / No]

### [H3: Sub-section]
- Purpose: [...]

## Conclusion (~X words)
- CTA: [...]
```

## Guardrails

- Structure must be original — don't replicate competitor headings
- Every section must serve the reader, not just hold keywords
- Mark sections needing verification with `[NEEDS VERIFICATION]`

---
name: seo-draft-writer
description: Write a complete SEO-optimized blog post from an approved outline and research
---

# SEO Draft Writer

Write a reader-first draft optimized for search engines.

## Input Required

- **Approved outline:** [from Step 4]
- **Research notes:** [from Step 3]
- **Target keyword:** [e.g., "email marketing best practices"]
- **Brand voice:** [e.g., "conversational but authoritative; uses 'you'"]
- **Target word count:** [e.g., 2,500 words]

## Guidelines

### Structure
- Lead with a specific hook (problem, stat, scenario) — never "In today's digital world..."
- Direct answer within 150 words
- One idea per paragraph (2–4 sentences)
- Use bullets, lists, and tables where helpful
- End sections with a transition to the next
- Conclusion = actions, not a summary

### SEO
- Primary keyword in: H1, first 100 words, at least one H2, naturally throughout
- Use semantic variations — don't keyword-stuff
- Write descriptive subheadings, not clever puns

### Readability
- 7th–9th grade reading level
- Active voice; sentences under 25 words
- Define jargon on first use

### Originality
- One original example or data point per major section
- Be specific: "62% of businesses report..." not "many businesses struggle"
- Cite sources naturally in the text

## Guardrails

- **Never fabricate** statistics, quotes, case studies, or results
- Mark unverified claims: `[VERIFICATION NEEDED: claim]`
- Missing data: write `[DATA NEEDED: description]` — don't invent
- No API keys, tokens, or internal notes in output

---
name: seo-content-reviewer
description: Review a draft for accuracy, flow, readability, and SEO with specific fixes
---

# SEO Content Reviewer

Review a draft and provide actionable fixes, not just flags.

## Input Required

- **Full draft:** [paste complete article]
- **Target keyword:** [e.g., "email marketing best practices"]
- **Original outline:** [from Step 4]
- **SERP analysis:** [from Step 2]

## Review Dimensions

### 1. Factual Accuracy
- Flag claims: `[FACT CHECK] "Claim" — verification method`
- Confidence: Confident / Needs source / Questionable / Likely wrong

### 2. Logical Flow
- Does the intro deliver on its promise?
- Does every H2 match what was outlined?
- Any gaps where readers think "but what about...?"
- Does the conclusion give next steps (not a summary)?

### 3. Readability
- Flag sentences over 25 words → suggest break point
- Flag undefined jargon → suggest plain-English definition
- Flag passive voice → suggest active rewrite
- Flag paragraphs over 4 sentences → suggest where to add bullets

### 4. SEO Health Check
- Keyword in: H1 ✓/✗, first 100 words ✓/✗, one H2 ✓/✗
- Keyword stuffing? Subheading quality? Intro as meta description candidate?

### Output Format

```
OVERALL: [Ready / Minor edits / Major revision]
Strongest section: [...]
Weakest section: [...]

PRIORITY FIXES
1. [Location] — [Issue] → [Fix]

LINE NOTES
[Section-by-section, with locations and suggestions]

SEO SCORECARD
- Keyword in H1: ✓/✗
- Keyword in first 100 words: ✓/✗
- Keyword in one H2: ✓/✗
- Subheading quality: [...]
```

## Guardrails

- Review as-is — don't rewrite
- "Factually wrong" ≠ "I'd phrase it differently"
- Never suggest adding fabricated data
- If unverifiable, say so

---
name: seo-metadata-generator
description: Generate SEO titles and meta descriptions with documented strategy
---

# SEO Metadata Generator

Generate high-CTR title tags and meta descriptions.

## Input Required

- **Primary keyword:** [e.g., "email marketing best practices"]
- **Content summary:** [2–3 sentences]
- **Unique angle:** [what makes this different]
- **Target audience:** [e.g., "small business owners"]
- **Current SERP titles:** [3–5 from top results — for differentiation]

## Title Rules
- Under 60 characters
- Include primary keyword; front-load important words
- Match intent: How-to → "How to...", List → number, Definition → "What Is..."
- Include year (2026) when freshness matters
- No clickbait — the title must deliver

## Meta Description Rules
- Under 155 characters
- Expand the title, don't repeat it
- Active voice, address the reader
- Include keyword naturally + subtle CTA

### Output Format

```
TITLE OPTIONS
1. "[Title]" (XX chars) — Strategy: [...]
2. "[Title]" (XX chars) — Strategy: [...]
3. "[Title]" (XX chars) — Strategy: [...]

RECOMMENDED: Option X — [...]

META DESCRIPTION OPTIONS
1. "[Description]" (XX chars)
2. [...]

RECOMMENDED: Option X — [...]

SERP STANDOUT CHECK
- Competitor 1: "[title]" — how yours differs
- Competitor 2: "[title]" — how yours differs
```

## Guardrails

- Title must match content — no bait-and-switch
- Don't stuff keywords
- Don't promise what the article doesn't deliver

---
name: internal-link-builder
description: Identify internal link opportunities for a new article
---

# Internal Link Builder

Find the best internal linking opportunities for your article.

## Input Required

- **New article URL/slug:** [e.g., "/blog/email-marketing-best-practices"]
- **New article summary:** [3–5 bullet points]
- **Target keyword:** [e.g., "email marketing best practices"]
- **Existing site content:** [list of URLs + titles]

## Workflow

### 1. Link-From Candidates
Find existing pages that should link TO the new article. Prioritize pages that mention related topics, rank for related keywords, or have existing authority.

### 2. Link-To Candidates
Find pages the new article should link TO: pillar content, product pages, related articles in the same topic cluster.

### 3. Anchor Text
Suggest 2–5 word anchors that flow naturally. Vary anchors — don't use exact-match every time.

### Output Format

```
LINKS TO THE NEW ARTICLE
| Link From | Anchor Text | Where to Insert | Priority |
|-----------|------------|----------------|---------|

LINKS FROM THE NEW ARTICLE
| Link To | Anchor Text | Where in Article | Why |
|---------|------------|-----------------|-----|
```

## Guardrails

- Only contextually relevant links
- Max one link per URL per page
- Vary anchor text: partial match, branded, natural language
- Reader value first, SEO second

/seo-keyword-research           →  Pick your keyword
/serp-intent-analyzer           →  Understand what searchers want
/content-uniqueness-researcher  →  Find your unique angle
/seo-content-outliner           →  Build your outline
/seo-draft-writer               →  Write the draft
/seo-content-reviewer           →  Review and polish
/seo-metadata-generator         →  Craft title and description
/internal-link-builder          →  Add internal links → PUBLISH