# keyword-researching

> Researches a keyword or content idea using Jina AI Search, competitor research, and AI-powered insights. Use when the user adds a keyword to the pipeline, requests research on a topic, or needs competitive intelligence for content planning.

- Author: makkusubaitou
- Repository: makkusubaitou/blogAgent
- Version: 20260126231411
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/makkusubaitou/blogAgent
- Web: https://mule.run/skillshub/@@makkusubaitou/blogAgent~keyword-researching:20260126231411

---

---
name: keyword-researching
description: Researches a keyword or content idea using Jina AI Search, competitor research, and AI-powered insights. Use when the user adds a keyword to the pipeline, requests research on a topic, or needs competitive intelligence for content planning.
---

# Keyword Researcher

## Purpose
Conduct comprehensive research for a content piece, gathering SERP data, competitor analysis, and AI-powered insights.

## When to Use

Use this skill when the user **explicitly requests** keyword research:
- "Research [keyword]"
- "Add [keyword] to the pipeline"
- "I want to write about [topic]"
- "Start research on [keyword]"

## DO NOT USE When

- User is asking about existing research ("What keywords have we researched?")
- User wants to see the status of content in progress
- User is having a general conversation about topics
- User mentions a topic without requesting research

**If uncertain, ask:** "Would you like me to research '[topic]' as a new article, or are you just asking about it?"

## Prerequisites
- Brand guidelines should exist for context (use brand-brief-generating skill first)
- JINA_API_KEY should be configured in environment variables
- Project `config.json` should have locale settings

## Instructions

### Step 0: Load Project Locale Settings

**IMPORTANT**: Before searching, read the project's locale settings:
```bash
cat workspace/projects/{domain}/config.json
```

Extract the locale:
- `locale.language` - Language code for search (e.g., "de")
- `locale.country` - Country code for search (e.g., "de")
- `locale.location` - Optional city for local SEO

**Always use these settings** when running search queries to get relevant results for the target market.

### Step 1: SERP Analysis with Jina Search

Run the Jina AI Search script **with the project's locale settings**:
```bash
# Use the project's language and country settings!
python .claude/skills/keyword-researcher/scripts/jina_search.py "{keyword}" \
  --country {locale.country} \
  --language {locale.language}
```

**Example for German market:**
```bash
python .claude/skills/keyword-researcher/scripts/jina_search.py "projektmanagement software" \
  --country de \
  --language de
```

**Example for US market:**
```bash
python .claude/skills/keyword-researcher/scripts/jina_search.py "project management software" \
  --country us \
  --language en
```

**With local SEO (if location is set):**
```bash
python .claude/skills/keyword-researcher/scripts/jina_search.py "{keyword}" \
  --country de \
  --language de \
  --location "Berlin, Germany"
```

**Available parameters:**
| Parameter | Description | Example |
|-----------|-------------|---------|
| `--country`, `-c` | Two-letter country code | `us`, `de`, `gb`, `fr` |
| `--language`, `-l` | Two-letter language code | `en`, `de`, `es`, `fr` |
| `--location` | City-level location | `"San Francisco, CA"` |
| `--site`, `-s` | Limit to domain | `wikipedia.org` |
| `--num`, `-n` | Number of results | `10` (default) |
| `--no-cache` | Bypass cache | (flag) |
| `--include-content` | Include full page content | (flag) |

This returns:
- Top 10 organic results (title, URL, snippet, content preview)
- Full page content available for competitor analysis

If the script fails (no API key), use WebSearch tool as fallback:
```
WebSearch: {keyword}
```

### Step 2: Competitor Content Analysis

For the top 3-5 ranking articles, use the Jina Reader script:
```bash
python .claude/skills/keyword-researcher/scripts/jina_reader.py "{url}"
```

Or use WebFetch as fallback:
```
WebFetch: {url}
```

For each competitor article, extract:
- **Headings structure** (H1, H2, H3)
- **Word count** (approximate)
- **Key points covered**
- **Unique angles**
- **Content gaps**

Summarize each article to ~300 words max.

