Contributing to claude-seo

Thanks for your interest in contributing! Here's how to get involved.

Reporting Bugs

Open a GitHub Issue with:

• Your OS and Python version
• The full error output (copy from terminal)
• The command or step that failed
• The URL you were analyzing (if applicable)

Suggesting Features

Use GitHub Discussions for feature ideas and questions.

Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Test with a sample URL before submitting
5. Submit a PR with a clear description of what changed and why

Development Setup

Option A: Local install

git clone https://github.com/YOUR_USERNAME/claude-seo.git
cd claude-seo
bash install.sh

Option B: GitHub Codespaces / VS Code Dev Containers

A .devcontainer/devcontainer.json is included so you can develop without any local setup. Two paths:

• GitHub Codespaces: click Code -> Codespaces -> Create codespace on main on the repo's GitHub page. You get a fully provisioned Python 3.12 environment with requirements.txt installed and Playwright + Chromium ready, in about 60 seconds.
• VS Code Remote Containers: with the Dev Containers extension installed, clone the repo locally then run Dev Containers: Reopen in Container from the command palette.

Both paths use the same image (mcr.microsoft.com/devcontainers/python:3.12) and post-create command (pip install -r requirements.txt && playwright install chromium). No additional setup needed for either.

Guidelines

• All Python scripts should output JSON for Claude Code to parse
• Shell scripts should use set -euo pipefail for safety
• SKILL.md files must stay under 500 lines
• Reference files should be focused and under 200 lines
• Follow kebab-case naming for all directories and files
• Keep dependencies minimal

Code Style

• Python: Follow PEP 8 conventions. Use ruff check or flake8 for linting before submitting
• Shell: Use set -euo pipefail and quote all variables
• Markdown: Keep lines under 120 characters where practical

Community Extensions (Pro Hub Challenge)

Claude SEO accepts community-built extensions through challenges and PRs. v1.9.0 integrated 5 challenge submissions and v1.9.7 added 9 community pull requests from 7 contributors. See CONTRIBUTORS.md for the full credits.

To submit a community extension: 1. Build your skill/agent/script following the patterns in this repo 2. Keep SKILL.md under 500 lines, references under 200 lines 3. All URL-fetching scripts must route through scripts/url_safety.py — the canonical SSRF / DNS-rebinding layer (validate_url(), safe_requests_session()); never fetch a user-supplied URL without it. (google_auth.py is OAuth token lifecycle only — not an SSRF guard.) 4. Include original_author in your SKILL.md frontmatter metadata 5. Submit a PR or post in the AI Marketing Hub