Open-source SEO, GEO, and marketing skills for AI agents.
feat: project-level config resolution for Google Ads skills (#27)
Tong Chendbd05b4b8c23
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 637dd318..a66428b7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.9.2] — 2026-04-06++### Changed+- **Config resolution** — replaced single global config (`~/.adsagent/config.json`) with 3-tier chain: project-level (`.adsagent.json`), Claude project-level (`~/.claude/projects/{path}/adsagent.json`), and global fallback. Fields merge up the chain so a project file with only `accountId` inherits `apiKey` from global.+- **Project-scoped data storage** — when a project-level config exists, data files (business-context, personas, change-log, account-baseline) are stored in `.adsagent/` relative to the project root instead of globally+- **Account switching** — now asks whether to save the selection for the current project or globally+- **Security** — preamble instructs LLM to add `.adsagent.json` and `.adsagent/` to `.gitignore` when using project-local storage++---+## [0.9.1] — 2026-04-04### Addeddiff --git a/VERSION b/VERSIONindex f374f666..2003b639 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.9.1+0.9.2diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.mdindex 0461885f..1a08e0bb 100644--- a/google-ads/ads-audit/SKILL.md+++ b/google-ads/ads-audit/SKILL.md@@ -13,7 +13,7 @@ Read and follow `../shared/preamble.md` — it handles MCP detection, token, andThis is the starting point for any Google Ads account. It does two things:1. **Audits the account** — surfaces what's working, what's wasting money, and what to fix first-2. **Builds business context** — gathers and saves business information to `~/.adsagent/business-context.json` so every other ads skill (copy, landing pages, competitive analysis) can use it without re-asking+2. **Builds business context** — gathers and saves business information to `{data_dir}/business-context.json` so every other ads skill (copy, landing pages, competitive analysis) can use it without re-askingRun this before anything else. If another ads skill finds `business-context.json` missing, it should point the user here.@@ -322,7 +322,7 @@ Use this full template for the persisted JSON file. In the **report output**, pe### Persist Personas-Save to `~/.adsagent/personas/{accountId}.json`:+Save to `{data_dir}/personas/{accountId}.json`:```json{@@ -346,7 +346,7 @@ These personas feed directly into `/ads-copy` for headline generation and `/ads`## Phase 3: Build Business Context-**Skip this phase for scoped audits if `~/.adsagent/business-context.json` already exists and has a recent `audit_date`.** A scoped audit (e.g., "focus on grooming") should deliver findings fast, not re-interview the user. Only run Phase 3 on the first full-account audit or if business-context.json is missing/stale (>90 days old).+**Skip this phase for scoped audits if `{data_dir}/business-context.json` already exists and has a recent `audit_date`.** A scoped audit (e.g., "focus on grooming") should deliver findings fast, not re-interview the user. Only run Phase 3 on the first full-account audit or if business-context.json is missing/stale (>90 days old).Pull as much as possible from the data you already have — only ask the user for what you can't infer.@@ -431,7 +431,7 @@ Present what you inferred from **both** account data and the website crawl, then### Save the context-Write the complete business context to `~/.adsagent/business-context.json`:+Write the complete business context to `{data_dir}/business-context.json`:```json{diff --git a/google-ads/ads-copy/SKILL.md b/google-ads/ads-copy/SKILL.mdindex f4bdf75d..f423d1dd 100644--- a/google-ads/ads-copy/SKILL.md+++ b/google-ads/ads-copy/SKILL.md@@ -24,11 +24,11 @@ These contain the specific formulas, character counts, and patterns that separat## Business Context — Read First, Ask Once-Every ad copy decision depends on understanding the business. This skill stores business context in `~/.adsagent/business-context.json` so it only needs to be gathered once.+Every ad copy decision depends on understanding the business. This skill stores business context in `{data_dir}/business-context.json` so it only needs to be gathered once.### On every invocation:-1. **Read `~/.adsagent/business-context.json`**. If it exists and has content, use it — skip the intake interview.+1. **Read `{data_dir}/business-context.json`**. If it exists and has content, use it — skip the intake interview.2. **If missing or empty**, run the intake interview below, then save the result.3. **If the user volunteers new info** (new service, changed positioning, seasonal update), merge it into the existing file.@@ -104,7 +104,7 @@ Present what you found and ask the user to confirm/correct/fill gaps. This is fa## Persona-Informed Copy-Cross-reference `~/.adsagent/personas/{accountId}.json` (created by `/ads-audit`) and `~/.adsagent/business-context.json` to ground every piece of copy in real customer data.+Cross-reference `{data_dir}/personas/{accountId}.json` (created by `/ads-audit`) and `{data_dir}/business-context.json` to ground every piece of copy in real customer data.### How personas shape copy decisions@@ -156,7 +156,7 @@ Google's ad strength score optimizes for Google's internal ad diversity goals, n## Competitive Differentiation-Read `~/.adsagent/business-context.json` `competitors` and `differentiators` fields. If empty, infer competitors from auction overlap (high impression share keywords where rank-lost IS is elevated suggest active competitors).+Read `{data_dir}/business-context.json` `competitors` and `differentiators` fields. If empty, infer competitors from auction overlap (high impression share keywords where rank-lost IS is elevated suggest active competitors).### Rules for competitive copy@@ -292,7 +292,7 @@ Show 2-3 variants, each with a distinct messaging angle. Name the angle so it's```VARIANT A: "[Angle Name — e.g., Trust & Experience]"- Target persona: [persona name from ~/.adsagent/personas/]+ Target persona: [persona name from {data_dir}/personas/]H1 [Pin 1]: [Service] in [Location] (XX chars)H2: [Value prop headline] (XX chars)H3: [Trust headline] (XX chars)@@ -366,7 +366,7 @@ After deciding a winner: pause the loser with `mcp__adsagent__pauseAd`, keep the## Rules-1. **Business context first.** Read `~/.adsagent/business-context.json` before doing anything. If it doesn't exist, build it.+1. **Business context first.** Read `{data_dir}/business-context.json` before doing anything. If it doesn't exist, build it.2. **Research before writing.** Always pull current performance data. Don't write copy in a vacuum.3. **Character limits are hard.** Count every headline (<=30) and description (<=90). No exceptions. When in doubt, count again.4. **Never deploy without confirmation.** Show the exact copy, get a yes, then create/update.diff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.mdindex a00c26cb..3a61215e 100644--- a/google-ads/ads/SKILL.md+++ b/google-ads/ads/SKILL.md@@ -30,7 +30,7 @@ Before fulfilling any user request, silently perform these checks. Do NOT tell t### Step 1: Check for pending change reviews-Read `~/.adsagent/change-log.json`. Find entries where:+Read `{data_dir}/change-log.json`. Find entries where:- `reviewed` is `false`- `reviewAfter` date has passed (is before today)@@ -70,7 +70,7 @@ If there are pending reviews:### Step 2: Check account baseline for anomalies-Read `~/.adsagent/account-baseline.json`. If it exists AND was last updated more than 24 hours ago:+Read `{data_dir}/account-baseline.json`. If it exists AND was last updated more than 24 hours ago:1. Get current campaign metrics — reuse the `listCampaigns` result from Step 1 if available, otherwise call `listCampaigns` now.2. Compare each campaign's 7-day metrics to the `rolling30d` baseline.@@ -155,15 +155,15 @@ All write tools return a `changeId` on success. Use this with `undoChange` to re3. **Show numbers clearly.** Format cost as dollars, show CTR as percentages, include date ranges.4. **Recommend before acting.** When you spot waste (high-spend zero-conversion keywords, irrelevant search terms), recommend the action and wait for approval.5. **Guardrails are server-side.** Bid changes >25% and budget changes >50% will be rejected by the server. Don't try to circumvent this.-6. **After every write, log the change.** Follow the Change Tracking workflow below — record the change to `~/.adsagent/change-log.json` with before-metrics and a review window. Tell the user the change is logged and when follow-up will happen. They can also undo within 7 days using `getChanges` and `undoChange`.+6. **After every write, log the change.** Follow the Change Tracking workflow below — record the change to `{data_dir}/change-log.json` with before-metrics and a review window. Tell the user the change is logged and when follow-up will happen. They can also undo within 7 days using `getChanges` and `undoChange`.## Change Tracking-After every successful write operation, log the change to `~/.adsagent/change-log.json` for follow-up tracking.+After every successful write operation, log the change to `{data_dir}/change-log.json` for follow-up tracking.### After every write-1. **Record the change.** Append an entry to the `changes` array in `~/.adsagent/change-log.json` (create the file if it doesn't exist):+1. **Record the change.** Append an entry to the `changes` array in `{data_dir}/change-log.json` (create the file if it doesn't exist):```json{@@ -219,7 +219,7 @@ After every successful write operation, log the change to `~/.adsagent/change-lo## Account Baseline-Maintain `~/.adsagent/account-baseline.json` to enable anomaly detection across sessions.+Maintain `{data_dir}/account-baseline.json` to enable anomaly detection across sessions.### When to update@@ -648,7 +648,7 @@ If you find CTR issues in 2+ ad groups (CTR below industry benchmark or declinin### Missing Business Context-If `~/.adsagent/business-context.json` doesn't exist or `audit_date` is more than 90 days old:+If `{data_dir}/business-context.json` doesn't exist or `audit_date` is more than 90 days old:> "I don't have business context for this account (or it's stale). Run `/ads-audit` first — it builds your business profile, which improves all recommendations. I can still work without it, but recommendations will be more generic."diff --git a/google-ads/ads/evals/evals.json b/google-ads/ads/evals/evals.jsonindex 3dc1745e..94849ffb 100644--- a/google-ads/ads/evals/evals.json+++ b/google-ads/ads/evals/evals.json@@ -4,11 +4,11 @@{"id": 1,"prompt": "Can you help me manage my Google Ads?",- "expected_output": "The skill checks for the AdsAgent MCP server connection, then checks for a token in ~/.adsagent/config.json, then checks for an accountId. It should not attempt to pull campaign data before completing the onboarding flow.",+ "expected_output": "The skill checks for the AdsAgent MCP server connection, then resolves config from the 3-tier chain (project .adsagent.json > Claude project adsagent.json > global ~/.adsagent/config.json), then checks for an accountId. It should not attempt to pull campaign data before completing the onboarding flow.","files": [],"expectations": ["The skill attempts to verify MCP server connectivity before pulling data",- "The skill checks for apiKey in ~/.adsagent/config.json",+ "The skill resolves apiKey from the 3-tier config chain (project > claude-project > global)","The skill checks for accountId before making campaign API calls","If any setup step is missing, the skill guides the user through resolution before proceeding"]diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.mdindex 887523db..6bf54ffd 100644--- a/google-ads/shared/preamble.md+++ b/google-ads/shared/preamble.md@@ -14,9 +14,28 @@ If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the iIf the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.-## Step 1: Check config cache+## Step 1: Resolve config-Read `~/.adsagent/config.json`. If both `apiKey` and `accountId` are present, skip to Step 4. The MCP server is already configured and the account is selected — no further setup needed.+Read config from three locations and merge fields (first non-null, non-empty-string value wins per field):++1. **Project-level** — `.adsagent.json` in the repository root (Claude Code's working directory)+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.++If both `apiKey` and `accountId` are resolved after merging, skip to Step 4.++### Resolved data directory++Data files (business-context, personas, change-log, account-baseline) are stored project-locally when a project-level config exists:++- 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.++**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.## Step 2: MCP Server Detection@@ -38,7 +57,7 @@ Stop here until the MCP server is available.## Step 3: Onboarding (only if config is incomplete)-Read `~/.adsagent/config.json` (create `~/.adsagent/` if it doesn't exist).+Read the merged config from Step 1. Ensure `~/.adsagent/` exists (needed for the global config file regardless of `{data_dir}`).### Token@@ -47,20 +66,25 @@ If `apiKey` 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.-Save the token to `~/.adsagent/config.json` when provided.+Save the token to `~/.adsagent/config.json` (global — API keys are shared across projects).### Account selectionIf `accountId` is missing:1. Run `listConnectedAccounts`-2. **One account** → save automatically, tell the user which was selected-3. **Multiple accounts** → show numbered list, ask user to pick, save choice+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 location4. **Zero accounts** → direct to [adsagent.org](https://www.adsagent.org) to connect one### Switching accounts-If the user explicitly asks to switch accounts, run `listConnectedAccounts`, let them pick, and update `accountId` in `~/.adsagent/config.json`.+If the user explicitly asks to switch accounts, run `listConnectedAccounts`, let them pick, then ask:++> "Save this account for this project only, or globally?"++- **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@@ -69,7 +93,7 @@ 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 `~/.adsagent/config.json` to every tool call (except `listConnectedAccounts`).+Always pass `accountId` from the resolved config (Step 1) to every tool call (except `listConnectedAccounts`).### Prefer GAQL for multi-campaign reads