# seo-review

> Weekly SEO performance review for clients. Fetches Search Console data, compares week-over-week metrics, identifies top pages, rising/declining keywords, CTR opportunities, and generates a markdown report. Use when performing client SEO reviews or analyzing search performance trends.

- Author: Alex Ishida
- Repository: alexweberk/seo-review
- Version: 20260121144837
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/alexweberk/seo-review
- Web: https://mule.run/skillshub/@@alexweberk/seo-review~seo-review:20260121144837

---

---
name: seo-review
description: Weekly SEO performance review for clients. Fetches Search Console data, compares week-over-week metrics, identifies top pages, rising/declining keywords, CTR opportunities, and generates a markdown report. Use when performing client SEO reviews or analyzing search performance trends.
---

# SEO Review Skill

Automated weekly SEO performance analysis using Google Search Console data. Designed for client reporting with actionable insights.

## Interactive Workflow

When the user invokes this skill, follow this workflow:

### Step 1: Check for Configured Sites

First, check if there are any sites configured:

```bash
cd ~/.claude/skills/seo-review
uv run seo-review --list-sites
```

**If sites exist:** Present them to the user with a picker asking which site they want to review.

**If no sites exist:** Proceed to Step 2 to set up a new site.

### Step 2: Site Selection (If Sites Exist)

Ask the user which site they want to review. Use the AskUserQuestion tool to present the available sites as options:

> **Which site would you like to review?**
>
> [List sites from --list-sites output]
> [Add new site]

If the user selects an existing site, skip to Step 5.
If the user selects "Add new site", proceed to Step 3.

### Step 3: Gather Credentials (New Site Only)

Ask the user:

> **Where is your Google Search Console service account credentials file located?**
>
> Please provide the full path to your JSON key file (e.g., `/Users/you/Downloads/my-service-account.json`)

Once the user provides the path:

1. Verify the file exists
2. Copy the credentials to the skill directory:
   ```bash
   mkdir -p ~/.claude/skills/seo-review/credentials
   cp "<user-provided-path>" ~/.claude/skills/seo-review/credentials/<client-name>.json
   ```

3. Confirm the copy was successful

### Step 4: Gather Site Information (New Site Only)

Ask the user:

> **What is the Search Console property URL?**
>
> Examples:
> - `https://www.example.com`
> - `sc-domain:example.com` (for domain properties)

Then ask:

> **What should we call this site?** (e.g., "Acme Corp", "My Blog")

Save the site configuration by running the setup:

```bash
cd ~/.claude/skills/seo-review
uv run seo-review-setup
```

Or manually add to the config (if setup is not interactive enough).

### Step 5: Run the Review

Navigate to the skill directory and run:

```bash
cd ~/.claude/skills/seo-review
uv sync  # Only if first time
uv run seo-review --site "<site-name>"
```

For example:
```bash
uv run seo-review --site "Acme Corp"
```

### Step 6: Present Results

After the report is generated:
1. Read the generated markdown file from `reports/seo_review_<date>.md`
2. Present a summary to the user
3. Offer to show specific sections in detail

## Quick Start (Returning Users)

For users who have already set up sites:

```bash
cd ~/.claude/skills/seo-review
uv run seo-review --site "Client Name"
```

To list all configured sites:
```bash
uv run seo-review --list-sites
```

To add a new site:
```bash
uv run seo-review-setup
```

## Setup Checklist

Before running a review, ensure:

- [ ] Google Cloud Project exists with Search Console API enabled
- [ ] Service account created and JSON key downloaded
- [ ] Service account email added to Search Console property (Settings → Users and permissions)
- [ ] Credentials file copied to `~/.claude/skills/seo-review/credentials/`

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--site` | Name of configured site (recommended) | None |
| `--list-sites` | List all configured sites | - |
| `--credentials` | Path to service account JSON | Auto from site config |
| `--site-url` | Search Console property URL | Auto from site config |
| `--current-start` | Current period start date | 7 days ago |
| `--current-end` | Current period end date | 3 days ago |
| `--previous-start` | Previous period start date | 14 days ago |
| `--previous-end` | Previous period end date | 8 days ago |
| `--output` | Output file path | `reports/seo_review_<date>.md` |
| `--top-n` | Items per section | 20 |

## Report Sections

### 1. Executive Summary
- Overall metrics (clicks, impressions, CTR, position)
- Week-over-week changes
- Key wins and concerns

### 2. Top Performing Pages
- Top 20 pages by clicks
- Change from previous week

### 3. Keyword Trends
- **Rising**: Impressions up >30%
- **Declining**: Impressions down >30%

### 4. Opportunities
- **CTR Optimization**: High impressions (>500) + low CTR (<2%)
- **Almost Page 1**: Keywords ranking 11-20
- **Almost Top 3**: Keywords ranking 4-10

### 5. Recommended Actions
- Prioritized actionable items based on data

## Analysis Thresholds

| Metric | Threshold | Interpretation |
|--------|-----------|----------------|
| Significant change | >10% | Worth highlighting |
| Major change | >25% | Requires attention |
| High impressions | >500/week | Valuable keyword |
| Low CTR | <2% | Needs optimization |
| "Almost page 1" | Position 11-20 | Push opportunity |
| "Almost top 3" | Position 4-10 | Priority target |

## Troubleshooting

### "Cannot access site" Error
- Verify the service account email has been added to Search Console
- Check the site URL format matches exactly what's in Search Console
- Run `uv run seo-review --credentials <path> --site-url <url>` with `--debug` for more info

### "No data found" Error
- GSC data has a 3-day delay; ensure your date range accounts for this
- Verify the property has search traffic in the specified period
- Try a broader date range

### Authentication Errors
- Ensure the JSON key file is valid (not corrupted)
- Verify the Google Search Console API is enabled in your Cloud project

## References

- [references/metrics-guide.md](references/metrics-guide.md) - Detailed explanation of GSC metrics
- [references/report-templates.md](references/report-templates.md) - Alternative report formats (Slack, slides, Japanese)