Skip to content

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.md
index 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
### Added
diff --git a/VERSION b/VERSION
index f374f666..2003b639 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.9.1
+0.9.2
diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.md
index 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, and
This 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-asking
Run 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.md
index 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.md
index 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 re
3. **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.json
index 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.md
index 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 i
If 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 selection
If `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 location
4. **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