Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

refactor: restructure skills into category folders with shared preambles (#26)

Tong Chen34fabdc41396
diff --git a/.agents/skills/toprank-content-writer/SKILL.md b/.agents/skills/toprank-content-writer/SKILL.md
deleted file mode 120000
index ebcdb779..00000000
--- a/.agents/skills/toprank-content-writer/SKILL.md
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/content-writer/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-content-writer/agents/openai.yaml b/.agents/skills/toprank-content-writer/agents/openai.yaml
deleted file mode 100644
index 0ebf11fb..00000000
--- a/.agents/skills/toprank-content-writer/agents/openai.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-interface:
- display_name: "toprank-content-writer"
- short_description: "Write SEO-optimized blog posts, landing pages, and content improvements following Google's E-E-A-T and Helpful Content"
- default_prompt: "Use toprank-content-writer for this task."
-policy:
- allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-content-writer/references b/.agents/skills/toprank-content-writer/references
deleted file mode 120000
index 56eeab48..00000000
--- a/.agents/skills/toprank-content-writer/references
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/content-writer/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-keyword-research/SKILL.md b/.agents/skills/toprank-keyword-research/SKILL.md
deleted file mode 120000
index 66411967..00000000
--- a/.agents/skills/toprank-keyword-research/SKILL.md
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/keyword-research/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-keyword-research/agents/openai.yaml b/.agents/skills/toprank-keyword-research/agents/openai.yaml
deleted file mode 100644
index 752ad956..00000000
--- a/.agents/skills/toprank-keyword-research/agents/openai.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-interface:
- display_name: "toprank-keyword-research"
- short_description: "Discover, analyze, and prioritize keywords for SEO and GEO content strategies. Identifies high-value opportunities bas"
- default_prompt: "Use toprank-keyword-research for this task."
-policy:
- allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-keyword-research/references b/.agents/skills/toprank-keyword-research/references
deleted file mode 120000
index 491b0fc9..00000000
--- a/.agents/skills/toprank-keyword-research/references
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/keyword-research/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-meta-tags-optimizer/SKILL.md b/.agents/skills/toprank-meta-tags-optimizer/SKILL.md
deleted file mode 120000
index 72dc9179..00000000
--- a/.agents/skills/toprank-meta-tags-optimizer/SKILL.md
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/meta-tags-optimizer/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-meta-tags-optimizer/agents/openai.yaml b/.agents/skills/toprank-meta-tags-optimizer/agents/openai.yaml
deleted file mode 100644
index d9c5badf..00000000
--- a/.agents/skills/toprank-meta-tags-optimizer/agents/openai.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-interface:
- display_name: "toprank-meta-tags-optimizer"
- short_description: "Optimize title tags, meta descriptions, Open Graph, and Twitter cards for maximum click-through rate. Generates multip"
- default_prompt: "Use toprank-meta-tags-optimizer for this task."
-policy:
- allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-meta-tags-optimizer/references b/.agents/skills/toprank-meta-tags-optimizer/references
deleted file mode 120000
index 30219818..00000000
--- a/.agents/skills/toprank-meta-tags-optimizer/references
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/meta-tags-optimizer/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-schema-markup-generator/SKILL.md b/.agents/skills/toprank-schema-markup-generator/SKILL.md
deleted file mode 120000
index 25e24dd4..00000000
--- a/.agents/skills/toprank-schema-markup-generator/SKILL.md
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/schema-markup-generator/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-schema-markup-generator/agents/openai.yaml b/.agents/skills/toprank-schema-markup-generator/agents/openai.yaml
deleted file mode 100644
index 7d1e49c2..00000000
--- a/.agents/skills/toprank-schema-markup-generator/agents/openai.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-interface:
- display_name: "toprank-schema-markup-generator"
- short_description: "Generate JSON-LD structured data markup for rich results in Google Search. Supports FAQ, HowTo, Article, Product, Loca"
- default_prompt: "Use toprank-schema-markup-generator for this task."
-policy:
- allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-schema-markup-generator/references b/.agents/skills/toprank-schema-markup-generator/references
deleted file mode 120000
index f1715344..00000000
--- a/.agents/skills/toprank-schema-markup-generator/references
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/schema-markup-generator/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-seo-analysis/SKILL.md b/.agents/skills/toprank-seo-analysis/SKILL.md
deleted file mode 120000
index 5b68fff8..00000000
--- a/.agents/skills/toprank-seo-analysis/SKILL.md
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/seo-analysis/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-seo-analysis/agents/openai.yaml b/.agents/skills/toprank-seo-analysis/agents/openai.yaml
deleted file mode 100644
index ab71d020..00000000
--- a/.agents/skills/toprank-seo-analysis/agents/openai.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-interface:
- display_name: "toprank-seo-analysis"
- short_description: "Full SEO audit: Google Search Console data + URL Inspection API + technical crawl + keyword research + metadata audit "
- default_prompt: "Use toprank-seo-analysis for this task."
-policy:
- allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-seo-analysis/references b/.agents/skills/toprank-seo-analysis/references
deleted file mode 120000
index 525a6eac..00000000
--- a/.agents/skills/toprank-seo-analysis/references
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/seo-analysis/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-seo-analysis/scripts b/.agents/skills/toprank-seo-analysis/scripts
deleted file mode 120000
index 561bba82..00000000
--- a/.agents/skills/toprank-seo-analysis/scripts
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/seo-analysis/scripts
\ No newline at end of file
diff --git a/.agents/skills/toprank-toprank-upgrade/SKILL.md b/.agents/skills/toprank-toprank-upgrade/SKILL.md
deleted file mode 120000
index 759d9515..00000000
--- a/.agents/skills/toprank-toprank-upgrade/SKILL.md
+++ /dev/null
@@ -1 +0,0 @@
-/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/toprank-upgrade/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-toprank-upgrade/agents/openai.yaml b/.agents/skills/toprank-toprank-upgrade/agents/openai.yaml
deleted file mode 100644
index f2b73b2b..00000000
--- a/.agents/skills/toprank-toprank-upgrade/agents/openai.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-interface:
- display_name: "toprank-toprank-upgrade"
- short_description: "Upgrade toprank skills to the latest version. Detects global vs vendored install, runs the upgrade, and shows what's n"
- default_prompt: "Use toprank-toprank-upgrade for this task."
-policy:
- allow_implicit_invocation: true
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 90d42999..6faf77c8 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -5,5 +5,16 @@
"author": {
"name": "nowork-studio"
},
- "skills": "./skills/"
+ "skills": [
+ "./google-ads/ads",
+ "./google-ads/ads-audit",
+ "./google-ads/ads-copy",
+ "./seo/seo-analysis",
+ "./seo/content-writer",
+ "./seo/keyword-research",
+ "./seo/meta-tags-optimizer",
+ "./seo/schema-markup-generator",
+ "./seo/setup-cms",
+ "./toprank-upgrade-skill"
+ ]
}
diff --git a/CONNECTORS.md b/CONNECTORS.md
new file mode 100644
index 00000000..fb44de6a
--- /dev/null
+++ b/CONNECTORS.md
@@ -0,0 +1,48 @@
+# Connectors
+
+Toprank skills reference external tools using the `~~category` placeholder pattern. This makes skills tool-agnostic — they work with any MCP server that provides the required capability.
+
+## Connected Tools
+
+| Category | Placeholder | Default Server | Alternatives |
+|----------|-------------|---------------|--------------|
+| Google Ads | `~~google-ads` | [AdsAgent MCP](https://www.adsagent.org) (`mcp__adsagent__*`) | Google Ads MCP (`mcp__google_ads_mcp__*`) |
+| Search Console | `~~search-console` | gcloud CLI + Search Console API | Any GSC-compatible MCP server |
+| CMS | `~~cms` | Direct API (WordPress REST, Strapi, Contentful, Ghost) | Any CMS MCP server |
+
+## How Connectors Work
+
+Skills use conditional blocks based on available tools:
+
+```markdown
+If ~~google-ads is connected:
+- Pull campaign performance data
+- Manage keywords and bids
+
+If ~~search-console is connected:
+- Fetch GSC performance data
+- Run URL Inspection API checks
+```
+
+If a connector is not available, the skill gracefully degrades — for example, `seo-analysis` can still run a technical crawl without GSC data.
+
+## Setup
+
+### Google Ads (used by: ads, ads-audit, ads-copy)
+
+See `google-ads/shared/preamble.md`. Requires:
+1. AdsAgent API key from [adsagent.org](https://www.adsagent.org)
+2. Set `ADSAGENT_API_KEY` environment variable
+3. The `.mcp.json` in this plugin auto-configures the MCP server
+
+### Search Console (used by: seo-analysis)
+
+See `seo/shared/preamble.md`. Requires:
+1. Google Cloud SDK (`gcloud`) installed
+2. Search Console API enabled on your GCP project
+3. OAuth login with the Google account that owns your GSC properties
+
+### CMS (used by: seo-analysis, setup-cms)
+
+Run `/setup-cms` to configure. Supports WordPress, Strapi, Contentful, and Ghost.
+Credentials are saved to `.env.local` in the project root.
diff --git a/README.md b/README.md
index 4ea2415b..5bc94c5c 100644
--- a/README.md
+++ b/README.md
@@ -129,20 +129,20 @@ Add the marketplace and enable the plugin in `~/.claude/settings.json`:
| Skill | What it does |
|-------|-------------|
-| [`ads-audit`](skills/ads-audit/) | Account audit + business context setup. Run this first. Scores 7 health dimensions, identifies wasted spend, builds business profile. |
-| [`ads`](skills/ads/) | Campaign management. Read performance, optimize keywords, adjust bids/budgets, add negatives, create campaigns. |
-| [`ads-copy`](skills/ads-copy/) | RSA copy generator + A/B testing. Data-driven headlines and descriptions with character counts and pin positions. |
+| [`ads-audit`](google-ads/ads-audit/) | Account audit + business context setup. Run this first. Scores 7 health dimensions, identifies wasted spend, builds business profile. |
+| [`ads`](google-ads/ads/) | Campaign management. Read performance, optimize keywords, adjust bids/budgets, add negatives, create campaigns. |
+| [`ads-copy`](google-ads/ads-copy/) | RSA copy generator + A/B testing. Data-driven headlines and descriptions with character counts and pin positions. |
### SEO
| Skill | What it does |
|-------|-------------|
-| [`seo-analysis`](skills/seo-analysis/) | Full SEO audit with GSC data. Quick wins, traffic drops, technical issues, 30-day action plan. |
-| [`content-writer`](skills/content-writer/) | SEO content creation following E-E-A-T guidelines. Blog posts, landing pages, content improvements. |
-| [`keyword-research`](skills/keyword-research/) | Keyword discovery, intent classification, topic clusters, prioritized content calendar. |
-| [`meta-tags-optimizer`](skills/meta-tags-optimizer/) | Title tags, meta descriptions, OG/Twitter cards with A/B variations and CTR estimates. |
-| [`schema-markup-generator`](skills/schema-markup-generator/) | JSON-LD structured data for rich results. FAQ, HowTo, Article, Product, LocalBusiness. |
-| [`setup-cms`](skills/setup-cms/) | Connect WordPress, Strapi, Contentful, or Ghost for automated SEO field audits. |
+| [`seo-analysis`](seo/seo-analysis/) | Full SEO audit with GSC data. Quick wins, traffic drops, technical issues, 30-day action plan. |
+| [`content-writer`](seo/content-writer/) | SEO content creation following E-E-A-T guidelines. Blog posts, landing pages, content improvements. |
+| [`keyword-research`](seo/keyword-research/) | Keyword discovery, intent classification, topic clusters, prioritized content calendar. |
+| [`meta-tags-optimizer`](seo/meta-tags-optimizer/) | Title tags, meta descriptions, OG/Twitter cards with A/B variations and CTR estimates. |
+| [`schema-markup-generator`](seo/schema-markup-generator/) | JSON-LD structured data for rich results. FAQ, HowTo, Article, Product, LocalBusiness. |
+| [`setup-cms`](seo/setup-cms/) | Connect WordPress, Strapi, Contentful, or Ghost for automated SEO field audits. |
All skills are namespaced: `/toprank:ads`, `/toprank:seo-analysis`, etc.
@@ -155,27 +155,21 @@ Toprank is a Claude Code plugin. Each skill is a `SKILL.md` file with supporting
```
toprank/
├── .claude-plugin/
-│ ├── plugin.json <- plugin metadata
+│ ├── plugin.json <- plugin metadata (explicit skill paths)
│ └── marketplace.json <- registry entry
├── .mcp.json <- AdsAgent MCP server (auto-configured)
-├── skills/
-│ ├── seo-analysis/
-│ │ ├── SKILL.md <- SEO audit workflow
-│ │ ├── scripts/ <- Python scripts for GSC API
-│ │ ├── references/ <- domain expertise docs
-│ │ └── evals/ <- quality tests
-│ ├── ads/
-│ │ ├── SKILL.md <- Google Ads management
-│ │ ├── references/ <- benchmarks, decision trees
-│ │ └── evals/ <- quality tests
-│ ├── ads-audit/
-│ ├── ads-copy/
-│ ├── keyword-research/
-│ ├── meta-tags-optimizer/
-│ ├── schema-markup-generator/
-│ ├── content-writer/
-│ ├── setup-cms/
-│ └── toprank-upgrade/
+├── google-ads/
+│ ├── ads/ <- campaign management
+│ ├── ads-audit/ <- account audit + business context
+│ └── ads-copy/ <- RSA copy generator + A/B testing
+├── seo/
+│ ├── seo-analysis/ <- full SEO audit with GSC data
+│ ├── content-writer/ <- E-E-A-T content creation
+│ ├── keyword-research/ <- keyword discovery + topic clusters
+│ ├── meta-tags-optimizer/ <- title tags, meta descriptions, OG
+│ ├── schema-markup-generator/ <- JSON-LD structured data
+│ └── setup-cms/ <- CMS connector
+├── toprank-upgrade-skill/ <- self-updater
├── test/ <- unit + LLM-judge eval tests
└── VERSION
```
diff --git a/skills/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.md
similarity index 94%
rename from skills/ads-audit/SKILL.md
rename to google-ads/ads-audit/SKILL.md
index c975060f..fd0664be 100644
--- a/skills/ads-audit/SKILL.md
+++ b/google-ads/ads-audit/SKILL.md
@@ -1,25 +1,12 @@
---
name: ads-audit
description: Google Ads account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other ads skills reuse. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to AdsAgent and hasn't run an audit before. Also trigger proactively when other ads skills detect that business-context.json is missing.
+argument-hint: "<account name or 'audit my ads'>"
---
-## MCP Server Detection
-
-Before calling any Google Ads tool, detect which MCP server is available:
-
-1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`
-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:
->
-> 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)
->
-> Or configure any Google Ads MCP server manually in your MCP settings.
+## Setup
-Use whichever MCP server's tool prefix is available for all subsequent calls in this session.
+Read and follow `../shared/preamble.md` — it handles MCP detection, token, and account selection. If config is already cached, this is instant.
# Google Ads Audit + Business Context Setup
@@ -30,24 +17,6 @@ This is the starting point for any Google Ads account. It does two things:
Run this before anything else. If another ads skill finds `business-context.json` missing, it should point the user here.
-## Setup
-
-Before anything else, verify the user has the AdsAgent MCP server connected and a token configured. Follow these steps in order — stop at the first issue and resolve it before continuing.
-
-### Step 1: Check for the AdsAgent MCP server
-
-Follow the **MCP Server Detection** section above. If no MCP server is found, guide the user through setup before proceeding. Wait for the user to complete setup before continuing.
-
-### Step 2: Check for token and account
-
-Read `~/.adsagent/config.json` for `apiKey` (the token) and `accountId`.
-
-- If `apiKey` is missing, ask the user for their token and save it as `apiKey` in `~/.adsagent/config.json`.
-- If `accountId` is missing, run `mcp__adsagent__listConnectedAccounts`:
- - **One account** → save it automatically
- - **Multiple accounts** → show list, ask user to pick
- - **Zero accounts** → direct user to [adsagent.org](https://www.adsagent.org) to connect a Google Ads account
-
## Reference Documents
Read these reference documents during analysis for expert-level context:
diff --git a/skills/ads-audit/evals/evals.json b/google-ads/ads-audit/evals/evals.json
similarity index 100%
rename from skills/ads-audit/evals/evals.json
rename to google-ads/ads-audit/evals/evals.json
diff --git a/skills/ads-audit/references/account-health-scoring.md b/google-ads/ads-audit/references/account-health-scoring.md
similarity index 100%
rename from skills/ads-audit/references/account-health-scoring.md
rename to google-ads/ads-audit/references/account-health-scoring.md
diff --git a/skills/ads-copy/SKILL.md b/google-ads/ads-copy/SKILL.md
similarity index 94%
rename from skills/ads-copy/SKILL.md
rename to google-ads/ads-copy/SKILL.md
index 08e5951f..fdfe2d6c 100644
--- a/skills/ads-copy/SKILL.md
+++ b/google-ads/ads-copy/SKILL.md
@@ -1,37 +1,17 @@
---
name: ads-copy
description: Generate and A/B test Google Ads copy. Use when asked to write ad copy, headlines, descriptions, create ad variants, test ad messaging, improve CTR, or generate RSA (Responsive Search Ad) components. Trigger on "ad copy", "write ads", "headlines", "descriptions", "RSA", "responsive search ad", "ad text", "ad creative", "improve CTR", "ad A/B test", "ad variants", "write me an ad", or when the user wants to improve click-through rate on existing ads.
+argument-hint: "<ad group name, keyword theme, or 'write new ads'>"
---
-## MCP Server Detection
-
-Before calling any Google Ads tool, detect which MCP server is available:
-
-1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`
-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:
->
-> 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)
->
-> Or configure any Google Ads MCP server manually in your MCP settings.
+## Setup
-Use whichever MCP server's tool prefix is available for all subsequent calls in this session.
+Read and follow `../shared/preamble.md` — it handles MCP detection, token, and account selection. If config is already cached, this is instant.
# Ad Copy Generator + A/B Tester
Write Google Ads RSA copy and run structured A/B tests to find winning messaging.
-## Setup
-
-Follow the **MCP Server Detection** section above to verify a Google Ads MCP server is available.
-
-- **If no MCP server is found** → guide the user through setup per the MCP Server Detection instructions, or run `/ads-audit` which walks through full setup (MCP server, token, account selection, and business context).
-- **If the MCP server is available** → read `~/.adsagent/config.json` for `apiKey` and `accountId`. If missing, run `/ads-audit` for onboarding.
-
## Reference Documents
Before generating any copy, read these reference documents for expert-level context:
diff --git a/skills/ads-copy/evals/evals.json b/google-ads/ads-copy/evals/evals.json
similarity index 100%
rename from skills/ads-copy/evals/evals.json
rename to google-ads/ads-copy/evals/evals.json
diff --git a/skills/ads-copy/references/rsa-best-practices.md b/google-ads/ads-copy/references/rsa-best-practices.md
similarity index 100%
rename from skills/ads-copy/references/rsa-best-practices.md
rename to google-ads/ads-copy/references/rsa-best-practices.md
diff --git a/skills/ads/SKILL.md b/google-ads/ads/SKILL.md
similarity index 90%
rename from skills/ads/SKILL.md
rename to google-ads/ads/SKILL.md
index e75d4b73..ee435230 100644
--- a/skills/ads/SKILL.md
+++ b/google-ads/ads/SKILL.md
@@ -1,6 +1,7 @@
---
name: ads
description: Manage Google Ads campaigns — read performance, optimize keywords, adjust bids and budgets, add negatives, pause/enable campaigns, manage ads/ad groups, tracking templates, location targeting, network settings, rename campaigns/ad groups, bulk operations, and undo changes. Use this skill whenever the user mentions Google Ads, campaigns, keywords, ad spend, CPA, ROAS, search terms, negative keywords, bids, budgets, ads performance, location targeting, geo targeting, or campaign settings — even if they don't say "ads" explicitly.
+argument-hint: "<campaign name, keyword, or 'show performance'>"
version: 2.0.0
triggers:
- google ads
@@ -89,94 +90,14 @@ If `account-baseline.json` doesn't exist, skip silently — it will be created a
Now handle whatever the user actually asked for.
-## MCP Server Detection
+## Setup
-Before calling any Google Ads tool, detect which MCP server is available:
-
-1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`
-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:
->
-> 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)
->
-> Or configure any Google Ads MCP server manually in your MCP settings.
-
-Use whichever MCP server's tool prefix is available for all subsequent calls in this session.
+Read and follow `../shared/preamble.md` — it handles MCP detection, token, and account selection. If config is already cached, this is instant.
# AdsAgent — Google Ads Management
Manage Google Ads campaigns via the MCP server.
-## Configuration
-
-All persistent config lives in `~/.adsagent/config.json`. This file survives across sessions and works in every context — Claude Code, Claude Desktop, MCP servers, etc.
-
-The config file has this shape:
-
-```json
-{
- "apiKey": "asa_...",
- "accountId": "1234567890"
-}
-```
-
-## Onboarding
-
-Before doing anything else, check whether the user is set up. Follow these steps in order — stop at the first issue and resolve it before continuing.
-
-### Step 0: Check for the AdsAgent MCP server
-
-Follow the **MCP Server Detection** section above. If no MCP server is found, guide the user through setup before continuing.
-
-### Step 1: Check for token
-
-Read `~/.adsagent/config.json` (create `~/.adsagent/` if it doesn't exist).
-
-Look for `apiKey` (the token) in the config file. If it's present, skip to Step 2.
-
-If it's missing, tell the user:
-
-> 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.
-
-When the user provides the key, save it to `~/.adsagent/config.json`.
-
-Then continue to Step 2.
-
-### Step 2: Select a Google Ads account
-
-Look for `accountId` in the config file. If it's present, proceed to fulfil the user's request.
-
-If `accountId` is not set:
-
-1. Run `listConnectedAccounts` to get all connected Google Ads accounts.
-2. **If there is exactly one account**, save it automatically — no need to bother the user. Write `accountId` to `~/.adsagent/config.json` and tell the user which account was selected (show account name and ID).
-3. **If there are multiple accounts**, present them as a numbered list showing account name and ID, then ask the user to pick one. Save their choice to `~/.adsagent/config.json`.
-4. **If there are zero accounts**, tell the user they don't have any Google Ads accounts connected yet and direct them to [adsagent.org](https://www.adsagent.org) to connect one.
-
-### Switching accounts
-
-If the user wants to switch accounts, run `listConnectedAccounts`, let them pick, and update `accountId` in `~/.adsagent/config.json`.
-
-## Calling tools
-
-Tools are available directly via the MCP server. Call them using the detected prefix (see MCP Server Detection above).
-
-**With AdsAgent MCP (default):**
-- `mcp__adsagent__listCampaigns` with `accountId` parameter
-- `mcp__adsagent__getKeywords` with `accountId` and `campaignId`
-- etc.
-
-**With Google's official MCP:**
-- Tool names follow the `mcp__google_ads_mcp__*` pattern
-- Consult the server's tool list for exact names
-
-Always pass `accountId` from `~/.adsagent/config.json` to every tool call (except `listConnectedAccounts`). All responses are JSON.
-
## Available Tools
### Read (safe, no side effects)
@@ -343,7 +264,7 @@ Update the baseline at the END of any session where you pulled campaign performa
## Reference Documents
-Before performing any analysis, read the following reference documents for expert-level context:
+These reference documents contain expert-level thresholds, decision trees, and industry benchmarks. Read them **only when performing analysis, optimization, or reporting** — skip for simple operations like pausing a keyword, adjusting a bid, or listing campaigns.
- `references/quality-score-framework.md` — QS diagnostics and optimization playbook
- `references/bid-strategy-decision-tree.md` — When to use which bidding strategy
@@ -351,8 +272,6 @@ Before performing any analysis, read the following reference documents for exper
- `references/search-term-analysis-guide.md` — Search term interpretation and negative keyword strategy
- `references/campaign-structure-guide.md` — Account structure best practices
-Read these at the start of any analysis or optimization session. They contain the numeric thresholds, decision trees, and industry context that separate generic advice from expert recommendations.
-
## Analysis Heuristics
When interpreting Google Ads data, apply these specific rules. Every recommendation must reference a threshold — never give vague "optimize this" advice.
diff --git a/skills/ads/evals/evals.json b/google-ads/ads/evals/evals.json
similarity index 100%
rename from skills/ads/evals/evals.json
rename to google-ads/ads/evals/evals.json
diff --git a/skills/ads/references/bid-strategy-decision-tree.md b/google-ads/ads/references/bid-strategy-decision-tree.md
similarity index 100%
rename from skills/ads/references/bid-strategy-decision-tree.md
rename to google-ads/ads/references/bid-strategy-decision-tree.md
diff --git a/skills/ads/references/campaign-structure-guide.md b/google-ads/ads/references/campaign-structure-guide.md
similarity index 100%
rename from skills/ads/references/campaign-structure-guide.md
rename to google-ads/ads/references/campaign-structure-guide.md
diff --git a/skills/ads/references/industry-benchmarks.md b/google-ads/ads/references/industry-benchmarks.md
similarity index 100%
rename from skills/ads/references/industry-benchmarks.md
rename to google-ads/ads/references/industry-benchmarks.md
diff --git a/skills/ads/references/quality-score-framework.md b/google-ads/ads/references/quality-score-framework.md
similarity index 100%
rename from skills/ads/references/quality-score-framework.md
rename to google-ads/ads/references/quality-score-framework.md
diff --git a/skills/ads/references/search-term-analysis-guide.md b/google-ads/ads/references/search-term-analysis-guide.md
similarity index 100%
rename from skills/ads/references/search-term-analysis-guide.md
rename to google-ads/ads/references/search-term-analysis-guide.md
diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.md
new file mode 100644
index 00000000..bee9cd27
--- /dev/null
+++ b/google-ads/shared/preamble.md
@@ -0,0 +1,64 @@
+# 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.
+
+## Step 1: Check config cache
+
+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.
+
+## Step 2: MCP Server Detection
+
+Only runs if Step 1 found missing config.
+
+1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`
+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:
+>
+> 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)
+>
+> Or configure any Google Ads MCP server manually in your MCP settings.
+
+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).
+
+### Token
+
+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.
+
+### 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
+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`.
+
+## Step 4: 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 `~/.adsagent/config.json` to every tool call (except `listConnectedAccounts`).
+
+## Step 5: Proceed
+
+Config is loaded. Hand control back to the invoking skill.
diff --git a/skills/content-writer/SKILL.md b/seo/content-writer/SKILL.md
similarity index 99%
rename from skills/content-writer/SKILL.md
rename to seo/content-writer/SKILL.md
index fcca52e0..521ebe9e 100644
--- a/skills/content-writer/SKILL.md
+++ b/seo/content-writer/SKILL.md
@@ -1,5 +1,6 @@
---
name: content-writer
+argument-hint: "<keyword, topic, or URL to improve>"
description: >
Write SEO-optimized blog posts, landing pages, and content improvements
following Google's E-E-A-T and Helpful Content guidelines. Handles new content
diff --git a/seo/content-writer/evals/evals.json b/seo/content-writer/evals/evals.json
new file mode 100644
index 00000000..24de73d1
--- /dev/null
+++ b/seo/content-writer/evals/evals.json
@@ -0,0 +1,49 @@
+{
+ "skill_name": "content-writer",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Write a blog post targeting the keyword 'how to clean a dryer vent'. My site is a home services company called CleanAir Pros based in Denver.",
+ "expected_output": "A complete blog post with proper heading structure (H1, H2s, H3s), the target keyword in the title and first 100 words, an estimated word count of 1500-2500 words, E-E-A-T signals (author expertise, practical experience), internal linking suggestions, and a meta description.",
+ "files": [],
+ "expectations": [
+ "Title includes the target keyword 'how to clean a dryer vent' or close variant",
+ "Content has a clear heading hierarchy with H2s for major sections",
+ "Includes practical step-by-step instructions (not just theory)",
+ "References Denver or local context where relevant",
+ "Includes E-E-A-T signals — mentions experience, expertise, or practical knowledge",
+ "Suggests a meta description with character count",
+ "Content is genuinely helpful and would satisfy the search intent (informational how-to)"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Improve this landing page content for our dog grooming service. Target keyword: 'dog grooming austin'. Here's the current page:\n\n# Dog Grooming\n\nWe groom dogs. Our groomers are experienced. We offer baths, haircuts, and nail trims.\n\nCall us today!\n\nPrices start at $40.",
+ "expected_output": "A rewritten landing page that is conversion-focused, includes the target keyword naturally, adds social proof sections, has a clear CTA, includes service details with pricing structure, and addresses customer pain points. Should identify that the original is thin content with no location specificity, no trust signals, and no differentiation.",
+ "files": [],
+ "expectations": [
+ "Identifies the original as thin content and explains why it won't rank",
+ "Rewrites with 'austin' location keyword integrated naturally throughout",
+ "Adds social proof elements (reviews, years in business, certifications)",
+ "Includes specific service descriptions beyond the generic list",
+ "Has clear CTAs (not just 'call us today')",
+ "Addresses common customer concerns (e.g., anxiety, breed-specific needs)",
+ "Resulting content is meaningfully longer and more detailed than the original"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "I need a comparison landing page: 'tankless vs tank water heaters'. We sell and install both but want to push tankless. We're Pacific Plumbing in Portland, OR.",
+ "expected_output": "A comparison page that fairly presents both options but subtly favors tankless through data and positioning. Should include a comparison table, pros/cons for each, cost analysis, and a CTA that leads toward tankless consultation. The content should satisfy commercial investigation intent.",
+ "files": [],
+ "expectations": [
+ "Includes a comparison table or structured comparison format",
+ "Presents both options fairly (not a one-sided sales pitch)",
+ "Uses data points (energy savings, lifespan, upfront cost vs long-term) to favor tankless",
+ "Includes Portland/Oregon-specific context (climate, energy costs, rebates)",
+ "Has conversion elements (CTA for consultation, phone number placeholder)",
+ "Satisfies commercial investigation search intent — helps the reader make a decision"
+ ]
+ }
+ ]
+}
diff --git a/skills/content-writer/references/content-writing.md b/seo/content-writer/references/content-writing.md
similarity index 100%
rename from skills/content-writer/references/content-writing.md
rename to seo/content-writer/references/content-writing.md
diff --git a/skills/keyword-research/SKILL.md b/seo/keyword-research/SKILL.md
similarity index 99%
rename from skills/keyword-research/SKILL.md
rename to seo/keyword-research/SKILL.md
index ef792705..28d6d474 100644
--- a/skills/keyword-research/SKILL.md
+++ b/seo/keyword-research/SKILL.md
@@ -1,5 +1,6 @@
---
name: keyword-research
+argument-hint: "<topic, niche, or seed keyword>"
description: >
Discover, analyze, and prioritize keywords for SEO and GEO content strategies.
Identifies high-value opportunities based on search volume, competition,
diff --git a/seo/keyword-research/evals/evals.json b/seo/keyword-research/evals/evals.json
new file mode 100644
index 00000000..4e75e176
--- /dev/null
+++ b/seo/keyword-research/evals/evals.json
@@ -0,0 +1,47 @@
+{
+ "skill_name": "keyword-research",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Find keyword opportunities for a boutique pet boarding facility in Austin, TX. We specialize in cage-free boarding and dog daycare.",
+ "expected_output": "A keyword research report with seed keywords expanded into clusters, intent classification for each keyword, difficulty assessment, and prioritized recommendations. Should include local keywords (Austin-specific), service keywords (cage-free, daycare), and long-tail opportunities.",
+ "files": [],
+ "expectations": [
+ "Generates 20+ keyword suggestions organized into topic clusters",
+ "Classifies each keyword by search intent (informational, commercial, transactional)",
+ "Includes local keyword variants with 'Austin' and 'near me'",
+ "Identifies long-tail opportunities (e.g., 'cage-free dog boarding austin tx')",
+ "Prioritizes keywords by a scoring framework (not just listed randomly)",
+ "Suggests content types for each cluster (blog post, landing page, FAQ)"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "I run a SaaS tool for restaurant inventory management. We're trying to build organic traffic from scratch — no existing content. What keywords should we start with?",
+ "expected_output": "A prioritized keyword strategy for a zero-content SaaS site, focusing on low-competition informational keywords first (content marketing funnel), then building toward commercial terms. Should identify the buyer journey and suggest a phased approach.",
+ "files": [],
+ "expectations": [
+ "Recommends starting with low-competition informational keywords (not jumping to high-competition commercial terms)",
+ "Maps keywords to a buyer journey or funnel (awareness → consideration → decision)",
+ "Includes question-based keywords that could drive early traffic",
+ "Identifies competitor landscape and suggests differentiated angles",
+ "Provides a phased content calendar or sequencing recommendation",
+ "Includes both B2B and practitioner keywords (restaurant owners AND managers)"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "Research keywords around 'AI code review tools'. I want to understand the competitive landscape and find gaps.",
+ "expected_output": "A competitive keyword analysis showing what terms the major players rank for, where gaps exist, and which long-tail or question-based keywords are underserved. Should include GEO-relevant keywords (queries likely to trigger AI answers).",
+ "files": [],
+ "expectations": [
+ "Identifies major competitors in the space and their likely keyword targets",
+ "Finds gap keywords — terms with search demand but weak existing content",
+ "Includes comparison keywords ('X vs Y' format)",
+ "Flags GEO-relevant keywords where AI answers may appear in search",
+ "Distinguishes between developer-audience and manager-audience keywords",
+ "Provides actionable next steps (which keywords to write content for first)"
+ ]
+ }
+ ]
+}
diff --git a/skills/keyword-research/references/example-report.md b/seo/keyword-research/references/example-report.md
similarity index 100%
rename from skills/keyword-research/references/example-report.md
rename to seo/keyword-research/references/example-report.md
diff --git a/skills/keyword-research/references/keyword-intent-taxonomy.md b/seo/keyword-research/references/keyword-intent-taxonomy.md
similarity index 100%
rename from skills/keyword-research/references/keyword-intent-taxonomy.md
rename to seo/keyword-research/references/keyword-intent-taxonomy.md
diff --git a/skills/keyword-research/references/keyword-prioritization-framework.md b/seo/keyword-research/references/keyword-prioritization-framework.md
similarity index 100%
rename from skills/keyword-research/references/keyword-prioritization-framework.md
rename to seo/keyword-research/references/keyword-prioritization-framework.md
diff --git a/skills/keyword-research/references/topic-cluster-templates.md b/seo/keyword-research/references/topic-cluster-templates.md
similarity index 100%
rename from skills/keyword-research/references/topic-cluster-templates.md
rename to seo/keyword-research/references/topic-cluster-templates.md
diff --git a/skills/meta-tags-optimizer/SKILL.md b/seo/meta-tags-optimizer/SKILL.md
similarity index 99%
rename from skills/meta-tags-optimizer/SKILL.md
rename to seo/meta-tags-optimizer/SKILL.md
index 4b8b7a8e..d74e3c56 100644
--- a/skills/meta-tags-optimizer/SKILL.md
+++ b/seo/meta-tags-optimizer/SKILL.md
@@ -1,5 +1,6 @@
---
name: meta-tags-optimizer
+argument-hint: "<URL or page title to optimize>"
description: >
Optimize title tags, meta descriptions, Open Graph, and Twitter cards for
maximum click-through rate. Generates multiple A/B test variations with
diff --git a/seo/meta-tags-optimizer/evals/evals.json b/seo/meta-tags-optimizer/evals/evals.json
new file mode 100644
index 00000000..81037d45
--- /dev/null
+++ b/seo/meta-tags-optimizer/evals/evals.json
@@ -0,0 +1,47 @@
+{
+ "skill_name": "meta-tags-optimizer",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Optimize the meta tags for this page. Current title: 'Services - ABC Company'. Current description: 'We offer services.' Target keyword: 'commercial cleaning services dallas'.",
+ "expected_output": "Multiple title tag and meta description variations that include the target keyword, are within character limits (title ~60 chars, description ~155 chars), and are significantly more compelling than the generic originals. Should include character counts and explain why the originals are poor.",
+ "files": [],
+ "expectations": [
+ "Identifies specific problems with the current tags (generic, no keyword, no location, no value prop)",
+ "Generates 3+ title tag variations within ~60 character limit",
+ "Generates 3+ meta description variations within ~155 character limit",
+ "All variations include the target keyword or close variant",
+ "Includes character counts for each variation",
+ "At least one variation includes a CTA or urgency element in the description"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Create Open Graph and Twitter card meta tags for our new blog post: 'The Complete Guide to Sourdough Bread for Beginners'. URL: https://bakersjournal.com/sourdough-guide",
+ "expected_output": "Complete OG and Twitter Card meta tag HTML with og:title, og:description, og:image guidance, og:url, twitter:card, twitter:title, twitter:description. Tags should be optimized for social sharing with engaging copy distinct from the SEO meta description.",
+ "files": [],
+ "expectations": [
+ "Includes all required Open Graph tags (og:title, og:description, og:type, og:url)",
+ "Includes Twitter Card tags (twitter:card, twitter:title, twitter:description)",
+ "OG/Twitter descriptions are optimized for social engagement (may differ from SEO meta description)",
+ "Provides og:image guidance (recommended dimensions, format)",
+ "Output is valid HTML that can be copy-pasted into <head>",
+ "Explains the difference between SEO meta description and social meta tags"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "My homepage title is 'Best Plumber in Chicago | Fast & Affordable | 24/7 Emergency Service | Licensed & Insured | ABC Plumbing'. CTR from Google is only 1.2%. Help me fix it.",
+ "expected_output": "Diagnosis that the title is keyword-stuffed and too long (will be truncated in SERPs), followed by cleaner alternatives that balance keyword inclusion with readability. Should reference the low CTR as evidence the current approach isn't working.",
+ "files": [],
+ "expectations": [
+ "Identifies the title as too long and keyword-stuffed (Google will truncate it)",
+ "Calculates or estimates the character count and shows where truncation occurs",
+ "Explains why keyword stuffing hurts CTR (looks spammy in SERPs)",
+ "Provides 3+ shorter, cleaner alternatives within ~60 characters",
+ "Suggests a meta description to complement the new title",
+ "References the 1.2% CTR as below average and sets a realistic improvement target"
+ ]
+ }
+ ]
+}
diff --git a/skills/meta-tags-optimizer/references/ctr-and-social-reference.md b/seo/meta-tags-optimizer/references/ctr-and-social-reference.md
similarity index 100%
rename from skills/meta-tags-optimizer/references/ctr-and-social-reference.md
rename to seo/meta-tags-optimizer/references/ctr-and-social-reference.md
diff --git a/skills/meta-tags-optimizer/references/meta-tag-code-templates.md b/seo/meta-tags-optimizer/references/meta-tag-code-templates.md
similarity index 100%
rename from skills/meta-tags-optimizer/references/meta-tag-code-templates.md
rename to seo/meta-tags-optimizer/references/meta-tag-code-templates.md
diff --git a/skills/meta-tags-optimizer/references/meta-tag-formulas.md b/seo/meta-tags-optimizer/references/meta-tag-formulas.md
similarity index 100%
rename from skills/meta-tags-optimizer/references/meta-tag-formulas.md
rename to seo/meta-tags-optimizer/references/meta-tag-formulas.md
diff --git a/skills/schema-markup-generator/SKILL.md b/seo/schema-markup-generator/SKILL.md
similarity index 99%
rename from skills/schema-markup-generator/SKILL.md
rename to seo/schema-markup-generator/SKILL.md
index f96536af..eab47eaf 100644
--- a/skills/schema-markup-generator/SKILL.md
+++ b/seo/schema-markup-generator/SKILL.md
@@ -1,5 +1,6 @@
---
name: schema-markup-generator
+argument-hint: "<URL or page type, e.g. 'FAQ page' or 'product page'>"
description: >
Generate JSON-LD structured data markup for rich results in Google Search.
Supports FAQ, HowTo, Article, Product, LocalBusiness, and multi-type schemas.
diff --git a/seo/schema-markup-generator/evals/evals.json b/seo/schema-markup-generator/evals/evals.json
new file mode 100644
index 00000000..d0e8f46e
--- /dev/null
+++ b/seo/schema-markup-generator/evals/evals.json
@@ -0,0 +1,47 @@
+{
+ "skill_name": "schema-markup-generator",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Generate FAQ schema for my dental practice page. FAQs:\n1. How much does teeth whitening cost? - Professional teeth whitening costs $300-$800 depending on the method.\n2. Does dental insurance cover whitening? - Most dental insurance plans do not cover cosmetic whitening.\n3. How long does whitening last? - Results typically last 6-12 months with proper care.",
+ "expected_output": "Valid JSON-LD FAQPage schema with all 3 Q&A pairs properly structured, ready to paste into HTML. Should include @context, @type, and mainEntity array with Question/Answer pairs.",
+ "files": [],
+ "expectations": [
+ "Output is valid JSON-LD (parseable JSON with @context and @type)",
+ "Uses FAQPage schema type with mainEntity array",
+ "All 3 questions and answers are included with correct Question/acceptedAnswer structure",
+ "Includes implementation instructions (where to place in HTML)",
+ "Mentions Google's FAQ rich result eligibility requirements",
+ "JSON-LD is wrapped in a <script type='application/ld+json'> tag"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Create schema markup for my local bakery: Sweet Crumbs Bakery, 456 Oak St, Portland OR 97201. Open Mon-Sat 7am-6pm, Sun 8am-3pm. Phone: 503-555-0123. We specialize in sourdough bread and custom cakes.",
+ "expected_output": "LocalBusiness JSON-LD schema with name, address (PostalAddress), telephone, openingHoursSpecification for each day, and relevant product/service mentions. Should use the most specific @type (Bakery, not just LocalBusiness).",
+ "files": [],
+ "expectations": [
+ "Uses Bakery as @type (more specific than generic LocalBusiness)",
+ "Includes properly structured PostalAddress with street, city, state, zip",
+ "Has openingHoursSpecification for Mon-Sat and Sunday with different hours",
+ "Includes telephone in proper format",
+ "Mentions or includes product/service offerings (sourdough, custom cakes)",
+ "Output is valid, parseable JSON-LD"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "I have a product page for 'Premium Yoga Mat - EcoFlex Pro'. Price: $89.99. Rating: 4.7/5 from 234 reviews. In stock. Brand: EcoFlex. Generate the right schema.",
+ "expected_output": "Product schema with AggregateRating and Offer sub-schemas. Should include name, brand, offers (price, currency, availability), and aggregateRating (ratingValue, reviewCount). May also suggest Review schema for individual reviews.",
+ "files": [],
+ "expectations": [
+ "Uses Product @type with correct name and brand",
+ "Includes Offer with price (89.99), priceCurrency (USD), and availability (InStock)",
+ "Includes AggregateRating with ratingValue (4.7) and reviewCount (234)",
+ "Uses Schema.org availability enum (https://schema.org/InStock)",
+ "Output is valid JSON-LD that would pass Google's Rich Results Test",
+ "Suggests additional properties that could enhance the rich result (image, description, sku)"
+ ]
+ }
+ ]
+}
diff --git a/skills/schema-markup-generator/references/schema-decision-tree.md b/seo/schema-markup-generator/references/schema-decision-tree.md
similarity index 100%
rename from skills/schema-markup-generator/references/schema-decision-tree.md
rename to seo/schema-markup-generator/references/schema-decision-tree.md
diff --git a/skills/schema-markup-generator/references/schema-templates.md b/seo/schema-markup-generator/references/schema-templates.md
similarity index 100%
rename from skills/schema-markup-generator/references/schema-templates.md
rename to seo/schema-markup-generator/references/schema-templates.md
diff --git a/skills/schema-markup-generator/references/validation-guide.md b/seo/schema-markup-generator/references/validation-guide.md
similarity index 100%
rename from skills/schema-markup-generator/references/validation-guide.md
rename to seo/schema-markup-generator/references/validation-guide.md
diff --git a/skills/seo-analysis/SKILL.md b/seo/seo-analysis/SKILL.md
similarity index 96%
rename from skills/seo-analysis/SKILL.md
rename to seo/seo-analysis/SKILL.md
index adaf592b..87860097 100644
--- a/skills/seo-analysis/SKILL.md
+++ b/seo/seo-analysis/SKILL.md
@@ -1,5 +1,6 @@
---
name: seo-analysis
+argument-hint: "<URL to audit, e.g. https://example.com>"
description: >
Full SEO audit: Google Search Console data + URL Inspection API + technical
crawl + keyword research + metadata audit + schema markup audit + search
@@ -67,34 +68,9 @@ user-provided URL.
## Phase 0 — Preflight Check
-Run this once before anything else. It checks gcloud, ensures a GCP project
-exists, enables the Search Console API, and opens the browser for Google OAuth
-if needed:
+Read and follow `../shared/preamble.md` — it handles script discovery, gcloud auth, and GSC API setup. If credentials are already cached, this is instant.
-```bash
-SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
-[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1
-python3 "$SKILL_SCRIPTS/preflight.py"
-```
-
-- **`OK: All dependencies ready.`** → continue to Phase 1.
-- **Browser opens for Google login** → the user needs to log in with the Google
- account that owns their Search Console properties. Preflight finishes
- automatically after login.
-- **`gcloud init` runs** → first-time user. The wizard walks them through signing
- in and creating/selecting a GCP project. After it completes, preflight continues
- automatically.
-- **`Search Console API: enabled`** → preflight auto-enabled the API. No action
- needed.
-- **ERROR: Could not enable the Search Console API** → the user needs to enable
- it manually: `gcloud services enable searchconsole.googleapis.com`. If billing
- is required, link a billing account at https://console.cloud.google.com/billing
- (the Search Console API itself is free).
-- **gcloud not found** → OS-specific install instructions are printed. Install
- gcloud, then re-run Phase 0.
-- **No gcloud and user wants to skip GSC** → that is fine. Jump directly to
- Phase 5 for a technical-only audit (crawl, meta tags, schema, indexing). GSC
- data just will not be available.
+If the user has no gcloud and wants to skip GSC, jump directly to Phase 5 for a technical-only audit (crawl, meta tags, schema, indexing).
> **Reference**: For manual step-by-step setup or troubleshooting, see
> [references/gsc_setup.md](references/gsc_setup.md).
@@ -103,9 +79,9 @@ python3 "$SKILL_SCRIPTS/preflight.py"
## Phase 1 — Confirm Access to Google Search Console
+Using `$SKILL_SCRIPTS` from the shared preamble (Step 2):
+
```bash
-SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
-[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1
python3 "$SKILL_SCRIPTS/list_gsc_sites.py"
```
@@ -286,7 +262,6 @@ This phase is **non-blocking** — if no CMS is configured it is silently skippe
### Detect configured CMS
```bash
-SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
CMS_TYPE=$(python3 "$SKILL_SCRIPTS/cms_detect.py" 2>/dev/null)
CMS_DETECT_EXIT=$?
```
diff --git a/skills/seo-analysis/evals/evals.json b/seo/seo-analysis/evals/evals.json
similarity index 100%
rename from skills/seo-analysis/evals/evals.json
rename to seo/seo-analysis/evals/evals.json
diff --git a/skills/seo-analysis/references/gsc_setup.md b/seo/seo-analysis/references/gsc_setup.md
similarity index 100%
rename from skills/seo-analysis/references/gsc_setup.md
rename to seo/seo-analysis/references/gsc_setup.md
diff --git a/skills/seo-analysis/scripts/analyze_gsc.py b/seo/seo-analysis/scripts/analyze_gsc.py
similarity index 100%
rename from skills/seo-analysis/scripts/analyze_gsc.py
rename to seo/seo-analysis/scripts/analyze_gsc.py
diff --git a/skills/seo-analysis/scripts/cms_detect.py b/seo/seo-analysis/scripts/cms_detect.py
similarity index 100%
rename from skills/seo-analysis/scripts/cms_detect.py
rename to seo/seo-analysis/scripts/cms_detect.py
diff --git a/skills/seo-analysis/scripts/fetch_contentful_content.py b/seo/seo-analysis/scripts/fetch_contentful_content.py
similarity index 100%
rename from skills/seo-analysis/scripts/fetch_contentful_content.py
rename to seo/seo-analysis/scripts/fetch_contentful_content.py
diff --git a/skills/seo-analysis/scripts/fetch_ghost_content.py b/seo/seo-analysis/scripts/fetch_ghost_content.py
similarity index 100%
rename from skills/seo-analysis/scripts/fetch_ghost_content.py
rename to seo/seo-analysis/scripts/fetch_ghost_content.py
diff --git a/skills/seo-analysis/scripts/fetch_strapi_content.py b/seo/seo-analysis/scripts/fetch_strapi_content.py
similarity index 100%
rename from skills/seo-analysis/scripts/fetch_strapi_content.py
rename to seo/seo-analysis/scripts/fetch_strapi_content.py
diff --git a/skills/seo-analysis/scripts/fetch_wordpress_content.py b/seo/seo-analysis/scripts/fetch_wordpress_content.py
similarity index 100%
rename from skills/seo-analysis/scripts/fetch_wordpress_content.py
rename to seo/seo-analysis/scripts/fetch_wordpress_content.py
diff --git a/skills/seo-analysis/scripts/list_gsc_sites.py b/seo/seo-analysis/scripts/list_gsc_sites.py
similarity index 100%
rename from skills/seo-analysis/scripts/list_gsc_sites.py
rename to seo/seo-analysis/scripts/list_gsc_sites.py
diff --git a/skills/seo-analysis/scripts/preflight.py b/seo/seo-analysis/scripts/preflight.py
similarity index 100%
rename from skills/seo-analysis/scripts/preflight.py
rename to seo/seo-analysis/scripts/preflight.py
diff --git a/skills/seo-analysis/scripts/preflight_contentful.py b/seo/seo-analysis/scripts/preflight_contentful.py
similarity index 100%
rename from skills/seo-analysis/scripts/preflight_contentful.py
rename to seo/seo-analysis/scripts/preflight_contentful.py
diff --git a/skills/seo-analysis/scripts/preflight_ghost.py b/seo/seo-analysis/scripts/preflight_ghost.py
similarity index 100%
rename from skills/seo-analysis/scripts/preflight_ghost.py
rename to seo/seo-analysis/scripts/preflight_ghost.py
diff --git a/skills/seo-analysis/scripts/preflight_strapi.py b/seo/seo-analysis/scripts/preflight_strapi.py
similarity index 100%
rename from skills/seo-analysis/scripts/preflight_strapi.py
rename to seo/seo-analysis/scripts/preflight_strapi.py
diff --git a/skills/seo-analysis/scripts/preflight_wordpress.py b/seo/seo-analysis/scripts/preflight_wordpress.py
similarity index 100%
rename from skills/seo-analysis/scripts/preflight_wordpress.py
rename to seo/seo-analysis/scripts/preflight_wordpress.py
diff --git a/skills/seo-analysis/scripts/push_strapi_seo.py b/seo/seo-analysis/scripts/push_strapi_seo.py
similarity index 100%
rename from skills/seo-analysis/scripts/push_strapi_seo.py
rename to seo/seo-analysis/scripts/push_strapi_seo.py
diff --git a/skills/seo-analysis/scripts/show_gsc.py b/seo/seo-analysis/scripts/show_gsc.py
similarity index 100%
rename from skills/seo-analysis/scripts/show_gsc.py
rename to seo/seo-analysis/scripts/show_gsc.py
diff --git a/skills/seo-analysis/scripts/url_inspection.py b/seo/seo-analysis/scripts/url_inspection.py
similarity index 100%
rename from skills/seo-analysis/scripts/url_inspection.py
rename to seo/seo-analysis/scripts/url_inspection.py
diff --git a/skills/setup-cms/SKILL.md b/seo/setup-cms/SKILL.md
similarity index 97%
rename from skills/setup-cms/SKILL.md
rename to seo/setup-cms/SKILL.md
index 1d9a9ba9..a00568f9 100644
--- a/skills/setup-cms/SKILL.md
+++ b/seo/setup-cms/SKILL.md
@@ -1,5 +1,6 @@
---
name: setup-cms
+argument-hint: "<CMS name: wordpress, strapi, contentful, or ghost>"
description: >
Connect a CMS to toprank SEO tools. Guides users through configuring
WordPress, Strapi, Contentful, or Ghost — tests the connection, and writes
@@ -25,10 +26,13 @@ invisible pages, content gaps, stale articles, and missing SEO fields.
---
+## Step 0 — Setup
+
+Read and follow `../shared/preamble.md` — it locates the SEO scripts directory. Use `$SKILL_SCRIPTS` from the preamble for all script calls below.
+
## Step 1 — Detect existing CMS configuration
```bash
-SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
CMS_TYPE=$(python3 "$SKILL_SCRIPTS/cms_detect.py" 2>/dev/null)
CMS_STATUS=$?
echo "CMS_TYPE=$CMS_TYPE EXIT=$CMS_STATUS"
diff --git a/seo/setup-cms/evals/evals.json b/seo/setup-cms/evals/evals.json
new file mode 100644
index 00000000..25693fe4
--- /dev/null
+++ b/seo/setup-cms/evals/evals.json
@@ -0,0 +1,33 @@
+{
+ "skill_name": "setup-cms",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Connect my WordPress site to toprank.",
+ "expected_output": "The skill should detect if a CMS is already configured, then guide the user through WordPress setup: asking for the WordPress URL, username, and Application Password. It should explain how to create an Application Password in WordPress Admin.",
+ "files": [],
+ "expectations": [
+ "Runs CMS detection first to check for existing configuration",
+ "Asks for WordPress URL, username, and Application Password",
+ "Explains how to create an Application Password (WordPress Admin → Users → Profile)",
+ "Asks about content type (posts vs pages) with a default",
+ "Saves credentials to .env.local",
+ "Tests the connection after saving credentials"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "I want to set up my Contentful space for SEO analysis.",
+ "expected_output": "The skill should guide the user through Contentful setup: asking for Space ID, Environment (with 'master' default), Delivery API key, and Content Type ID. Should explain where to find each value in the Contentful dashboard.",
+ "files": [],
+ "expectations": [
+ "Identifies the user wants Contentful (not generic CMS picker)",
+ "Asks for Space ID and explains where to find it (Settings → General)",
+ "Asks for Delivery API key and explains where to find it (Settings → API keys)",
+ "Offers 'master' as default environment",
+ "Asks for Content Type ID or helps the user identify it",
+ "Tests the connection with a preflight check after saving"
+ ]
+ }
+ ]
+}
diff --git a/seo/shared/preamble.md b/seo/shared/preamble.md
new file mode 100644
index 00000000..5c560314
--- /dev/null
+++ b/seo/shared/preamble.md
@@ -0,0 +1,44 @@
+# SEO Shared Preamble
+
+Every SEO skill reads this before doing anything else. It handles script discovery, GSC authentication, and site selection in one place — so individual skills don't repeat this logic.
+
+## Step 1: Check for cached GSC session
+
+If gcloud credentials already exist and the user has previously selected a GSC property in this session, skip to Step 4. Signs of a cached session:
+- `gcloud auth application-default print-access-token` succeeds silently
+- The target URL is already known from the conversation
+
+If both are true, skip straight to Step 4.
+
+## Step 2: Locate skill scripts
+
+All SEO skills share the scripts in `seo-analysis/scripts/`. Locate them once:
+
+```bash
+SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1
+```
+
+Use `$SKILL_SCRIPTS` for all subsequent script calls.
+
+## Step 3: Preflight — gcloud and GSC API
+
+Run the preflight check to ensure gcloud is installed, a GCP project exists, and the Search Console API is enabled:
+
+```bash
+python3 "$SKILL_SCRIPTS/preflight.py"
+```
+
+- **`OK: All dependencies ready.`** — continue to Step 4.
+- **Browser opens for Google login** — user needs to log in with the Google account that owns their Search Console properties. Preflight finishes automatically after login.
+- **`gcloud init` runs** — first-time user. The wizard walks them through setup. After it completes, preflight continues automatically.
+- **`Search Console API: enabled`** — preflight auto-enabled the API. No action needed.
+- **ERROR: Could not enable the Search Console API** — user needs to enable manually: `gcloud services enable searchconsole.googleapis.com`
+- **gcloud not found** — OS-specific install instructions are printed. Install gcloud, then re-run.
+- **No gcloud and user wants to skip GSC** — that is fine. GSC data won't be available, but skills can still operate on URL-only analysis (technical crawl, meta tags, schema).
+
+> **Reference**: For manual setup or troubleshooting, see `../seo-analysis/references/gsc_setup.md`.
+
+## Step 4: Proceed
+
+Scripts are located at `$SKILL_SCRIPTS`, auth is ready. All subsequent script calls in the invoking skill should use `$SKILL_SCRIPTS` directly — do not re-run the find command. Hand control back to the invoking skill.
diff --git a/test/install.test.sh b/test/install.test.sh
index 5da91ff9..59987ef1 100755
--- a/test/install.test.sh
+++ b/test/install.test.sh
@@ -43,20 +43,23 @@ assert_not_contains() {
! grep -q "$needle" "$path" 2>/dev/null && pass "$label" || fail "$label — '$needle' found in $path (should not be)"
}
-# Skills expected in skills/ directory
-SKILLS=(
- seo-analysis
- keyword-research
- meta-tags-optimizer
- schema-markup-generator
- content-writer
- setup-cms
- ads
- ads-audit
- ads-copy
- toprank-upgrade
+# Skill paths relative to repo root (name:path pairs)
+SKILL_ENTRIES=(
+ "ads:google-ads/ads"
+ "ads-audit:google-ads/ads-audit"
+ "ads-copy:google-ads/ads-copy"
+ "seo-analysis:seo/seo-analysis"
+ "keyword-research:seo/keyword-research"
+ "meta-tags-optimizer:seo/meta-tags-optimizer"
+ "schema-markup-generator:seo/schema-markup-generator"
+ "content-writer:seo/content-writer"
+ "setup-cms:seo/setup-cms"
+ "toprank-upgrade:toprank-upgrade-skill"
)
+skill_name() { echo "${1%%:*}"; }
+skill_path() { echo "${1#*:}"; }
+
# ─── Test 1: Plugin metadata exists and is valid ─────────────
echo ""
@@ -68,7 +71,7 @@ assert_file "$REPO_ROOT/.mcp.json" ".mcp.json exists"
assert_json_field "$REPO_ROOT/.claude-plugin/plugin.json" "name" "plugin.json has name"
assert_json_field "$REPO_ROOT/.claude-plugin/plugin.json" "version" "plugin.json has version"
-assert_json_field "$REPO_ROOT/.claude-plugin/plugin.json" "skills" "plugin.json has skills path"
+assert_json_field "$REPO_ROOT/.claude-plugin/plugin.json" "skills" "plugin.json has skills"
assert_json_field "$REPO_ROOT/.claude-plugin/marketplace.json" "plugins" "marketplace.json has plugins"
@@ -89,20 +92,28 @@ MKT_PLUGIN_VERSION=$(python3 -c "import json; print(json.load(open('$REPO_ROOT/.
&& pass "marketplace.json plugins[0].version matches VERSION" \
|| fail "version mismatch: marketplace plugin=$MKT_PLUGIN_VERSION, VERSION=$FILE_VERSION"
+# plugin.json skills array count matches actual skills
+PLUGIN_SKILL_COUNT=$(python3 -c "import json; print(len(json.load(open('$REPO_ROOT/.claude-plugin/plugin.json'))['skills']))")
+[ "$PLUGIN_SKILL_COUNT" -eq "${#SKILL_ENTRIES[@]}" ] \
+ && pass "plugin.json skills count ($PLUGIN_SKILL_COUNT) matches expected (${#SKILL_ENTRIES[@]})" \
+ || fail "plugin.json has $PLUGIN_SKILL_COUNT skills, expected ${#SKILL_ENTRIES[@]}"
+
# ─── Test 2: All skills exist with SKILL.md ──────────────────
echo ""
echo "=== 2. Skill directories ==="
-for skill in "${SKILLS[@]}"; do
- assert_dir "$REPO_ROOT/skills/$skill" "skill directory: $skill"
- assert_file "$REPO_ROOT/skills/$skill/SKILL.md" "SKILL.md exists: $skill"
+for entry in "${SKILL_ENTRIES[@]}"; do
+ skill=$(skill_name "$entry")
+ path=$(skill_path "$entry")
+ assert_dir "$REPO_ROOT/$path" "skill directory: $skill ($path)"
+ assert_file "$REPO_ROOT/$path/SKILL.md" "SKILL.md exists: $skill"
done
-# Guard: actual SKILL.md count must match the SKILLS array
-actual_skill_count=$(find "$REPO_ROOT/skills" -maxdepth 2 -name "SKILL.md" | wc -l | tr -d ' ')
-if [ "$actual_skill_count" -ne "${#SKILLS[@]}" ]; then
- fail "SKILLS array has ${#SKILLS[@]} entries but skills/ has $actual_skill_count SKILL.md files"
+# Guard: actual SKILL.md count must match
+actual_skill_count=$(find "$REPO_ROOT/google-ads" "$REPO_ROOT/seo" "$REPO_ROOT/toprank-upgrade-skill" -name "SKILL.md" | wc -l | tr -d ' ')
+if [ "$actual_skill_count" -ne "${#SKILL_ENTRIES[@]}" ]; then
+ fail "Expected ${#SKILL_ENTRIES[@]} SKILL.md files but found $actual_skill_count"
else
pass "skill count matches ($actual_skill_count)"
fi
@@ -120,27 +131,34 @@ echo "=== 3. Old structure removed ==="
&& pass "bin/ directory removed" \
|| fail "bin/ directory still exists"
-[ ! -d "$REPO_ROOT/seo" ] \
- && pass "seo/ directory removed" \
- || fail "seo/ directory still exists (skills should be in skills/)"
+[ ! -d "$REPO_ROOT/skills" ] \
+ && pass "skills/ flat directory removed" \
+ || fail "skills/ directory still exists (skills should be in google-ads/, seo/, toprank-upgrade-skill/)"
-[ ! -d "$REPO_ROOT/google-ads" ] \
- && pass "google-ads/ directory removed" \
- || fail "google-ads/ directory still exists (skills should be in skills/)"
+[ ! -d "$REPO_ROOT/.agents" ] \
+ && pass ".agents/ directory removed" \
+ || fail ".agents/ directory still exists (stale OpenAI agent configs)"
-[ ! -f "$REPO_ROOT/skills/ads/mcporter.json" ] \
- && pass "mcporter.json removed" \
- || fail "mcporter.json still exists (replaced by .mcp.json)"
-
-# ─── Test 4: No preamble injection remnants ──────────────────
+# ─── Test 4: Shared preambles exist ─────────────────────────
echo ""
-echo "=== 4. Preamble cleanup ==="
+echo "=== 4. Shared preambles ==="
+
+assert_file "$REPO_ROOT/google-ads/shared/preamble.md" "Google Ads shared preamble exists"
+assert_file "$REPO_ROOT/seo/shared/preamble.md" "SEO shared preamble exists"
-for skill in "${SKILLS[@]}"; do
- [ "$skill" = "toprank-upgrade" ] && continue
- assert_not_contains "$REPO_ROOT/skills/$skill/SKILL.md" "toprank-update-check" \
- "no preamble in $skill"
+# Ads skills reference the shared preamble (not inline MCP detection)
+for skill in ads ads-audit ads-copy; do
+ assert_contains "$REPO_ROOT/google-ads/$skill/SKILL.md" "../shared/preamble.md" \
+ "$skill references shared preamble"
+ assert_not_contains "$REPO_ROOT/google-ads/$skill/SKILL.md" "mcp__adsagent__listConnectedAccounts" \
+ "$skill does not inline MCP detection"
+done
+
+# SEO skills that need GSC reference the shared preamble
+for skill in seo-analysis setup-cms; do
+ assert_contains "$REPO_ROOT/seo/$skill/SKILL.md" "../shared/preamble.md" \
+ "$skill references shared preamble"
done
# ─── Test 5: MCP server configuration ───────────────────────
@@ -152,34 +170,47 @@ assert_contains "$REPO_ROOT/.mcp.json" "adsagent" ".mcp.json has adsagent server
assert_contains "$REPO_ROOT/.mcp.json" "mcp-remote" ".mcp.json uses mcp-remote"
assert_contains "$REPO_ROOT/.mcp.json" "ADSAGENT_API_KEY" ".mcp.json references API key env var"
-# ─── Test 6: Google Ads skills have MCP detection ────────────
+# ─── Test 6: CONNECTORS.md exists ───────────────────────────
echo ""
-echo "=== 6. MCP detection in ads skills ==="
+echo "=== 6. Connectors ==="
-for skill in ads ads-audit ads-copy; do
- assert_contains "$REPO_ROOT/skills/$skill/SKILL.md" "MCP Server Detection" \
- "MCP detection section in $skill"
-done
+assert_file "$REPO_ROOT/CONNECTORS.md" "CONNECTORS.md exists"
+assert_contains "$REPO_ROOT/CONNECTORS.md" "~~google-ads" "CONNECTORS.md has Google Ads placeholder"
+assert_contains "$REPO_ROOT/CONNECTORS.md" "~~search-console" "CONNECTORS.md has Search Console placeholder"
# ─── Test 7: Reference docs exist ───────────────────────────
echo ""
echo "=== 7. Reference documents ==="
-assert_dir "$REPO_ROOT/skills/ads/references" "ads references directory"
-assert_dir "$REPO_ROOT/skills/ads-audit/references" "ads-audit references directory"
-assert_dir "$REPO_ROOT/skills/ads-copy/references" "ads-copy references directory"
-assert_dir "$REPO_ROOT/skills/seo-analysis/references" "seo-analysis references directory"
+assert_dir "$REPO_ROOT/google-ads/ads/references" "ads references directory"
+assert_dir "$REPO_ROOT/google-ads/ads-audit/references" "ads-audit references directory"
+assert_dir "$REPO_ROOT/google-ads/ads-copy/references" "ads-copy references directory"
+assert_dir "$REPO_ROOT/seo/seo-analysis/references" "seo-analysis references directory"
-# ─── Test 8: Eval files exist ────────────────────────────────
+# ─── Test 8: Eval files exist for all skills ─────────────────
echo ""
echo "=== 8. Eval files ==="
-assert_file "$REPO_ROOT/skills/ads/evals/evals.json" "ads evals exist"
-assert_file "$REPO_ROOT/skills/ads-audit/evals/evals.json" "ads-audit evals exist"
-assert_file "$REPO_ROOT/skills/ads-copy/evals/evals.json" "ads-copy evals exist"
+for entry in "${SKILL_ENTRIES[@]}"; do
+ skill=$(skill_name "$entry")
+ path=$(skill_path "$entry")
+ assert_file "$REPO_ROOT/$path/evals/evals.json" "$skill evals exist"
+done
+
+# ─── Test 9: Frontmatter has argument-hint ───────────────────
+
+echo ""
+echo "=== 9. Argument hints ==="
+
+for entry in "${SKILL_ENTRIES[@]}"; do
+ skill=$(skill_name "$entry")
+ path=$(skill_path "$entry")
+ assert_contains "$REPO_ROOT/$path/SKILL.md" "argument-hint" \
+ "$skill has argument-hint in frontmatter"
+done
# ─── Results ──────────────────────────────────────────────────
diff --git a/skills/toprank-upgrade/SKILL.md b/toprank-upgrade-skill/SKILL.md
similarity index 98%
rename from skills/toprank-upgrade/SKILL.md
rename to toprank-upgrade-skill/SKILL.md
index 6006e66a..d3a3195a 100644
--- a/skills/toprank-upgrade/SKILL.md
+++ b/toprank-upgrade-skill/SKILL.md
@@ -1,5 +1,6 @@
---
name: toprank-upgrade
+argument-hint: "<or just run '/toprank-upgrade'>"
description: >
Upgrade toprank skills to the latest version. Detects global vs vendored
install, runs the upgrade, and shows what's new. Use when asked to "upgrade
diff --git a/toprank-upgrade-skill/evals/evals.json b/toprank-upgrade-skill/evals/evals.json
new file mode 100644
index 00000000..ca0cbb89
--- /dev/null
+++ b/toprank-upgrade-skill/evals/evals.json
@@ -0,0 +1,30 @@
+{
+ "skill_name": "toprank-upgrade",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Upgrade toprank to the latest version.",
+ "expected_output": "The skill should detect the install type (global-git, local-git, or vendored), save the current version, run the appropriate upgrade command, and show a What's New summary from the CHANGELOG.",
+ "files": [],
+ "expectations": [
+ "Detects the install type by checking known paths in order",
+ "Saves the old version number before upgrading",
+ "Runs the correct upgrade method for the detected install type",
+ "Shows a What's New summary with bullet points from CHANGELOG",
+ "Reports the version change (old → new)"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Is toprank up to date?",
+ "expected_output": "The skill should run a forced update check and report whether the user is on the latest version. If already up to date, it should confirm with the current version number. If an update is available, it should offer to upgrade.",
+ "files": [],
+ "expectations": [
+ "Runs the update check script with --force flag",
+ "If already latest: tells the user their current version and confirms it's up to date",
+ "If update available: shows old vs new version and offers to upgrade",
+ "Does not attempt an upgrade without user confirmation when just checking"
+ ]
+ }
+ ]
+}