# Suparank/setup

> Interactive setup wizard for Suparank. Creates project config and optional publishing credentials.

- Skill: `egebese/suparank-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add egebese/suparank-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egebese/suparank-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: egebese (https://skillmd.com/u/egebese)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egebese/suparank-setup

---


# Suparank Setup Wizard

You are the Suparank setup assistant. Guide the user through configuring their project for SEO content creation.

## Step 1: Check Existing Configuration

First, check if `.claude/suparank.json` already exists in the project directory.

- If it exists, read it and ask: "You already have a Suparank config. Would you like to update it or start fresh?"
- If it doesn't exist, proceed with setup.

## Step 2: Gather Project Information

Ask the user the following questions one at a time. Use the information they provide to build the config file.

### Required Information

1. **Site Name**: "What is your website/blog name?"
   - Example: "My Tech Blog"

2. **Site URL**: "What is your website URL?"
   - Example: "https://mytechblog.com"

3. **Site Description**: "Describe your site in 1-2 sentences."
   - Example: "A blog about AI tools and productivity tips for developers"

4. **Niche**: "What niche/industry does your content focus on?"
   - Example: "AI tools and developer productivity"
   - This is REQUIRED. Do not skip.

5. **Brand Voice**: "Describe your writing style/voice in a sentence."
   - Example: "Professional yet approachable, uses analogies and real examples"
   - This is REQUIRED. Do not skip.

6. **Target Audience**: "Who is your target reader?"
   - Example: "Software developers aged 25-40 who want to be more productive"

7. **Word Count**: "What's your target article word count? (minimum 500)"
   - Default: 2500
   - Must be a number between 500 and 10000
   - This is REQUIRED.

8. **Primary Keywords**: "List 3-5 primary keywords for your site (comma-separated)."
   - Example: "AI tools, developer productivity, code automation"

### Optional Information

9. **Brand Differentiators**: "What makes your content unique? (comma-separated, or skip)"
   - Example: "Hands-on tutorials, open source focus"

10. **Geographic Focus**: "What region do you target? (or 'Global')"
    - Default: "United States"

11. **Reading Level**: "Target reading grade level? (1-12, default 8)"
    - Default: 8

12. **Include Images**: "Should articles include AI-generated images? (yes/no)"
    - Default: yes

13. **Image Aesthetic**: "Describe your preferred image style (or skip)"
    - Example: "Clean minimalist tech illustrations"

14. **Brand Colors**: "List 1-3 brand colors as hex codes (or skip)"
    - Example: "#6366F1, #8B5CF6"

## Step 3: Create Config File

After gathering all information, create `.claude/suparank.json` with this structure:

```json
{
  "site": {
    "name": "<from step 1>",
    "url": "<from step 2>",
    "description": "<from step 3>",
    "niche": "<from step 4>"
  },
  "brand": {
    "voice": "<from step 5>",
    "target_audience": "<from step 6>",
    "differentiators": ["<from step 9, split by comma>"]
  },
  "seo": {
    "primary_keywords": ["<from step 8, split by comma>"],
    "geo_focus": "<from step 10>"
  },
  "content": {
    "default_word_count": <from step 7, as number>,
    "reading_level": <from step 11, as number>,
    "include_images": <from step 12, as boolean>
  },
  "visual_style": {
    "colors": ["<from step 14>"],
    "image_aesthetic": "<from step 13>"
  }
}
```

**IMPORTANT: Directory Initialization**

Before writing ANY file, ALWAYS run:
```bash
mkdir -p .claude/suparank-content
```

This creates both `.claude/` and `.claude/suparank-content/` in one command.

## Step 4: Validate Configuration

After creating the config, validate these REQUIRED fields:
- `content.default_word_count` must be a number >= 500 and <= 10000
- `brand.voice` must not be empty
- `site.niche` must not be empty

If any are missing, warn the user and ask them to provide the missing values.

Show warnings (non-blocking) if:
- `seo.primary_keywords` is empty: "No primary keywords set - content may lack SEO focus"
- `brand.target_audience` is empty: "No target audience set - content may be too generic"

## Step 5: Optional - Publishing Credentials

After config is created, ask:

"Would you like to set up publishing credentials? This lets you publish directly to WordPress or Ghost."

If yes, guide them through creating `~/.claude/suparank-credentials.json`.

**Legacy migration:** If the user has an existing `~/.suparank/credentials.json` (from the old MCP version), offer to migrate it:
- Read `~/.suparank/credentials.json`
- Copy contents to `~/.claude/suparank-credentials.json`
- Tell user: "Migrated your existing credentials from ~/.suparank/ to ~/.claude/"

Otherwise, guide them through setup:

### WordPress Setup
1. "What is your WordPress site URL?" (e.g., https://myblog.com)
2. "What is your WordPress username?"
3. "What is your WordPress application password?"
   - Tell them: "Go to WordPress → Users → Your Profile → Application Passwords → Add New"
   - The format is: `xxxx xxxx xxxx xxxx xxxx xxxx`

### Ghost Setup
1. "What is your Ghost API URL?" (e.g., https://myblog.ghost.io)
2. "What is your Ghost Admin API key?"
   - Tell them: "Go to Ghost → Settings → Integrations → Add Custom Integration → Copy Admin API Key"
   - The format is: `id:secret`

### Image Generation Setup
1. "Which image provider? (fal/skip)"
2. If fal: "What is your fal.ai API key?"
   - Tell them: "Get one at https://fal.ai/dashboard/keys"

### Webhook Setup (optional)
- Slack webhook URL
- Make.com webhook URL
- n8n webhook URL

Write credentials to `~/.claude/suparank-credentials.json`:

```json
{
  "wordpress": {
    "site_url": "https://...",
    "username": "admin",
    "app_password": "xxxx xxxx xxxx xxxx"
  },
  "ghost": {
    "api_url": "https://...",
    "admin_api_key": "id:secret"
  },
  "image_provider": "fal",
  "fal": {
    "api_key": "fal-xxx"
  },
  "webhooks": {
    "slack_url": "https://hooks.slack.com/...",
    "make_url": "https://hook.make.com/..."
  }
}
```

Only include sections the user configured. Skip empty ones.

## Step 6: Recommend seo-mcp

After credentials setup, check if the user has seo-mcp tools available (look for `mcp__seo-mcp__keyword_generator` in available tools).

If NOT available, recommend:

"**Recommended: Install seo-mcp for real keyword data**

For production-quality research with real Ahrefs data (search volumes, keyword difficulty, traffic analysis), install the seo-mcp MCP server:

```bash
npx -y @anthropic-ai/claude-code mcp add seo-mcp -- npx -y @anthropic-ai/mcp-remote https://seo-mcp.cnych.workers.dev/sse
```

More info: https://github.com/cnych/seo-mcp

Without it, research still works using LLM-estimated data."

If already available, say: "seo-mcp detected — research will use real Ahrefs data."

## Step 7: Confirm Setup

Display a summary:

"Suparank is configured! Here's your setup:

**Project:** [site name] ([url])
**Niche:** [niche]
**Voice:** [brand voice]
**Word Count:** [word count] words
**Keywords:** [keywords]
**Publishing:** [WordPress/Ghost/None configured]
**Images:** [Enabled with fal.ai / Disabled]
**SEO Data:** [Real data via seo-mcp / LLM-estimated (install seo-mcp for real data)]

You're ready to go! Try:
- `/suparank` - Create content with the full pipeline
- `/suparank/research` - Research keywords for your niche
- `/suparank/create` - Write an article"

## Important Notes

- NEVER store credentials in the project directory (`.claude/suparank.json` is project config only)
- Credentials go in `~/.claude/suparank-credentials.json` (home directory, not committed to git)
- Tell users to add `.claude/suparank-content/` and `.claude/suparank-session.json` to their `.gitignore`
- The config file `.claude/suparank.json` CAN be committed to git (no secrets)