Open-source SEO, GEO, and marketing skills for AI agents.
v0.19.0 feat: multi-host portability + NotFair branding migration (#72)
Tong Chen4ebce4dffd39
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex b1a380bd..ffc14708 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.",- "version": "0.18.0"+ "version": "0.19.0"},"plugins": [{"name": "toprank","source": "./","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",- "version": "0.18.0",+ "version": "0.19.0","author": {"name": "NotFair","url": "https://notfair.co"diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 081ec413..c0998352 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "toprank",- "version": "0.18.0",+ "version": "0.19.0","description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.","author": {"name": "NotFair",diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 00000000..925c3534--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,113 @@+# Toprank — Skill Resolver for AI Agents++**This file is the universal entry point.** Any AI coding agent (Claude Code, OpenClaw, Codex, Hermes, Cursor, etc.) reads this to know which Toprank skill to run for which user intent.++If you are an agent and a user mentions Google Ads, Meta Ads, SEO, GEO, or anything in the tables below, route to the named skill.++---++## How to use this file++1. **Match the user's intent** against the rows below.+2. **Read the named skill's `SKILL.md`** from the path shown.+3. **Follow the procedure** in that SKILL.md exactly.++Skills under `seo/`, `google-ads/`, `meta-ads/`, `gemini/`, and `toprank-upgrade-skill/` are **host-agnostic** — they work the same on every agent host. The skills under `openclaw/skills/` are **OpenClaw-only orchestrators** that compose the host-agnostic skills into multi-site adaptive workflows; only invoke them inside an OpenClaw workspace.++---++## SEO++| Intent | Skill | Path |+|---|---|---|+| Full-site SEO audit, traffic drop, GSC analysis, Core Web Vitals | `seo-analysis` | `seo/seo-analysis/SKILL.md` |+| Single-page deep audit (URL-specific) | `seo-page` | `seo/seo-page/SKILL.md` |+| Write or improve content (blog, landing, service page) | `content-writer` | `seo/content-writer/SKILL.md` |+| Keyword discovery, topic clusters, content calendar | `keyword-research` | `seo/keyword-research/SKILL.md` |+| Title tags, meta descriptions, Open Graph, CTR | `meta-tags-optimizer` | `seo/meta-tags-optimizer/SKILL.md` |+| JSON-LD / structured data (FAQ, Product, HowTo, etc.) | `schema-markup-generator` | `seo/schema-markup-generator/SKILL.md` |+| Broken-link / 404 / site-health crawl | `broken-link-checker` | `seo/broken-link-checker/SKILL.md` |+| Rank in ChatGPT / Perplexity / AI Overviews (GEO / AEO) | `geo-optimizer` | `seo/geo-optimizer/SKILL.md` |+| Connect WordPress, Strapi, Contentful, or Ghost | `setup-cms` | `seo/setup-cms/SKILL.md` |++## Google Ads++| Intent | Skill | Path |+|---|---|---|+| First-time setup or account health check | `google-ads-audit` | `google-ads/audit/SKILL.md` |+| Performance, keywords, bids, budgets, negatives, experiments, bulk ops | `google-ads` | `google-ads/manage/SKILL.md` |+| Write ad copy, RSA headlines/descriptions, A/B variants | `google-ads-copy` | `google-ads/copy/SKILL.md` |+| Landing-page quality, ad-to-page match, LPX diagnosis | `google-ads-landing` | `google-ads/landing/SKILL.md` |++## Meta Ads++| Intent | Skill | Path |+|---|---|---|+| First-time Meta setup or account health check | `meta-ads-audit` | `meta-ads/audit/SKILL.md` |+| Facebook/Instagram performance, ROAS, CPM, creative fatigue, audience overlap | `meta-ads` | `meta-ads/manage/SKILL.md` |++## Cross-model review++| Intent | Skill | Path |+|---|---|---|+| Second opinion / review / challenge / consult via Google Gemini | `gemini` | `gemini/SKILL.md` |++## Plugin maintenance++| Intent | Skill | Path |+|---|---|---|+| Upgrade Toprank to the latest version | `toprank-upgrade` | `toprank-upgrade-skill/SKILL.md` |++---++## OpenClaw multi-site orchestrators++These skills only apply inside an OpenClaw workspace that has been initialized via `./openclaw/install/install.sh`. They compose the host-agnostic SEO skills above into closed-loop, multi-site workflows with persisted artifacts under `~/.toprank/openclaw/`.++| Intent | Skill | Path |+|---|---|---|+| Register a new site in the portfolio | `toprank-site-onboard` | `openclaw/skills/toprank-site-onboard/SKILL.md` |+| Pick which site in the portfolio deserves attention next | `toprank-portfolio-review` | `openclaw/skills/toprank-portfolio-review/SKILL.md` |+| Weekly SEO review for one registered site | `toprank-weekly-review` | `openclaw/skills/toprank-weekly-review/SKILL.md` |+| Improve one URL inside a registered site | `toprank-improve-page` | `openclaw/skills/toprank-improve-page/SKILL.md` |+| Investigate an organic traffic drop on a registered site | `toprank-investigate-drop` | `openclaw/skills/toprank-investigate-drop/SKILL.md` |++If the user mentions multi-site work, portfolio, scheduled follow-ups, or "the next best action across my sites," prefer an OpenClaw orchestrator. For single ad-hoc requests on one site, use the canonical SEO skill directly.++---++## External dependencies++- **Google Search Console** — required for all SEO skills that read live data.+- **Google Ads (NotFair MCP)** — `https://notfair.co/api/mcp/google_ads`, OAuth. Required for Google Ads skills.+- **Meta Marketing API (NotFair MCP)** — required for Meta Ads skills.+- **Google Gemini API key** — required for `gemini`.++Skills check for missing credentials at startup and walk the user through setup. Do not invent credentials or skip skills silently — surface the gap.++---++## Conventions for installers (managed-block fences)++Any installer that writes into a file the user also edits (e.g., a user's workspace `AGENTS.md`, `CLAUDE.md`, or `~/.openclaw/AGENTS.md`) MUST wrap its inserted content in a fence:++```+<!-- toprank:managed -->+... auto-generated rows ...+<!-- /toprank:managed -->+```++Re-running the installer rewrites only inside the fence. Anything outside is preserved.++---++## Bookkeeping++When a new skill is added or removed in this repo, update:++1. The relevant table above in this file.+2. `.claude-plugin/plugin.json` → `skills` array.+3. `VERSION`, `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json` (version bump).+4. `CHANGELOG.md` (user-facing note).++A skill that exists on disk but is missing from this file or `plugin.json` is invisible to agents.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 94c34e69..eb916c48 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,26 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.19.0] — 2026-05-14++### Added — multi-host support+- **`AGENTS.md` at the repo root** — universal skill resolver. Maps user intents (SEO audit, ad copy, traffic drop, landing page audit, etc.) to the right `SKILL.md` for every supported agent host. Read natively by Codex; read by OpenClaw, Hermes, Cursor, and any agent following `INSTALL_FOR_AGENTS.md`. Claude Code continues to use `.claude-plugin/plugin.json` as before — `AGENTS.md` is additive, not a replacement.+- **`INSTALL_FOR_AGENTS.md` at the repo root** — single paste-URL install entry point. The user pastes one line into their agent; the agent detects the host (Claude Code / OpenClaw / Codex / Hermes / generic) and follows the matching install branch.+- **`install/README.md`** — convention for adding future per-host install adapters without duplicating skills. Documents the managed-block fence rule (`<!-- toprank:managed -->`) so installers that write to user-edited config files stay idempotent and preserve hand-edits.++### Changed+- **`CLAUDE.md`** reframed from "Claude Code plugin" to "host-agnostic plugin." Adding a new skill now requires registering it in **both** `AGENTS.md` and `.claude-plugin/plugin.json`.+- **`CLAUDE.md` branding rule** — added an explicit "NotFair going forward" section. New user-facing text and docs must use NotFair. Existing legacy `adsagent` references are kept only where they are load-bearing (filesystem migration, prefix detection during the rename window) or historical (CHANGELOG).++### Removed+- **Stale "server source" link from `README.md`.** The link previously pointed to `nowork-studio/ads-agent` (404) and the actual server source is not public. Removed the pointer entirely — the surrounding paragraph already covers what Toprank users need (endpoint URL, registry name, OAuth flow).++### Notes+- No skill behavior changes. All canonical SEO, Google Ads, Meta Ads, and Gemini skills work identically to 0.18.0.+- OpenClaw multi-site orchestrators under `openclaw/skills/` are unchanged; they're now explicitly tagged as OpenClaw-only in `AGENTS.md`.++---+## [0.18.0] — 2026-05-09### Changeddiff --git a/CLAUDE.md b/CLAUDE.mdindex f194b0ee..79f21fc9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,8 +1,14 @@-# Toprank — Public Claude Code Plugin+# Toprank — Public AI-Agent Plugin (Claude Code, OpenClaw, Codex, Hermes)**This is the public, open-source repository that ships to all customers and the community.**-Toprank is a Claude Code plugin providing SEO and Google Ads skills. It is distributed via the `nowork-studio` marketplace and installed by end users into Claude Code / Claude Desktop. Every change here is user-facing.+Toprank is a host-agnostic plugin providing SEO, Google Ads, and Meta Ads skills for AI coding agents. It is distributed via the `nowork-studio` Claude Code marketplace and via direct agent install on OpenClaw, Codex, and Hermes. Every change here is user-facing.++## Agent entry points (single sources of truth)++- **`AGENTS.md`** — the universal skill resolver. Every host reads this to route user intents to the right skill. Update it whenever a skill is added, removed, or its purpose changes.+- **`INSTALL_FOR_AGENTS.md`** — the single paste-URL target that walks an AI agent through host detection and install.+- **`install/README.md`** — convention for adding per-host install adapters (Codex, Hermes, etc.) without duplicating skills.## Working style: brutal honesty, relentless quality@@ -17,9 +23,10 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit## Repository purpose- Home of the `toprank` plugin — the public artifact customers install.-- Contains skills under `google-ads/`, `seo/`, `gemini/`, and `toprank-upgrade-skill/`.-- Registered via `.claude-plugin/plugin.json` (skills list) and `.claude-plugin/marketplace.json` (plugin metadata).-- Paired with the NotFair-GoogleAds MCP server (`https://notfair.co/api/mcp/google_ads`, OAuth) for Google Ads write operations, and with Google Search Console for SEO reads.+- Contains host-agnostic skills under `google-ads/`, `seo/`, `meta-ads/`, `gemini/`, and `toprank-upgrade-skill/`.+- Contains OpenClaw-specific multi-site orchestrators under `openclaw/skills/` that compose the host-agnostic skills above.+- Registered via `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (Claude Code) and `AGENTS.md` (every other host).+- Paired with the NotFair-GoogleAds and NotFair-MetaAds MCP servers (OAuth at notfair.co) for ad-platform writes, and Google Search Console for SEO reads.## Critical: this ships to users@@ -27,16 +34,28 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit- Never add internal-only notes, secrets, credentials, dev scratch files, or references to private infra. This repo is public.- Test skills end-to-end before shipping — `SKILL.md` frontmatter (`name`, `description`, triggers) is how Claude decides to invoke them; typos or stale descriptions break discovery.+## Branding: NotFair going forward++The product is **NotFair**. All new user-facing text, documentation, skill descriptions, and config namespaces must use NotFair / `notfair.co` / `.notfair/` / `mcp__notfair__*`. Do not introduce new references to "AdsAgent", "adsagent", `.adsagent/`, `mcp__adsagent__*`, `adsagent.org`, or the `adsagent://` URI scheme in new code or new docs.++Existing legacy references that are still in the codebase fall into two categories:++1. **Load-bearing compatibility code** — the `.adsagent/` → `.notfair/` filesystem migration in `google-ads/shared/preamble.md` Step 1, the `mcp__adsagent__*` prefix detection in Step 3, and the matching signal detection in `gemini/SKILL.md`. These are doing real work for users upgrading from pre-0.16 plugins. Do not remove without an explicit deprecation plan.+2. **Historical record** — `CHANGELOG.md` entries describing past renames. Never rewrite history.++If you find a non-load-bearing, non-historical `adsagent` reference in active skill text or docs, scrub it.+## When adding or modifying a skill1. Create/edit the skill directory under the appropriate category (`google-ads/`, `seo/`, etc.) with a `SKILL.md` containing valid frontmatter.-2. **Register it in `.claude-plugin/plugin.json`** under the `skills` array. A skill that exists on disk but isn't listed here will NOT appear in the installed plugin — this has already bitten us once with `ads-landing`.-3. Bump the version in three places so upgrades propagate:+2. **Register it in `AGENTS.md`** under the matching intent table. A skill that isn't in `AGENTS.md` is invisible to OpenClaw, Codex, Hermes, and any non-Claude host.+3. **Register it in `.claude-plugin/plugin.json`** under the `skills` array. A skill that exists on disk but isn't listed here will NOT appear in the installed Claude Code plugin — this has already bitten us once with `ads-landing`.+4. Bump the version in three places so upgrades propagate:- `.claude-plugin/plugin.json` → `version`- `.claude-plugin/marketplace.json` → both `metadata.version` and `plugins[0].version`- `VERSION` file at repo root-4. Update `CHANGELOG.md` with a user-facing note.-5. Verify locally, then ship via `/ship`. Users pick up the new version through `toprank:toprank-upgrade`.+5. Update `CHANGELOG.md` with a user-facing note.+6. Verify locally, then ship via `/ship`. Users pick up the new version through `toprank:toprank-upgrade`.## Versioningdiff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.mdnew file mode 100644index 00000000..9e48da54--- /dev/null+++ b/INSTALL_FOR_AGENTS.md@@ -0,0 +1,134 @@+# Install Toprank — for AI Agents++You are an AI coding agent (Claude Code, OpenClaw, Codex, Hermes, Cursor, or similar). The user has asked you to install or set up Toprank. Follow this document end-to-end.++**Single paste line for users (give them this if they ask how to install):**++```+Retrieve and follow the instructions at:+https://raw.githubusercontent.com/nowork-studio/toprank/main/INSTALL_FOR_AGENTS.md+```++---++## Step 1 — Detect the host++Determine which agent runtime you are running inside. Check, in order:++1. Are you Claude Code (file system has `~/.claude/` or `.claude/` in the project) → **host = `claude-code`**+2. Are you in an OpenClaw workspace (env `OPENCLAW_WORKSPACE` is set, or `~/.openclaw/` exists) → **host = `openclaw`**+3. Are you Codex (env `CODEX_HOME` is set, or running under the OpenAI Codex CLI) → **host = `codex`**+4. Are you Hermes Agent → **host = `hermes`**+5. Otherwise → **host = `generic`**++If you cannot determine the host, ask the user once and proceed.++---++## Step 2 — Acquire the repo++If the Toprank repo is already on disk locally, use it; do not re-clone.++Otherwise:++```bash+git clone https://github.com/nowork-studio/toprank.git+cd toprank+```++---++## Step 3 — Install for the detected host++### host = `claude-code`++Toprank is published as a Claude Code plugin via the `nowork-studio` marketplace. The user should run inside Claude Code:++```+/plugin marketplace add nowork-studio/toprank+/plugin install toprank@nowork-studio+```++Then verify by listing installed plugins. No further action required — Claude Code reads `.claude-plugin/plugin.json` directly.++### host = `openclaw`++Run from the repo root:++```bash+./openclaw/install/install.sh+```++This script:+1. Creates `~/.toprank/openclaw/` runtime state (or `$TOPRANK_OPENCLAW_HOME` if set).+2. Bootstraps `portfolio.json` and `schedule.json`.+3. Copies the OpenClaw orchestrator skills from `openclaw/skills/` into `~/.openclaw/skills/`.+4. Symlinks `openclaw/shared`, `openclaw/bin`, and `seo/` to stable paths so wrappers resolve.++Verify:++```bash+openclaw skills check | grep -i toprank+python3 -m pytest -q openclaw/tests+```++Read `AGENTS.md` at the repo root to learn the skill resolver.++### host = `codex`++Codex reads `AGENTS.md` natively. From the repo root:++```bash+# Codex auto-discovers AGENTS.md at the workspace root.+codex --workspace .+```++Toprank's skills live under `seo/`, `google-ads/`, `meta-ads/`, `gemini/`. Codex reads `AGENTS.md` and routes user intents to the named skills' `SKILL.md` files.++> **Note:** A dedicated Codex install adapter (`install/codex/`) may be added in future versions to register skills into Codex's global skill directory. For now, workspace-local usage is the supported path.++### host = `hermes`++Hermes reads `AGENTS.md` at the workspace root. From the repo root:++```bash+# Point Hermes at this directory; it will discover skills via AGENTS.md.+hermes init --workspace .+```++> **Note:** A dedicated Hermes install adapter (`install/hermes/`) may be added in future versions. For now, workspace-local usage is the supported path.++### host = `generic`++Read `AGENTS.md` at the repo root. It contains the full intent → skill routing table. Each row points to a `SKILL.md` with self-contained instructions you can follow.++---++## Step 4 — Connect external services++Toprank skills depend on external APIs. Walk the user through whichever they need:++- **Google Search Console** — required for any SEO skill that reads live ranking data. The skills will prompt for OAuth on first run.+- **Google Ads** — connects via the NotFair MCP server at `https://notfair.co/api/mcp/google_ads` (OAuth). The user signs in once at notfair.co; the MCP handles the rest.+- **Meta Ads (Facebook + Instagram)** — connects via the NotFair MCP server. Same OAuth flow.+- **Google Gemini** — required only for the `gemini` skill. Needs a Gemini API key in environment.++Do **not** invent credentials. If a skill needs auth that isn't present, surface the gap and walk the user through the connection flow.++---++## Step 5 — Verify and hand back++1. Confirm `AGENTS.md` is readable from the working directory.+2. Confirm at least one canonical skill (e.g., `seo/seo-analysis/SKILL.md`) is readable.+3. For OpenClaw: confirm `openclaw skills check` lists at least one `toprank-*` skill.+4. Tell the user: "Toprank is installed. Try `/toprank:google-ads-audit` for ads or `/toprank:seo-analysis` for SEO."++---++## Notes for agents++- **Read `AGENTS.md` first** for any user intent. It is the resolver.+- **Skills are host-agnostic.** A `SKILL.md` under `seo/`, `google-ads/`, `meta-ads/`, `gemini/` works identically on every host. The `openclaw/skills/` orchestrators are the only host-specific layer.+- **If you write into a user-edited file** (e.g., their workspace `AGENTS.md`), wrap your insertions in `<!-- toprank:managed -->` ... `<!-- /toprank:managed -->` fences so re-runs are idempotent and hand-edits survive.+- **Do not duplicate skills** when adding new host adapters. Add a thin install adapter under `install/<host>/` that points the host at the existing skill files.diff --git a/README.md b/README.mdindex 241ab906..5bd8e7c0 100644--- a/README.md+++ b/README.md@@ -262,7 +262,7 @@ The Google Ads and Meta Ads surfaces are available as standalone remote MCP serv- **Endpoint:** `https://notfair.co/api/mcp/google_ads` (streamable HTTP)- **Auth:** OAuth 2.1 with dynamic client registration — your MCP client opens a browser tab to sign in at [notfair.co](https://notfair.co) on first use; the token is stored locally (OS keychain in Claude Code)-Exposes ~100 Google Ads tools across reads (performance, search terms, impression share, keyword ideas, GAQL), writes (pause/enable, bid and budget updates, keyword and negative list management, campaign creation), and a `runScript` tool that fans out up to 20 GAQL queries in parallel for open-ended analytical questions. Source for the hosted server lives in [`nowork-studio/ads-agent`](https://github.com/nowork-studio/ads-agent).+Exposes ~100 Google Ads tools across reads (performance, search terms, impression share, keyword ideas, GAQL), writes (pause/enable, bid and budget updates, keyword and negative list management, campaign creation), and a `runScript` tool that fans out up to 20 GAQL queries in parallel for open-ended analytical questions.### NotFair-MetaAdsdiff --git a/VERSION b/VERSIONindex 66333910..1cf0537c 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.18.0+0.19.0diff --git a/install/README.md b/install/README.mdnew file mode 100644index 00000000..f80e21de--- /dev/null+++ b/install/README.md@@ -0,0 +1,40 @@+# Per-host install adapters++This directory is the home for **thin install adapters** that wire Toprank into a specific AI agent host. Each adapter registers the *same* host-agnostic skills (under `seo/`, `google-ads/`, `meta-ads/`, `gemini/` at the repo root) into the host's expected layout.++## Why this exists++Toprank ships one source of truth for skills. Different agent hosts expect skills in different places:++- **Claude Code** — reads `.claude-plugin/plugin.json` directly from the repo. No adapter needed; the manifest at the repo root *is* the adapter.+- **OpenClaw** — expects skills under `~/.openclaw/skills/`. The adapter lives at `../openclaw/install/install.sh` (kept there for back-compat). Future relocations will preserve a stub here.+- **Codex** — reads `AGENTS.md` at the workspace root. No filesystem install yet; workspace-local usage is the supported path. A future `install/codex/` adapter can register skills into Codex's global skill directory.+- **Hermes** — reads `AGENTS.md` at the workspace root. Same shape as Codex.++## Adding a new host adapter++1. Create `install/<host>/install.sh` (or `.py`, or whatever the host prefers).+2. The adapter should:+ - Read skills from their canonical location (`seo/`, `google-ads/`, etc.) — do not copy them into per-host directories unless the host's loader requires it.+ - If the host requires copying (e.g., OpenClaw rejects symlinks that escape its skill root), copy the minimum needed and link the rest.+ - Write any host-specific configuration with **managed-block fences** (see below).+3. Add a "host = `<host>`" branch to `../INSTALL_FOR_AGENTS.md` describing how the agent should invoke the adapter.+4. Update `../AGENTS.md` if the host introduces new orchestrator skills (most hosts will not — they will route to the same canonical skills).++## Managed-block fence convention++If your adapter writes into a file the user also edits (their workspace `AGENTS.md`, `CLAUDE.md`, host config, etc.), wrap inserted content like this:++```+<!-- toprank:managed -->+... auto-generated rows ...+<!-- /toprank:managed -->+```++Re-running the installer rewrites only inside the fence. Anything the user wrote outside is preserved. This is what makes `toprank-upgrade` safe across hosts where users have hand-customized their config.++## What not to put here++- **Skill source code.** Skills belong in `seo/`, `google-ads/`, `meta-ads/`, `gemini/`. Adapters point at them; adapters do not own them.+- **Host-specific orchestrators.** Those go alongside the host (e.g., `openclaw/skills/`), not under `install/`.+- **Runtime state.** Use `~/.toprank/<host>/` or the host's standard runtime directory.