Installing Claude SEO on macOS, Linux, and Windows

Claude SEO can be installed in three ways: through the Claude Code plugin marketplace (the fastest path, requires Claude Code 1.0.33+), manually via git clone on Unix-based systems, or manually via git clone on Windows with PowerShell. All three methods install the same skill files and create the same directory layout. Choose the method that matches your setup.

Prerequisites

Before installing, confirm the following are present on your system:

Python 3.10 or higher — the install script checks this and exits with an error if the version is too old
Git — required for the manual install paths
Claude Code CLI — install from claude.ai/claude-code; the plugin install method requires version 1.0.33 or later

Optional, but recommended for full functionality:

Playwright Chromium — enables SPA rendering and screenshot analysis; the installer attempts this automatically
Google API credentials — unlocks CrUX field data, Search Console, GA4, and Keyword Planner (see Google API setup)

Install Methods

Plugin Install
Unix / macOS / Linux
Windows PowerShell

The plugin install method is the fastest path and is the recommended approach for anyone on Claude Code 1.0.33 or later. It handles everything in two commands run inside Claude Code.

Add the repository to your marketplace

Inside Claude Code, run:

/plugin marketplace add AgriciDaniel/claude-seo

This registers AgriciDaniel/claude-seo as a trusted plugin source in your local Claude Code installation.

Install the plugin

/plugin install claude-seo@agricidaniel-claude-seo

Claude Code fetches the plugin, copies 25 sub-skill SKILL.md files into ~/.claude/skills/, places 18 subagent definitions in ~/.claude/agents/, and creates a Python virtual environment at ~/.claude/skills/seo/.venv/. Python dependencies from requirements.txt are installed into that venv automatically.

Verify the install

ls ~/.claude/skills/seo/SKILL.md

If the file exists, the install succeeded. Start Claude Code with claude and type /seo to confirm the command is available.

If you are an AI Marketing Hub Pro member and want the community mirror with early-access features, swap AgriciDaniel/claude-seo for AI-Marketing-Hub/claude-seo and use the plugin slug claude-seo@ai-marketing-hub-claude-seo. This requires gh auth login (or a PAT) with access to the AI-Marketing-Hub org. If /plugin marketplace add returns a 404, post in the Skool community to be added to the org.

The manual Unix install clones the repository locally so you can inspect every file before anything runs on your system.

Clone the repository

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git

The --depth 1 flag downloads only the latest commit, keeping the clone small. You can browse claude-seo/install.sh before proceeding.

Run the installer

bash claude-seo/install.sh

The script:

Verifies Python 3.10+ is available

Creates ~/.claude/skills/seo/ and ~/.claude/agents/

Copies all 25 sub-skill directories to ~/.claude/skills/

Copies 18 subagent .md files to ~/.claude/agents/

Copies shared scripts, schema templates, and reference docs

Creates a Python venv at ~/.claude/skills/seo/.venv/

Installs Python dependencies into the venv (falls back to pip install --user if venv creation fails)

Attempts to install Playwright Chromium (non-fatal if it fails)

Verify the install

ls ~/.claude/skills/seo/SKILL.md

Then start Claude Code and confirm /seo is available:

claude

Alternative: curl review-then-runIf you prefer not to maintain a local clone, you can download the install script, review it, and run it:

curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh
cat install.sh        # review before running
bash install.sh
rm install.sh

The installer pins to a specific release tag by default (currently v2.2.0). To install from main instead, set the environment variable before running: CLAUDE_SEO_TAG=main bash install.sh.

The Windows install uses git clone rather than a irm | iex one-liner. This is intentional — see the security note below.

Clone the repository

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git

This downloads the repository into a claude-seo\ subdirectory of your current folder. Review claude-seo\install.ps1 before running it.

Run the installer

powershell -ExecutionPolicy Bypass -File claude-seo\install.ps1

The script creates the same directory layout as the Unix installer:

Sub-skills → ~/.claude/skills/seo/ and ~/.claude/skills/seo-*/

Subagents → ~/.claude/agents/seo-*.md

Python venv → ~/.claude/skills/seo/.venv/

Verify the install

Test-Path "$env:USERPROFILE\.claude\skills\seo\SKILL.md"

A result of True confirms the skill is installed. Start Claude Code and type /seo to confirm.

Why git clone instead of irm | iex? Claude Code’s own security guardrails flag irm ... | iex (Invoke-RestMethod piped to Invoke-Expression) as a supply chain risk because it downloads and executes remote code without giving you a chance to inspect it. The git clone approach places install.ps1 on your local filesystem so you can read it before anything runs. Always inspect remote scripts before executing them.

What Gets Installed

The installer places files in the following locations regardless of which method you use:

