Skip to content

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.json
index 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.json
index 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.md
index 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
### Added
diff --git a/VERSION b/VERSION
index e3e18070..7e310bae 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.9.8
+0.9.9
diff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.md
index 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 reviews
Read `{data_dir}/change-log.json`. Find entries where:
diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.md
index 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 config
Read 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-str
2. **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 4
2. If not found, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*` in the available tools
3. 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 tools
Use 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 reads
When 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.