### Step 3: Deep Research

Use the Perplexity script for AI-powered research:
```bash
python .claude/skills/keyword-researcher/scripts/perplexity_research.py "{keyword}"
```

Query topics:
1. "What should a comprehensive article about {keyword} cover?"
2. "What are common questions about {keyword}?"
3. "What are the latest trends/updates related to {keyword}?"

Or use WebSearch for multiple queries as fallback.

### Step 4: Store Research

Create the content folder and save research:
```bash
mkdir -p workspace/projects/{domain}/content/{slug}
```

Save to `research.json`:
```json
{
  "keyword": "primary keyword",
  "slug": "url-friendly-slug",
  "researchedAt": "ISO timestamp",
  "locale": {
    "language": "de",
    "country": "de",
    "location": "Berlin, Germany"
  },
  "serp": {
    "results": [
      {
        "position": 1,
        "title": "...",
        "url": "...",
        "snippet": "..."
      }
    ],
    "peopleAlsoAsk": [
      "Question 1?",
      "Question 2?"
    ],
    "relatedSearches": [
      "related term 1",
      "related term 2"
    ]
  },
  "competitors": [
    {
      "url": "...",
      "title": "...",
      "wordCount": 1500,
      "headings": ["H2: ...", "H2: ..."],
      "summary": "300 word summary...",
      "strengths": ["...", "..."],
      "gaps": ["...", "..."]
    }
  ],
  "insights": {
    "mustCover": ["topic 1", "topic 2"],
    "differentiators": ["angle 1", "angle 2"],
    "questions": ["Q1?", "Q2?"],
    "trends": ["trend 1"]
  },
  "sources": [
    {
      "url": "...",
      "title": "...",
      "type": "competitor|reference|data"
    }
  ]
}
```

### Step 5: Track API Costs

After each API call, log the costs using the shared cost tracker:

```bash
# Log Jina Search costs (per search)
python .claude/skills/shared/cost_tracker.py log {domain} jina search \
  --units 1 --slug {slug} --step research

# Log Jina Reader costs (per page fetched)
python .claude/skills/shared/cost_tracker.py log {domain} jina reader \
  --units {number_of_pages_fetched} --slug {slug} --step research

# Log Perplexity costs (per query)
python .claude/skills/shared/cost_tracker.py log {domain} perplexity chat/completions \
  --units {number_of_queries} --slug {slug} --step research
```

**Cost reference:**
| Service | Endpoint | Cost/Unit |
|---------|----------|-----------|
| Jina | search | Free tier |
| Jina | reader | Free tier |
| Perplexity | chat/completions | ~$0.005 |
| SerpAPI | search | ~$0.01 |

### Step 6: Generate Research Summary

Save a human-readable summary to `research.md`:

```markdown
# Keyword Research: {keyword}

## SERP Overview
- **Search Volume**: [if available]
- **Difficulty**: [if available]
- **Current top result**: {title}

## Top Questions (PAA)
1. {question}
2. {question}
3. {question}

## Competitor Analysis

### {Competitor 1 Title}
- **URL**: {url}
- **Word Count**: ~{count}
- **Strengths**: {what they do well}
- **Gaps**: {what they miss}

[Repeat for top 3-5 competitors]

## Content Opportunities
Based on the research:
1. **Must cover**: {essential topics}
2. **Differentiate with**: {unique angles}
3. **Answer these questions**: {unaddressed questions}

## Recommended Approach
{2-3 sentences on how to approach this content}

## Sources
- [Source 1]({url})
- [Source 2]({url})
```

## Context Management Rules
- Only summaries go in research.json (must fit in context)
- Full competitor texts stored separately in `/raw/` subfolder if needed
- Never exceed 500 words per competitor summary
- Limit to top 5 competitors

## Output Files
- `content/{slug}/research.json` - Structured research data
- `content/{slug}/research.md` - Human-readable summary
- `content/{slug}/metadata.json` - Updated with research costs
- `content/{slug}/raw/` - Full source texts (optional, for reference)
- `costs.json` (project level) - Updated with research costs