Troubleshooting

Common Issues

Skill Not Loading

Symptom: /kimi-seo:seo command not recognized

Solutions:

For plugin installs, verify and reinstall through Kimi Code:

/plugins install https://github.com/bentocodeing/kimi-seo
/reload

For manual installs:

Verify installation:

ls ~/.kimi-code/skills/seo/SKILL.md

Check SKILL.md has proper frontmatter:

head -5 ~/.kimi-code/skills/seo/SKILL.md

Should start with --- followed by YAML.

Restart Kimi Code:

kimi

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/bentocodeing/kimi-seo/kimi/install.sh | bash

Python Dependency Errors

Symptom: ModuleNotFoundError: No module named 'requests'

Solution:

Dependencies belong in the managed runtime. For a plugin install, run:

/kimi-seo:seo doctor
/kimi-seo:seo setup

For a manual install, run:

~/.kimi-code/skills/seo/bin/kimi-seo doctor
~/.kimi-code/skills/seo/bin/kimi-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:

/plugins install https://github.com/bentocodeing/kimi-seo
/reload

For manual installs, requirements.txt is copied to the skill directory:

ls ~/.kimi-code/skills/seo/requirements.txt

If missing, download it directly:

curl -fsSL https://raw.githubusercontent.com/bentocodeing/kimi-seo/kimi/requirements.txt \
  -o ~/.kimi-code/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 resolves py -3, python3, then python
Run /kimi-seo:seo doctor after 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:

/kimi-seo:seo setup
/kimi-seo:seo doctor

Permission Denied Errors

Symptom: Permission denied when running scripts

Solution:

chmod +x ~/.kimi-code/skills/seo/scripts/*.py

Subagent Not Found

Symptom: Agent 'seo-technical' not found

Solution:

For plugin installs, check the installed plugin list and reinstall via /plugins install https://github.com/bentocodeing/kimi-seo followed by /reload; subagents load from the plugin, not ~/.agents/agents/.

For manual installs:

Verify agent files exist:

ls ~/.agents/agents/seo-*.md

Check agent frontmatter:

head -5 ~/.agents/agents/seo-technical.md

Re-install agents:

cp /path/to/kimi-seo/agents/*.md ~/.agents/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 /kimi-seo:seo page on 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 Kimi Code's output for error details

Debug Mode

To see detailed output, check Kimi Code's internal logs or run scripts directly:

# Test fetch
python3 ~/.kimi-code/skills/seo/scripts/fetch_page.py https://example.com

# Test parse
python3 ~/.kimi-code/skills/seo/scripts/parse_html.py page.html --json

# Test screenshot
python3 ~/.kimi-code/skills/seo/scripts/capture_screenshot.py https://example.com