# claude-seo-kit 🤖🔍

**Claude SEO Skills** — production [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for SEO, powered by a **standalone Python engine** (no API keys, no paywalls, one dependency).

Install as a **Claude Code plugin** and audit any URL for **technical SEO**, **content quality & E-E-A-T**, **Schema.org structured data**, **sitemaps**, **hreflang**, and **GEO (AI-search readiness)** — with a 0-100 score, A-F grade, and prioritized fixes.

> **Credits:** This is an **original implementation** — no code was copied — inspired by two pioneering open-source projects:
> - **[AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo)** (12.9K⭐, MIT) — the Claude Code SEO plugin that popularized SEO-as-an-agent-skill.
> - **[seranking/seo-skills](https://github.com/seranking/seo-skills)** (108⭐, MIT) — production Claude Agent Skills for the SE Ranking MCP server.
>
> Unlike both, **claude-seo-kit needs no API account**: every skill is backed by a dependency-light Python engine that fetches and analyzes pages directly. It also works as a standalone CLI and an MCP server.

---

## Why claude-seo-kit?

Most SEO agent tools either require a paid API (SE Ranking, DataForSEO, Ahrefs), are locked to one CLI ecosystem, or ship no real engine at all. `claude-seo-kit` fixes all three:

| Feature | claude-seo-kit | AgriciDaniel/claude-seo | seranking/seo-skills |
|---------|----------------|--------------------------|----------------------|
| **Claude Code plugin / skills** | ✅ | ✅ | ✅ |
| **Works without any API account** | ✅ | ❌ (needs Google/Firecrawl) | ❌ (needs SE Ranking) |
| **Real Python engine behind the skills** | ✅ | partial (scripts) | ❌ (skills only) |
| **Standalone CLI** | ✅ | ❌ | ❌ |
| **MCP server** | ✅ | ❌ | ✅ (remote, paid) |
| **JSON reports for pipelines** | ✅ | ❌ | ❌ |
| **GEO / AI-search readiness** | ✅ | ✅ | ✅ |
| **Sitemap / hreflang checks** | ✅ | ✅ | ✅ |
| One dependency (`httpx`) | ✅ | many | many |

---

## Install

### 1. Claude Code plugin (recommended)

```bash
/plugin marketplace add FreeAutomation-Tech/claude-seo-kit
/plugin install claude-seo-kit@FreeAutomation-Tech
```

Skills load on your next session. Trigger by name — `/seo-audit <url>` — or just describe what you want ("audit example.com") and Claude picks the right skill.

### 2. Manual install (copy skills into Claude Code)

```bash
git clone https://github.com/FreeAutomation-Tech/claude-seo-kit.git
cd claude-seo-kit
bash install.sh          # copies skills/ to ~/.claude/skills/
pip install -r requirements.txt
```

### 3. As a Python package

```bash
pip install -e .
claude-seo-kit https://example.com --format json
```

---

## Skills

| Skill | What it produces | Trigger |
|-------|------------------|---------|
| [`seo-audit`](skills/seo-audit/SKILL.md) | Full audit: 0-100 score, A-F grade, prioritized fixes across technical + content + schema | "audit my site", "check my seo" |
| [`seo-technical`](skills/seo-technical/SKILL.md) | On-page HTML signals + robots.txt/sitemap health | "technical seo", "crawl issues", "indexation" |
| [`seo-content`](skills/seo-content/SKILL.md) | Content quality, heading hierarchy, readability, E-E-A-T | "improve my content", "e-e-a-t" |
| [`seo-schema`](skills/seo-schema/SKILL.md) | JSON-LD detect, validate, generate | "schema", "structured data", "rich results" |
| [`seo-sitemap`](skills/seo-sitemap/SKILL.md) | robots.txt + XML sitemap health | "check my sitemap", "robots.txt" |
| [`seo-hreflang`](skills/seo-hreflang/SKILL.md) | International SEO tag validation + x-default | "hreflang", "multi-language site" |
| [`seo-geo`](skills/seo-geo/SKILL.md) | AI-search readiness — LLM citability score | "why isn't my content cited by chatgpt" |

Each skill is a single `SKILL.md` with YAML frontmatter (Anthropic's
[progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work)
pattern) that tells Claude when to use it and exactly how to run the engine.

---

## The engine

A dependency-light Python package (`seo_kit`) with everything the skills call:

### Technical SEO (`seo_kit.technical`)
- Title, meta description, canonical, H1, robots, viewport, alt text, links, thin content, lang, favicon
- robots.txt + XML sitemap health (`seo_kit.crawler.sitemap`)
- hreflang / international tag validation (`seo_kit.technical.hreflang`)

### Content & E-E-A-T (`seo_kit.content`)
- Word count, heading hierarchy, Flesch readability, keyword density, E-E-A-T signals
- GEO / AI-search citability (`seo_kit.content.geo`)

### Structured data (`seo_kit.schema`)
- JSON-LD extraction, type coverage (Organization, WebSite, Article, Product, FAQ...), required-field completeness

### Interfaces
- **CLI** — `python -m seo_kit.cli <url> --format json|markdown`
- **Python API** — `from seo_kit.cli import audit_url`
- **MCP server** — `python -m seo_kit.mcp.server` exposes `seo_audit`, `seo_audit_full`, `seo_technical_check`, `seo_content_check`, `seo_sitemap_check`, `seo_hreflang_check`, `seo_geo_check`
- **Skills** — the Claude Code skills above

---

## Quick start

```bash
pip install -r requirements.txt

# Full audit (markdown report)
python -m seo_kit.cli https://example.com --format markdown --output report.md

# Full audit (JSON for pipelines / agents)
python -m seo_kit.cli https://example.com --format json

# Standalone checks
python -m seo_kit.crawler.sitemap https://example.com
python -m seo_kit.technical.hreflang https://example.com
python -m seo_kit.content.geo https://example.com

# MCP server
pip install mcp && python -m seo_kit.mcp.server
```

### Python API

```python
from seo_kit.cli import audit_url
from seo_kit.reports.markdown import render_markdown

result = audit_url("https://example.com")
print(f"Score: {result.overall_score}/100 — Grade {result.grade}")
print(render_markdown(result, "https://example.com"))
```

---

## Example report

```markdown
# SEO Audit Report — https://example.com

**Overall Score: 72/100 — Grade 🟡 C**

| Category | Score |
|----------|-------|
| Technical | 68/100 |
| Content   | 75/100 |
| Schema    | 80/100 |
```

Every report ends with a **prioritized recommendations** list ordered
error → warning → info, plus per-category details.

---

## Roadmap

- [ ] Site-wide crawling (multi-page audit with weighted scoring)
- [ ] Core Web Vitals via Lighthouse API
- [ ] Optional data providers (SE Ranking / DataForSEO adapters)
- [ ] Schema.org generator (draft valid JSON-LD from the CLI)
- [ ] Image SEO audit (`srcset`, WebP/AVIF, lazy-loading)

---

## Credits & Inspiration

This project is an **original implementation** — no code was copied — but the
concept is heavily inspired by:

- **[AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo)** (MIT) — the
  Claude Code SEO plugin with 25 sub-skills, 18 sub-agents, and 410+ tests. Star it:
  ⭐ [github.com/AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo)
- **[seranking/seo-skills](https://github.com/seranking/seo-skills)** (MIT) — production
  Claude Agent Skills for the SE Ranking MCP server. Star it:
  ⭐ [github.com/seranking/seo-skills](https://github.com/seranking/seo-skills)

### Ecosystem

Part of the **FreeAutomation-Tech** AI tooling family:

| Repo | What it does |
|------|--------------|
| [claude-marketing-kit](https://github.com/FreeAutomation-Tech/claude-marketing-kit) | Claude Marketing Skills + Python engine |
| [claude-seo-kit](https://github.com/FreeAutomation-Tech/claude-seo-kit) | Claude SEO Skills + Python engine |
| [agent-harness](https://github.com/FreeAutomation-Tech/agent-harness) | Production agent runtime |
| [llm-economizer](https://github.com/FreeAutomation-Tech/llm-economizer) | Token cost optimization proxy |
| [skill-optimizer](https://github.com/FreeAutomation-Tech/skill-optimizer) | Compress & benchmark agent skills |
| [fastapi-ai-kit](https://github.com/FreeAutomation-Tech/fastapi-ai-kit) | FastAPI agent backend |
| [agent-memory-kit](https://github.com/FreeAutomation-Tech/agent-memory-kit) | Memory patterns for agents |
| [agent-security-kit](https://github.com/FreeAutomation-Tech/agent-security-kit) | Agent threat models & defenses |
| [awesome-mcp-servers](https://github.com/FreeAutomation-Tech/awesome-mcp-servers) | Curated MCP server list |

---

## License

[MIT](LICENSE)

---

If you find this useful, please consider giving it a star ⭐ — it helps others discover
free, open-source AI tooling and keeps us building more.

*Made with ❤️ by [FreeAutomation-Tech](https://github.com/FreeAutomation-Tech)*