Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.
Troubleshooting
Common Issues
Skill Not Loading
Symptom: /seo command not recognized
Solutions:
For plugin installs, verify and reinstall through Claude Code:
/plugin list
/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo
For manual installs:
- Verify installation:
ls ~/.claude/skills/seo/SKILL.md
- Check SKILL.md has proper frontmatter:
head -5 ~/.claude/skills/seo/SKILL.md
Should start with --- followed by YAML.
- Restart Claude Code:
claude
- Re-run installer:
Caution: Prefer downloading, inspecting, then running remote scripts; the pipe-to-shell form below is the less-safe convenience option.
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh | bash
Python Dependency Errors
Symptom: ModuleNotFoundError: No module named 'requests'
Solution:
Dependencies belong in the managed runtime. For a plugin install, run:
/seo doctor
/seo setup
For a manual install, run:
~/.claude/skills/seo/scripts/claude-seo doctor
~/.claude/skills/seo/scripts/claude-seo setup
Do not install individual packages, use pip --user, or create a PATH shim.
requirements.txt Not Found
Symptom: No such file: requirements.txt after install
Solution: For plugin installs, reinstall the plugin first:
/plugin install claude-seo@agricidaniel-claude-seo
For manual installs, requirements.txt is copied to the skill directory:
ls ~/.claude/skills/seo/requirements.txt
If missing, download it directly:
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/requirements.txt \
-o ~/.claude/skills/seo/requirements.txt
Windows Python Detection Issues
Symptom: python is not recognized or pip points to wrong Python
Solution (v1.2.0+): The Windows installer now tries both python and py -3. If both fail:
- Install Python from python.org and check "Add to PATH"
- Rerun
install.ps1. It usesCLAUDE_SEO_PYTHONwhen set, otherwise the first ofpy -3,python3andpythonthat is Python 3.11 to 3.14, otherwise the newest ofpy -3.14down topy -3.11 - If
py -3is a newer Python that Claude SEO does not support yet (such as 3.15), install 3.14 alongside it, or setCLAUDE_SEO_PYTHONto a supportedpython.exe - Run
/seo doctorafter installation
Playwright Screenshot Errors
Symptom: playwright._impl._errors.Error: Executable doesn't exist
Solution: rerun managed setup so the browser is installed through the same interpreter and persistent browser directory:
/seo setup
/seo doctor
Permission Denied Errors
Symptom: Permission denied when running scripts
Solution:
chmod +x ~/.claude/skills/seo/scripts/*.py
Subagent Not Found
Symptom: Agent 'seo-technical' not found
Solution:
For plugin installs, check /plugin list and reinstall claude-seo@agricidaniel-claude-seo; subagents load from the plugin, not ~/.claude/agents/.
For manual installs:
- Verify agent files exist:
ls ~/.claude/agents/seo-*.md
- Check agent frontmatter:
head -5 ~/.claude/agents/seo-technical.md
- Re-install agents:
cp /path/to/claude-seo/agents/*.md ~/.claude/agents/
Timeout Errors
Symptom: Request timed out after 30 seconds
Solutions:
- The target site may be slow: try again
- Increase timeout in script calls
- Check your network connection
- Some sites block automated requests
Schema Validation False Positives
Symptom: Hook blocks valid schema
Check:
- Ensure placeholders are replaced
- Verify @context is
https://schema.org - Check for deprecated/retired types: HowTo and SpecialAnnouncement, plus the June 2025 retirements (ClaimReview, VehicleListing, EstimatedSalary, LearningVideo, and the CourseInfo carousel)
- FAQPage rich results were retired for all sites on 2026-05-07. The hook does not block it because it remains a valid Schema.org type, but no AI or ranking benefit is confirmed.
- Validate at Google's Rich Results Test
Slow Audit Performance
Symptom: Full audit takes too long
Solutions:
- Audit crawls up to 500 pages: large sites take time
- Subagents run in parallel to speed up analysis
- For faster checks, use
/seo pageon specific URLs - Check if site has slow response times
Getting Help
Check the docs: Review COMMANDS.md and ARCHITECTURE.md
GitHub Issues: Report bugs at the repository
Logs: Check Claude Code's output for error details
Debug Mode
To see detailed output, check Claude Code's internal logs or run scripts directly:
# Test fetch
python3 ~/.claude/skills/seo/scripts/fetch_page.py https://example.com
# Test parse
python3 ~/.claude/skills/seo/scripts/parse_html.py page.html --json
# Test screenshot
python3 ~/.claude/skills/seo/scripts/capture_screenshot.py https://example.com