Component	Path
Orchestrator skill	`~/.claude/skills/seo/SKILL.md`
Sub-skills (25)	`~/.claude/skills/seo-*/SKILL.md`
Subagents (18)	`~/.claude/agents/seo-*.md`
Shared scripts	`~/.claude/skills/seo/scripts/`
Schema templates	`~/.claude/skills/seo/schema/`
Python venv	`~/.claude/skills/seo/.venv/`
Requirements file	`~/.claude/skills/seo/requirements.txt`

Optional: Playwright Chromium for SPA Rendering

The installer attempts to install Playwright Chromium automatically. If that step failed, or if you skipped it, install it manually:

# Using the skill venv (preferred)
~/.claude/skills/seo/.venv/bin/python -m playwright install chromium

# Or using your system Python
python3 -m playwright install chromium

Without Playwright, the SPA renderer falls back to WebFetch. Most audits still complete successfully; pages that require JavaScript execution for content (empty <div id="root"> shells, hydration-dependent content) may produce incomplete findings on those specific pages.

Optional: Google API Setup

Claude SEO works fully offline with zero credentials. Run the setup wizard inside Claude Code to add enrichment at any tier:

/seo google setup

This opens an interactive credential wizard that walks through Tier 0 (API key for PageSpeed Insights and CrUX) through Tier 3 (Ads developer token for Keyword Planner). All credentials are stored in ~/.config/claude-seo/ with 0o600 file permissions — nothing is checked into any repository and nothing is transmitted beyond Google’s own endpoints.

Verify Installation

The canonical verification check is:

ls ~/.claude/skills/seo/SKILL.md

If the file does not exist, re-run the installer. Additional checks:

# Confirm sub-skills are present
ls ~/.claude/skills/ | grep seo

# Confirm subagents are present
ls ~/.claude/agents/ | grep seo

# Confirm venv was created
ls ~/.claude/skills/seo/.venv/

If you encounter a “Skill not found” error inside Claude Code, the most common cause is that SKILL.md is missing from the expected path. Re-run the installer or check for permission errors — see the Troubleshooting guide for a full list of error cases and resolutions.

Uninstall

If installed via plugin:

/plugin uninstall claude-seo@agricidaniel-claude-seo
/plugin marketplace remove AgriciDaniel/claude-seo

If installed manually (Unix / macOS / Linux):

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/uninstall.sh

The uninstall.sh script uses glob enumeration rather than a hardcoded list — it removes every seo and seo-* skill directory under ~/.claude/skills/ and every seo-*.md agent file under ~/.claude/agents/, and cleans up the plugin’s MCP entries from ~/.claude/settings.json. It leaves all sibling skills (e.g. blog-writer, security) untouched.

Do not maintain a hand-coded rm list for uninstalling. The shipped uninstall.sh is the canonical source and tracks new sub-skills automatically as the project grows.

Community vs. Public Version

By default, all commands in this guide install from AgriciDaniel/claude-seo — the public open-source MIT-licensed repository. If you are an AI Marketing Hub Pro member and want the community private mirror with early-access features:

Swap AgriciDaniel/claude-seo → AI-Marketing-Hub/claude-seo in any git clone command
Swap the plugin slug claude-seo@agricidaniel-claude-seo → claude-seo@ai-marketing-hub-claude-seo in any /plugin command

The community mirror requires gh auth login (or a personal access token) with access to the AI-Marketing-Hub GitHub organization. Both versions share the same skill interface and all commands described in this documentation.

Upgrading

To upgrade to the latest version, uninstall the current version and reinstall:

# Uninstall
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/uninstall.sh

# Reinstall (latest pinned release)
bash claude-seo/install.sh

Prefer downloading, inspecting, then running remote scripts. The uninstall.sh | bash and install.sh | bash curl forms are the less-safe convenience options; they skip the review step.

Get Started

Core Commands

Specialized Commands

Extensions

Reference

Installing Claude SEO on macOS, Linux, and Windows

Prerequisites

Install Methods

What Gets Installed

Optional: Playwright Chromium for SPA Rendering

Optional: Google API Setup

Verify Installation

Uninstall

Community vs. Public Version

Upgrading

Build docs developers (and LLMs) love

Get Started

Core Commands

Specialized Commands

Extensions

Reference

Documentation Index

​Prerequisites

​Install Methods

​What Gets Installed

​Optional: Playwright Chromium for SPA Rendering

​Optional: Google API Setup

​Verify Installation

​Uninstall

​Community vs. Public Version

​Upgrading

Build docs developers (and LLMs) love

Prerequisites

Install Methods

What Gets Installed

Optional: Playwright Chromium for SPA Rendering

Optional: Google API Setup

Verify Installation

Uninstall

Community vs. Public Version

Upgrading