Skip to content

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.md
index 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
### Added
diff --git a/CONNECTORS.md b/CONNECTORS.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
index 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/VERSION
index 78bc1abd..320497a7 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.10.0
+0.10.0.1
diff --git a/requirements-test.lock b/requirements-test.lock
deleted file mode 100644
index 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 pydantic
diff --git a/test/install.test.sh b/test/install.test.sh
index 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 server
assert_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 ───────────────────────────