Open-source SEO, GEO, and marketing skills for AI agents.
chore: consolidate root files into README (#34)
Tong Chene509b93d0f03
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f2696a13..108db379 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.10.0.1] — 2026-04-08++### Changed+- **Consolidated root files** — Merged `CONNECTORS.md` and `CONTRIBUTING.md` into `README.md` to reduce file count without losing content. Connectors section now lives under "## Connectors" and contributing guide under "## Contributing" in the main README.+- **Updated install test** — Test suite now checks for connector content in `README.md` instead of the removed `CONNECTORS.md` file.+- **Added `seo-page` to directory tree** in README to reflect the new single-page analysis skill.++### Removed+- **`CONNECTORS.md`** — Content moved to README.md.+- **`CONTRIBUTING.md`** — Content moved to README.md.+- **`requirements-test.lock`** — Stale lock file that didn't match `requirements-test.txt`.++---+## [0.10.0] — 2026-04-08### Addeddiff --git a/CONNECTORS.md b/CONNECTORS.mddeleted file mode 100644index fb44de6a..00000000--- a/CONNECTORS.md+++ /dev/null@@ -1,48 +0,0 @@-# Connectors--Toprank skills reference external tools using the `~~category` placeholder pattern. This makes skills tool-agnostic — they work with any MCP server that provides the required capability.--## Connected Tools--| Category | Placeholder | Default Server | Alternatives |-|----------|-------------|---------------|--------------|-| Google Ads | `~~google-ads` | [AdsAgent MCP](https://www.adsagent.org) (`mcp__adsagent__*`) | Google Ads MCP (`mcp__google_ads_mcp__*`) |-| Search Console | `~~search-console` | gcloud CLI + Search Console API | Any GSC-compatible MCP server |-| CMS | `~~cms` | Direct API (WordPress REST, Strapi, Contentful, Ghost) | Any CMS MCP server |--## How Connectors Work--Skills use conditional blocks based on available tools:--```markdown-If ~~google-ads is connected:-- Pull campaign performance data-- Manage keywords and bids--If ~~search-console is connected:-- Fetch GSC performance data-- Run URL Inspection API checks-```--If a connector is not available, the skill gracefully degrades — for example, `seo-analysis` can still run a technical crawl without GSC data.--## Setup--### Google Ads (used by: ads, ads-audit, ads-copy)--See `google-ads/shared/preamble.md`. Requires:-1. AdsAgent API key from [adsagent.org](https://www.adsagent.org)-2. Set `ADSAGENT_API_KEY` environment variable-3. The `.mcp.json` in this plugin auto-configures the MCP server--### Search Console (used by: seo-analysis)--See `seo/shared/preamble.md`. Requires:-1. Google Cloud SDK (`gcloud`) installed-2. Search Console API enabled on your GCP project-3. OAuth login with the Google account that owns your GSC properties--### CMS (used by: seo-analysis, setup-cms)--Run `/setup-cms` to configure. Supports WordPress, Strapi, Contentful, and Ghost.-Credentials are saved to `.env.local` in the project root.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mddeleted file mode 100644index 9f372d6b..00000000--- a/CONTRIBUTING.md+++ /dev/null@@ -1,52 +0,0 @@-# Contributing--Thanks for wanting to contribute! Here's how to get started.--## Adding a Skill--Each skill lives in its own folder under a category directory:--```-seo/ <- SEO skills go here-└── your-skill-name/- ├── SKILL.md <- required- ├── scripts/ <- optional- └── references/ <- optional--google-ads/ <- Google Ads skills go here-└── your-skill-name/- └── SKILL.md <- required-```--### SKILL.md--Every skill needs a frontmatter header:--```yaml-----name: your-skill-name-description: >- One paragraph. Explain what the skill does AND when to trigger it.- Be specific about trigger phrases.-----```--Then the body: step-by-step instructions Claude will follow. Write in the imperative.--> The update-check preamble is auto-injected by `./setup` — you don't need to add it manually.--### Scripts--- Python 3.8+ stdlib only (or `requests`)-- Accept `--output` for file output-- stderr for progress, stdout for data--## Pull Requests--1. One skill per PR-2. Test your skill before submitting-3. Bump `VERSION` and update `CHANGELOG.md`--## Questions--Open an issue. We're friendly.diff --git a/README.md b/README.mdindex 5bc94c5c..e7bc99d9 100644--- a/README.md+++ b/README.md@@ -168,6 +168,7 @@ toprank/│ ├── keyword-research/ <- keyword discovery + topic clusters│ ├── meta-tags-optimizer/ <- title tags, meta descriptions, OG│ ├── schema-markup-generator/ <- JSON-LD structured data+│ ├── seo-page/ <- single-page deep analysis│ └── setup-cms/ <- CMS connector├── toprank-upgrade-skill/ <- self-updater├── test/ <- unit + LLM-judge eval tests@@ -176,9 +177,48 @@ toprank/---+## Connectors++Toprank skills reference external tools using the `~~category` placeholder pattern. This makes skills tool-agnostic — they work with any MCP server that provides the required capability.++| Category | Placeholder | Default Server | Alternatives |+|----------|-------------|---------------|--------------|+| Google Ads | `~~google-ads` | [AdsAgent MCP](https://www.adsagent.org) (`mcp__adsagent__*`) | Google Ads MCP (`mcp__google_ads_mcp__*`) |+| Search Console | `~~search-console` | gcloud CLI + Search Console API | Any GSC-compatible MCP server |+| CMS | `~~cms` | Direct API (WordPress REST, Strapi, Contentful, Ghost) | Any CMS MCP server |++Skills use conditional blocks based on available tools. If a connector is not available, the skill gracefully degrades — for example, `seo-analysis` can still run a technical crawl without GSC data.++**Setup:**+- **Google Ads:** See `google-ads/shared/preamble.md`. Get a free API key from [adsagent.org](https://www.adsagent.org), set `ADSAGENT_API_KEY`, and the `.mcp.json` auto-configures the MCP server.+- **Search Console:** See `seo/shared/preamble.md`. Requires Google Cloud SDK, Search Console API enabled, and OAuth login.+- **CMS:** Run `/toprank:setup-cms` to configure WordPress, Strapi, Contentful, or Ghost.++---+## Contributing-Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.+Each skill lives in its own folder under a category directory:++```+seo/ <- SEO skills go here+└── your-skill-name/+ ├── SKILL.md <- required+ ├── scripts/ <- optional+ └── references/ <- optional++google-ads/ <- Google Ads skills go here+└── your-skill-name/+ └── SKILL.md <- required+```++**SKILL.md** needs a frontmatter header with `name` and `description`, then step-by-step instructions in the imperative.++**Scripts:** Python 3.8+ stdlib only (or `requests`). Accept `--output` for file output. stderr for progress, stdout for data.++**Pull requests:** One skill per PR. Test your skill before submitting. Bump `VERSION` and update `CHANGELOG.md`.++Questions? Open an issue.---diff --git a/VERSION b/VERSIONindex 78bc1abd..320497a7 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.10.0+0.10.0.1diff --git a/requirements-test.lock b/requirements-test.lockdeleted file mode 100644index 734317a6..00000000--- a/requirements-test.lock+++ /dev/null@@ -1,63 +0,0 @@-#-# This file is autogenerated by pip-compile with Python 3.12-# by the following command:-#-# pip-compile --output-file=requirements-test.lock requirements-test.txt-#-annotated-types==0.7.0- # via pydantic-anthropic==0.86.0- # via -r requirements-test.txt-anyio==4.13.0- # via- # anthropic- # httpx-certifi==2026.2.25- # via- # httpcore- # httpx-distro==1.9.0- # via anthropic-docstring-parser==0.17.0- # via anthropic-h11==0.16.0- # via httpcore-httpcore==1.0.9- # via httpx-httpx==0.28.1- # via anthropic-idna==3.11- # via- # anyio- # httpx-iniconfig==2.3.0- # via pytest-jiter==0.13.0- # via anthropic-packaging==26.0- # via pytest-pluggy==1.6.0- # via pytest-pydantic==2.12.5- # via anthropic-pydantic-core==2.41.5- # via pydantic-pygments==2.19.2- # via pytest-pytest==9.0.2- # via- # -r requirements-test.txt- # pytest-timeout-pytest-timeout==2.4.0- # via -r requirements-test.txt-sniffio==1.3.1- # via anthropic-typing-extensions==4.15.0- # via- # anthropic- # anyio- # pydantic- # pydantic-core- # typing-inspection-typing-inspection==0.4.2- # via pydanticdiff --git a/test/install.test.sh b/test/install.test.shindex 59987ef1..1dc6c9fd 100755--- a/test/install.test.sh+++ b/test/install.test.sh@@ -170,14 +170,13 @@ assert_contains "$REPO_ROOT/.mcp.json" "adsagent" ".mcp.json has adsagent serverassert_contains "$REPO_ROOT/.mcp.json" "mcp-remote" ".mcp.json uses mcp-remote"assert_contains "$REPO_ROOT/.mcp.json" "ADSAGENT_API_KEY" ".mcp.json references API key env var"-# ─── Test 6: CONNECTORS.md exists ───────────────────────────+# ─── Test 6: Connectors section in README ─────────────────────echo ""echo "=== 6. Connectors ==="-assert_file "$REPO_ROOT/CONNECTORS.md" "CONNECTORS.md exists"-assert_contains "$REPO_ROOT/CONNECTORS.md" "~~google-ads" "CONNECTORS.md has Google Ads placeholder"-assert_contains "$REPO_ROOT/CONNECTORS.md" "~~search-console" "CONNECTORS.md has Search Console placeholder"+assert_contains "$REPO_ROOT/README.md" "~~google-ads" "README.md has Google Ads connector placeholder"+assert_contains "$REPO_ROOT/README.md" "~~search-console" "README.md has Search Console connector placeholder"# ─── Test 7: Reference docs exist ───────────────────────────