Open-source SEO, GEO, and marketing skills for AI agents.
refactor: move API key verification to shared preamble and rewrite step flow (v0.9.9)
Yuting Zhong82ef776a978a
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 325a6624..0162167c 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "SEO and Google Ads skills for Claude Code",- "version": "0.9.8"+ "version": "0.9.9"},"plugins": [{"name": "toprank","source": "./","description": "SEO analysis, Google Ads management, keyword research, content optimization, schema markup, and meta tags optimization.",- "version": "0.9.8",+ "version": "0.9.9","author": {"name": "nowork-studio"},diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 05c36be8..80637edf 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "toprank",- "version": "0.9.8",+ "version": "0.9.9","description": "SEO analysis, Google Ads management, keyword research, content optimization, and schema markup tools powered by Google Search Console and Google Ads APIs.","author": {"name": "nowork-studio"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex aecd6b17..9d333d03 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.9.9] — 2026-04-08++### Changed+- **API key check moved to shared preamble** — Moved the `ADSAGENT_API_KEY` verification from the `/ads` skill into the shared preamble so all google-ads skills (`/ads`, `/ads-audit`, `/ads-copy`) verify the key automatically. The key is saved to `~/.claude/settings.json` under `env` (not config files) since the MCP server reads it from the environment.+- **Preamble rewrite** — Clean step numbering (0–5), fixed MCP detection to always run (was skipped for returning users with saved accountId), eliminated duplicate `listConnectedAccounts` calls, explicit deep-merge instructions for settings.json to avoid clobbering existing env vars.+- **Removed `apiKey` from config schema** — Config files (`.adsagent.json`, `config.json`) now only store `accountId`. API key storage is exclusively in `~/.claude/settings.json`.++---+## [0.9.8.0] — 2026-04-08### Addeddiff --git a/VERSION b/VERSIONindex e3e18070..7e310bae 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.9.8+0.9.9diff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.mdindex 12930770..05ac3c4f 100644--- a/google-ads/ads/SKILL.md+++ b/google-ads/ads/SKILL.md@@ -28,35 +28,6 @@ triggers:Before fulfilling any user request, silently perform these checks. Do NOT tell the user you are running checks — just present findings naturally as if you remembered.-### Step 0: Verify API key — BLOCKING, MUST RUN FIRST--**CRITICAL: You MUST execute this step before doing ANYTHING else. Do NOT skip this. Do NOT check environment variables — you MUST read the file.**--1. Use the Read tool to read `~/.claude/settings.json`.-2. Parse the JSON and check if `env.ADSAGENT_API_KEY` exists and is a non-empty string.--**If the key exists and is non-empty:** proceed to Step 1 silently.--**If the key is missing, the `env` object doesn't exist, or the file doesn't exist:** you MUST stop and do the following — do NOT proceed to any other step, do NOT fulfill the user's request:--1. Show this message:- > To use Google Ads features, you need an AdsAgent API key.- > Sign up at [adsagent.org](https://adsagent.org) to get your key, then paste it here.--2. Use AskUserQuestion to ask: "Please paste your AdsAgent API key:"--3. Once the user provides the key, read `~/.claude/settings.json` again (use `{}` if it doesn't exist), merge the key into the JSON preserving all existing fields:- ```json- {- "env": {- "ADSAGENT_API_KEY": "<the key the user provided>"- }- }- ```- Write the updated JSON back to `~/.claude/settings.json` using the Write tool.--4. Tell the user the key has been saved, then proceed to Step 1.-### Step 1: Check for pending change reviewsRead `{data_dir}/change-log.json`. Find entries where:diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.mdindex b7af3212..7501aa77 100644--- a/google-ads/shared/preamble.md+++ b/google-ads/shared/preamble.md@@ -1,6 +1,6 @@# Google Ads Shared Preamble-Every google-ads skill reads this before doing anything else. It handles MCP detection, authentication, and upgrade checks in one place — so individual skills don't repeat this logic.+Every google-ads skill reads this before doing anything else. It handles updates, API key verification, MCP detection, config resolution, and onboarding in one place — so individual skills don't repeat this logic.## Step 0: Check for toprank updates@@ -10,11 +10,45 @@ _UPD_BIN=$(ls ~/.claude/plugins/cache/nowork-studio/toprank/*/bin/toprank-update[ -n "$_UPD" ] && echo "$_UPD" || true```-If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade. After the upgrade completes, re-read the updated preamble from the new plugin cache and restart from Step 1 (the upgrade check itself doesn't need to run again).-If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue to Step 1.-## Step 1: Resolve config+If neither: continue to Step 1 silently.++## Step 1: Verify API key — BLOCKING++The MCP server authenticates via the `ADSAGENT_API_KEY` environment variable, which Claude Code injects from `~/.claude/settings.json`. Without it, no MCP tools will work — so this check must happen before anything else.++**You MUST execute this step. Do NOT skip it. Do NOT check environment variables — you MUST read the file.**++1. Use the Read tool to read `~/.claude/settings.json`.+2. Parse the JSON and check if `env.ADSAGENT_API_KEY` exists and is a non-empty string.++**If the key exists and is non-empty:** proceed to Step 2 silently.++**If the key is missing, the `env` object doesn't exist, or the file doesn't exist:** you MUST stop and do the following — do NOT proceed to any other step, do NOT fulfill the user's request:++1. Output this message and STOP (do not call any tools, do not continue — just output this text and end your turn):++ > To use Google Ads features, you need an AdsAgent API key.+ > Sign up at [adsagent.org](https://adsagent.org) to get your key, then paste it below.++2. When the user replies with their key, read `~/.claude/settings.json` again (use `{}` if it doesn't exist). Deep-merge the key into the existing JSON — preserve all existing top-level fields and all existing keys within the `env` object. Only add/overwrite `ADSAGENT_API_KEY`:+ ```json+ {+ "...existing fields preserved...",+ "env": {+ "...existing env vars preserved...",+ "ADSAGENT_API_KEY": "<the key the user provided>"+ }+ }+ ```+ Write the updated JSON back to `~/.claude/settings.json` using the Write tool.++3. Tell the user the key has been saved. Note: the MCP server won't pick up the new key until Claude Code restarts. If MCP tools fail in Step 3, advise the user to restart Claude Code and re-run their command. Then proceed to Step 2.++## Step 2: Resolve configRead config from three locations and merge fields (first non-null, non-empty-string value wins per field):@@ -22,9 +56,9 @@ Read config from three locations and merge fields (first non-null, non-empty-str2. **Claude project-level** — `~/.claude/projects/{project-path}/adsagent.json` (where `{project-path}` is the CWD-based path Claude Code uses for project memory, e.g. `-Users-alice-repos-petshop`)3. **Global fallback** — `~/.adsagent/config.json`-Each file uses the same schema: `{ "accountId": "...", "apiKey": "..." }`. Fields merge up the chain — a project file with only `accountId` inherits `apiKey` from global.+Each file uses the same schema: `{ "accountId": "..." }`. Fields merge up the chain — a project file with only `accountId` inherits from global.-If both `apiKey` and `accountId` are resolved after merging, skip to Step 4.+The API key is stored separately in `~/.claude/settings.json` under `env.ADSAGENT_API_KEY` (not in config files — the MCP server reads it from the environment).### Resolved data directory@@ -33,49 +67,37 @@ Data files (business-context, personas, change-log, account-baseline) are stored- If `.adsagent.json` exists in the current working directory → `{data_dir}` = `.adsagent/` (relative to project root)- Otherwise → `{data_dir}` = `~/.adsagent/` (the Claude project-level config alone doesn't trigger project-local data — only a `.adsagent.json` in the repo does)-Create `{data_dir}` if it doesn't exist. Throughout this document and all skills, `{data_dir}` refers to this resolved directory.+Create `{data_dir}` if it doesn't exist. Ensure `~/.adsagent/` also exists (needed for the global config file regardless of `{data_dir}`). Throughout this document and all skills, `{data_dir}` refers to this resolved directory.++**Important:** If using project-local storage (`.adsagent/`), ensure `.adsagent.json` and `.adsagent/` are in the project's `.gitignore` — they contain business-sensitive data that should not be committed.-**Important:** If using project-local storage (`.adsagent/`), ensure `.adsagent.json` and `.adsagent/` are in the project's `.gitignore` — they contain API keys and business-sensitive data that should not be committed.+Continue to Step 3 (MCP detection always runs).-## Step 2: MCP Server Detection+## Step 3: MCP Server Detection-Only runs if Step 1 found missing config.+Always verify that a Google Ads MCP server is available — the MCP server could be down or misconfigured even with a valid API key and saved accountId.-1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`+1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts` — save the result for reuse in Step 42. If not found, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*` in the available tools3. If neither exists, guide the user:-> No Google Ads MCP server detected. The easiest setup:+> No Google Ads MCP server detected.>-> 1. Get a free API key at [adsagent.org](https://www.adsagent.org)-> 2. Set the environment variable: `export ADSAGENT_API_KEY=your_key`-> 3. Restart Claude Code (the toprank plugin's .mcp.json will auto-configure the server)+> Your API key is configured, but the MCP server may not have started. Try restarting Claude Code — the toprank plugin's .mcp.json will auto-configure the server using your key.>-> Or configure any Google Ads MCP server manually in your MCP settings.+> If the problem persists, check your MCP server settings or configure a Google Ads MCP server manually.Stop here until the MCP server is available.-## Step 3: Onboarding (only if config is incomplete)--Read the merged config from Step 1. Ensure `~/.adsagent/` exists (needed for the global config file regardless of `{data_dir}`).--### Token+If `accountId` was already resolved in Step 2, skip to Step 5. Otherwise, continue to Step 4.-If `apiKey` is missing:+## Step 4: Onboarding (only if accountId is missing)-> To use AdsAgent, you need a free token. You can get one from [adsagent.org](https://www.adsagent.org).-> Once you have it, paste it here and I'll save it for you.+Use the `listConnectedAccounts` result from Step 3 (do not call it again):-Save the token to `~/.adsagent/config.json` (global — API keys are shared across projects).--### Account selection--If `accountId` is missing:--1. Run `listConnectedAccounts`-2. **One account** → save automatically to the highest-priority config file that already exists (project > claude-project > global; if none exist yet, save to `~/.adsagent/config.json`), tell the user which was selected-3. **Multiple accounts** → show numbered list, ask user to pick, save choice to the same location-4. **Zero accounts** → direct to [adsagent.org](https://www.adsagent.org) to connect one+1. **One account** → save automatically to the highest-priority config file that already exists (project > claude-project > global; if none exist yet, save to `~/.adsagent/config.json`), tell the user which was selected+2. **Multiple accounts** → show numbered list, ask user to pick, save choice to the same location+3. **Zero accounts** → direct to [adsagent.org](https://www.adsagent.org) to connect one### Switching accounts@@ -86,19 +108,17 @@ If the user explicitly asks to switch accounts, run `listConnectedAccounts`, let- **Project** → write `accountId` to `.adsagent.json` in the current working directory (create the file if needed)- **Global** → write `accountId` to `~/.adsagent/config.json`-## Step 4: Calling tools+## Step 5: Calling toolsUse whichever MCP server prefix was detected:- **AdsAgent MCP (default):** `mcp__adsagent__<toolName>` with `accountId` parameter- **Google's official MCP:** `mcp__google_ads_mcp__<toolName>`-Always pass `accountId` from the resolved config (Step 1) to every tool call (except `listConnectedAccounts`).+Always pass `accountId` from the resolved config (Step 2) to every tool call (except `listConnectedAccounts`).### Prefer GAQL for multi-campaign readsWhen a workflow needs data from 2+ campaigns, use `runGaqlQuery` with bulk queries instead of per-campaign helper calls. See `../shared/gaql-cookbook.md` for ready-to-use query patterns. This typically reduces API calls from `N × data_types` to just the number of data types (e.g., 7 queries instead of 30+). Fall back to per-campaign helpers if GAQL errors or you need >50 rows for a single campaign.-## Step 5: Proceed-Config is loaded. Hand control back to the invoking skill.