Skip to content

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

feat: add universal Codex onboarding (#113)

Tong Chen8d9d54bb9a87
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 94fd1f0b..41c12535 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "The official ads, analytics, SEO, and GEO plugin from NotFair.",
- "version": "0.26.0"
+ "version": "0.27.0"
},
"plugins": [
{
"name": "notfair",
"source": "./",
"description": "Operate Google, Meta, X, and LinkedIn Ads; analyze Search Console and GA4; and run open-source SEO, GEO, and content workflows.",
- "version": "0.26.0",
+ "version": "0.27.0",
"author": {
"name": "NotFair",
"url": "https://notfair.co"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 3c95e0e9..67c739b6 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "notfair",
- "version": "0.26.0",
+ "version": "0.27.0",
"description": "The official ads, analytics, SEO, and GEO plugin from NotFair. Operate Google, Meta, X, and LinkedIn Ads; analyze Google Search Console and GA4; and run open-source search and content workflows from any compatible agent.",
"author": {
"name": "NotFair",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
new file mode 100644
index 00000000..75794674
--- /dev/null
+++ b/.codex-plugin/plugin.json
@@ -0,0 +1,41 @@
+{
+ "name": "notfair",
+ "version": "0.27.0",
+ "description": "The official ads, analytics, SEO, and GEO plugin from NotFair.",
+ "author": {
+ "name": "NotFair",
+ "url": "https://www.notfair.co"
+ },
+ "homepage": "https://www.notfair.co",
+ "repository": "https://github.com/nowork-studio/notfair-plugin",
+ "license": "MIT",
+ "keywords": [
+ "advertising",
+ "analytics",
+ "google-ads",
+ "marketing",
+ "seo"
+ ],
+ "skills": "./skills/",
+ "mcpServers": "./.mcp.json",
+ "interface": {
+ "displayName": "NotFair",
+ "shortDescription": "Operate ads and analyze search performance.",
+ "longDescription": "Connect once to operate Google, Meta, X, and LinkedIn Ads, analyze GA4 and Search Console, and use open-source SEO and GEO workflows.",
+ "developerName": "NotFair",
+ "category": "Productivity",
+ "capabilities": [
+ "Interactive",
+ "Write"
+ ],
+ "websiteURL": "https://www.notfair.co",
+ "privacyPolicyURL": "https://www.notfair.co/privacy",
+ "termsOfServiceURL": "https://www.notfair.co/terms",
+ "defaultPrompt": [
+ "Audit my Google Ads account and find wasted spend.",
+ "Review my paid media performance across channels.",
+ "Find my strongest SEO and content opportunities."
+ ],
+ "brandColor": "#111827"
+ }
+}
diff --git a/.mcp.json b/.mcp.json
index 40ec7fde..26ec5938 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -1,28 +1,8 @@
{
"mcpServers": {
- "NotFair-GoogleAds": {
+ "NotFair": {
"type": "http",
- "url": "https://notfair.co/api/mcp/google_ads"
- },
- "NotFair-MetaAds": {
- "type": "http",
- "url": "https://notfair.co/api/mcp/meta_ads"
- },
- "NotFair-XAds": {
- "type": "http",
- "url": "https://notfair.co/api/mcp/x_ads"
- },
- "NotFair-LinkedInAds": {
- "type": "http",
- "url": "https://notfair.co/api/mcp/linkedin_ads"
- },
- "NotFair-GoogleSearchConsole": {
- "type": "http",
- "url": "https://notfair.co/api/mcp/google_search_console"
- },
- "NotFair-GoogleAnalytics": {
- "type": "http",
- "url": "https://notfair.co/api/mcp/google_analytics"
+ "url": "https://notfair.co/api/mcp/notfair_ads"
}
}
}
diff --git a/AGENTS.md b/AGENTS.md
index 539f07ae..e6c9028c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -98,12 +98,8 @@ Skills under `seo/`, `paid-ads/`, `google-ads/`, `meta-ads/`, `analytics/`, `gem
## External dependencies
-- **Google Search Console (NotFair MCP)** — `https://notfair.co/api/mcp/google_search_console`, OAuth. Required for live Search Console analysis; existing local GSC workflows may also use Google OAuth directly.
-- **Google Analytics (NotFair MCP)** — `https://notfair.co/api/mcp/google_analytics`, OAuth. Required for live GA4 analysis and supported measurement configuration.
-- **Google Ads (NotFair MCP)** — `https://notfair.co/api/mcp/google_ads`, OAuth. Required for Google Ads skills.
-- **Meta Marketing API (NotFair MCP)** — required for Meta Ads skills.
-- **X Ads (NotFair MCP)** — `https://notfair.co/api/mcp/x_ads`, OAuth. Required for live X Ads work.
-- **LinkedIn Ads (NotFair MCP)** — `https://notfair.co/api/mcp/linkedin_ads`, OAuth. Required for live LinkedIn Ads work.
+- **Universal NotFair MCP** — `https://notfair.co/api/mcp/notfair_ads`, OAuth. The plugin registers this single connection for Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Search Console, and Google Analytics. Its tools carry platform prefixes such as `google_ads_`, `meta_ads_`, and `search_console_`; verify the requested platform is connected before claiming live access.
+- **Platform connections** — each live skill still requires its corresponding account or property to be connected inside the selected NotFair workspace. A universal MCP session does not imply that every platform is connected.
- **Google Gemini API key** — required for `gemini`.
TikTok, Amazon, and ChatGPT Ads skills are planning/review workflows unless the current session exposes a verified connector. They do not imply account or mutation access.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cbbf18dc..bc137b67 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
### Changed
+- **One-command universal MCP onboarding (v0.27.0).** Replaced the six bundled platform server registrations with one `NotFair` MCP connection at `https://notfair.co/api/mcp/notfair_ads`. Codex and Claude now need one OAuth grant; workspaces enabled in the staged Google-first rollout connect Google Ads during that flow, and every supported platform remains isolated behind explicit tool prefixes such as `google_ads_`, `meta_ads_`, and `search_console_`.
- **Repository renamed to `nowork-studio/notfair-plugin`.** Active clone, install, update-check, package metadata, and source links now use the new GitHub repository name. The plugin name and `/notfair:*` command namespace remain unchanged.
- **`/google-ads-copy` now records concepts and claim sources,** requires unsupported proof to be marked for substantiation, and makes test decisions from pre-set metrics and adequate exposure rather than early conversion-rate gaps.
diff --git a/CLAUDE.md b/CLAUDE.md
index 6a9febcf..665527c5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,6 +20,7 @@ NotFair is a host-agnostic plugin providing SEO, Google Ads, and Meta Ads skills
- **`AGENTS.md`** — the universal skill resolver. Every host reads this to route user intents to the right skill. Update it whenever a skill is added, removed, or its purpose changes.
- **`INSTALL_FOR_AGENTS.md`** — the single paste-URL target that walks an AI agent through host detection and install.
+- **`skills/`** — Codex's portable wrapper index into the canonical skill directories. Each wrapper preserves the canonical frontmatter and forwards to the full workflow; keep both in parity with `.claude-plugin/plugin.json`.
- **`install/README.md`** — convention for adding per-host install adapters (Codex, Hermes, etc.) without duplicating skills.
## Working style: brutal honesty, relentless quality
@@ -36,8 +37,8 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit
- Home of the `notfair` plugin — the public artifact customers install.
- Contains host-agnostic skills under `paid-ads/`, `google-ads/`, `meta-ads/`, `analytics/`, `seo/`, `gemini/`, and `notfair-upgrade-skill/`.
-- Registered via `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (Claude Code) and `AGENTS.md` (every other host).
-- Paired with NotFair MCP servers for Google, Meta, X, and LinkedIn Ads plus Google Search Console and Google Analytics (OAuth at notfair.co).
+- Registered via `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (Claude Code), `.codex-plugin/plugin.json` (Codex), and `AGENTS.md` (every host's resolver).
+- Paired with one universal NotFair MCP server for Google, Meta, X, and LinkedIn Ads plus Google Search Console and Google Analytics (OAuth at notfair.co).
## Critical: this ships to users
@@ -47,19 +48,21 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit
## Branding: NotFair
-The product is **NotFair**. All user-facing text, documentation, skill descriptions, and config namespaces use NotFair / `notfair.co` / `.notfair/` / `mcp__notfair__*`. The prior brand has been fully removed from this repo — do not reintroduce any of its strings (names, config paths, MCP prefixes, URI schemes, or domains) in new code, new docs, or rewrites of existing files. The only allowed "legacy" references in active code are the `mcp__notfair__*` prefix and `.notfair.json` config (these reflect the more recent NotFair → NotFair-GoogleAds namespace split, not the older rebrand).
+The product is **NotFair**. All user-facing text, documentation, skill descriptions, and config namespaces use NotFair / `notfair.co` / `.notfair/` / `mcp__NotFair__*`. The prior brand has been fully removed from this repo — do not reintroduce any of its strings (names, config paths, MCP prefixes, URI schemes, or domains) in new code, new docs, or rewrites of existing files. Dedicated platform-prefixed NotFair namespaces may remain in compatibility guidance, but the installed plugin's current default is the universal `NotFair` server.
## When adding or modifying a skill
1. Create/edit the skill directory under the appropriate category (`google-ads/`, `seo/`, etc.) with a `SKILL.md` containing valid frontmatter.
2. **Register it in `AGENTS.md`** under the matching intent table. A skill that isn't in `AGENTS.md` is invisible to Codex, Hermes, and any non-Claude host.
3. **Register it in `.claude-plugin/plugin.json`** under the `skills` array. A skill that exists on disk but isn't listed here will NOT appear in the installed Claude Code plugin — this has already bitten us once with `ads-landing`.
-4. Bump the version in three places so upgrades propagate:
+4. **Link it under `skills/`** using the skill's frontmatter name so Codex discovers the same canonical source without duplication.
+5. Bump the version in all manifests so upgrades propagate:
- `.claude-plugin/plugin.json` → `version`
+ - `.codex-plugin/plugin.json` → `version`
- `.claude-plugin/marketplace.json` → both `metadata.version` and `plugins[0].version`
- `VERSION` file at repo root
-5. Update `CHANGELOG.md` with a user-facing note.
-6. Verify locally, then ship via `/ship`. Users pick up the new version through `notfair:upgrade`.
+6. Update `CHANGELOG.md` with a user-facing note.
+7. Verify locally, then ship via `/ship`. Users pick up the new version through `notfair:upgrade`.
## Versioning
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
index b648946a..e0861bfa 100644
--- a/INSTALL_FOR_AGENTS.md
+++ b/INSTALL_FOR_AGENTS.md
@@ -24,11 +24,9 @@ If you cannot determine the host, ask the user once and proceed.
---
-## Step 2 — Acquire the repo
+## Step 2 — Acquire the repo when the host needs a workspace checkout
-If the NotFair repo is already on disk locally, use it; do not re-clone.
-
-Otherwise:
+Codex and Claude Code install directly from the marketplace in Step 3 and can skip this checkout. For Hermes and generic agents, use an existing local NotFair repo or clone it:
```bash
git clone https://github.com/nowork-studio/notfair-plugin.git
@@ -52,16 +50,19 @@ Then verify by listing installed plugins. No further action required — Claude
### host = `codex`
-Codex reads `AGENTS.md` natively. From the repo root:
+Install the public plugin through Codex:
```bash
-# Codex auto-discovers AGENTS.md at the workspace root.
-codex --workspace .
+codex plugin marketplace add nowork-studio/notfair-plugin --json && codex plugin add notfair@nowork-studio --json && codex mcp login NotFair
```
-NotFair's skills live under `seo/`, `google-ads/`, `meta-ads/`, `gemini/`. Codex reads `AGENTS.md` and routes user intents to the named skills' `SKILL.md` files.
+If Codex reports that `nowork-studio` is already configured, refresh it and continue:
-> **Note:** A dedicated Codex install adapter (`install/codex/`) may be added in future versions to register skills into Codex's global skill directory. For now, workspace-local usage is the supported path.
+```bash
+codex plugin marketplace upgrade nowork-studio --json && codex plugin add notfair@nowork-studio --json && codex mcp login NotFair
+```
+
+Verify that `notfair@nowork-studio` is installed and `codex mcp list` reports `NotFair` as authenticated. The plugin's Codex manifest loads its skills and one universal NotFair MCP connection; do not add the dedicated platform MCP endpoints separately.
### host = `hermes`
@@ -82,11 +83,12 @@ Read `AGENTS.md` at the repo root. It contains the full intent → skill routing
## Step 4 — Connect external services
+The plugin registers one universal NotFair MCP server at `https://notfair.co/api/mcp/notfair_ads`. The Codex install command above explicitly starts its native OAuth flow; other hosts prompt on install or first use. The user signs in once and selects a NotFair workspace. During the staged Google-first rollout, enabled workspaces also connect Google Ads when they do not already have an active account. Google Ads, Meta Ads, X Ads, LinkedIn Ads, Search Console, and Google Analytics then appear as platform-prefixed tools through that one connection.
+
NotFair skills depend on external APIs. Walk the user through whichever they need:
-- **Google Search Console** — required for any SEO skill that reads live ranking data. The skills will prompt for OAuth on first run.
-- **Google Ads** — connects via the NotFair MCP server at `https://notfair.co/api/mcp/google_ads` (OAuth). The user signs in once at notfair.co; the MCP handles the rest.
-- **Meta Ads (Facebook + Instagram)** — connects via the NotFair MCP server. Same OAuth flow.
+- **Google Ads** — connected in the same first-run flow for workspaces enabled in the staged Google-first rollout; otherwise connect it in NotFair.
+- **Google Search Console, Google Analytics, Meta Ads, X Ads, and LinkedIn Ads** — available through the same MCP after each platform is connected in the selected NotFair workspace.
- **Google Gemini** — required only for the `gemini` skill. Needs a Gemini API key in environment.
Do **not** invent credentials. If a skill needs auth that isn't present, surface the gap and walk the user through the connection flow.
diff --git a/README.md b/README.md
index 43566bf7..665bd873 100644
--- a/README.md
+++ b/README.md
@@ -58,13 +58,25 @@ You can also use plain language:
### Codex, Hermes, and other agents
-The NotFair Plugin's skill source is host-agnostic. Clone the repository and open it as a workspace; [`AGENTS.md`](AGENTS.md) maps marketing requests to the right skill.
+Install the universal NotFair plugin directly through Codex:
+
+```bash
+codex plugin marketplace add nowork-studio/notfair-plugin --json && codex plugin add notfair@nowork-studio --json && codex mcp login NotFair
+```
+
+Codex installs the skills, registers one NotFair MCP connection, and opens its OAuth flow. If you prefer a workspace-local checkout, clone the repository and open it as a workspace; [`AGENTS.md`](AGENTS.md) maps marketing requests to the right skill.
```bash
git clone https://github.com/nowork-studio/notfair-plugin.git
cd notfair-plugin
```
+If the `nowork-studio` marketplace is already configured, refresh it instead:
+
+```bash
+codex plugin marketplace upgrade nowork-studio --json && codex plugin add notfair@nowork-studio --json && codex mcp login NotFair
+```
+
For host-specific setup, give your agent [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md), or paste:
```text
@@ -161,16 +173,16 @@ Marketing work gets unreliable when every request goes through the same vague pr
## Live data and integrations
-Some skills work entirely from a repository, URL, or supplied export. Live account analysis requires the relevant connection.
+Some skills work entirely from a repository, URL, or supplied export. Live account analysis uses one OAuth-connected [universal NotFair MCP](https://notfair.co/api/mcp/notfair_ads). The plugin registers that connection automatically. During the staged Google-first rollout, enabled workspaces connect Google Ads in the same OAuth flow; every other platform becomes available after it is connected in the selected NotFair workspace.
| Data source | Used for | Connection |
|---|---|---|
-| **Google Search Console** | Search performance, queries, pages, indexing, URL inspection, and sitemaps | [NotFair Search Console MCP](https://notfair.co/api/mcp/google_search_console) via OAuth |
-| **Google Analytics 4** | Acquisition, engagement, landing pages, events, conversions, realtime, and measurement configuration | [NotFair Google Analytics MCP](https://notfair.co/api/mcp/google_analytics) via OAuth |
-| **Google Ads** | Campaign performance, search terms, bids, budgets, keywords, and change history | [NotFair Google Ads MCP](https://notfair.co) via OAuth |
-| **Meta Ads** | Facebook and Instagram campaigns, ad sets, creatives, and insights | [NotFair Meta Ads MCP](https://notfair.co) via OAuth |
-| **X Ads** | Campaigns, line items, performance, targeting, promoted posts, audiences, and approved mutations | [NotFair X Ads MCP](https://notfair.co/api/mcp/x_ads) via OAuth |
-| **LinkedIn Ads** | Campaign groups, campaigns, creatives, analytics, targeting, conversions, and leads | [NotFair LinkedIn Ads MCP](https://notfair.co/api/mcp/linkedin_ads) via OAuth |
+| **Google Search Console** | Search performance, queries, pages, indexing, URL inspection, and sitemaps | Universal NotFair MCP via `search_console_` tools |
+| **Google Analytics 4** | Acquisition, engagement, landing pages, events, conversions, realtime, and measurement configuration | Universal NotFair MCP via `google_analytics_` tools |
+| **Google Ads** | Campaign performance, search terms, bids, budgets, keywords, and change history | Universal NotFair MCP via `google_ads_` tools |
+| **Meta Ads** | Facebook and Instagram campaigns, ad sets, creatives, and insights | Universal NotFair MCP via `meta_ads_` tools |
+| **X Ads** | Campaigns, line items, performance, targeting, promoted posts, audiences, and approved mutations | Universal NotFair MCP via `x_ads_` tools |
+| **LinkedIn Ads** | Campaign groups, campaigns, creatives, analytics, targeting, conversions, and leads | Universal NotFair MCP via `linkedin_ads_` tools |
| **CMS platforms** | Content and SEO-field review in WordPress, Strapi, Contentful, or Ghost | Platform API or compatible MCP |
| **Google Gemini** | Cross-model review | Gemini API key |
diff --git a/VERSION b/VERSION
index 4e8f395f..1b58cc10 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.26.0
+0.27.0
diff --git a/analytics/google-analytics/SKILL.md b/analytics/google-analytics/SKILL.md
index ec6e5209..dc44dfc7 100644
--- a/analytics/google-analytics/SKILL.md
+++ b/analytics/google-analytics/SKILL.md
@@ -6,13 +6,13 @@ argument-hint: "<property, date range, metric, or GA4 question>"
# Google Analytics
-Read `../shared/operating-contract.md`. Use the live NotFair Google Analytics MCP at `https://notfair.co/api/mcp/google_analytics` as the source of truth.
+Read `../shared/operating-contract.md`. Use the `google_analytics_` tools on the universal NotFair MCP as the source of truth.
## Select the property and question
1. Resolve `~~google-analytics` to the actual GA4 connector and inspect its current tools. Confirm access with `listProperties` or the equivalent harmless property-list read.
2. Select the exact `properties/123456789` resource returned by the connector. Never substitute a `G-` measurement ID or Google account ID.
-3. Define the business question, primary metric, conversion or key-event definition, property timezone, date range, and comparison window. If the connector is missing or unauthorized, provide the endpoint/setup path and stop before claiming live data.
+3. Define the business question, primary metric, conversion or key-event definition, property timezone, date range, and comparison window. If the platform is missing or unauthorized, direct the user to reconnect the universal NotFair plugin and stop before claiming live data.
## Pull decision-grade evidence
diff --git a/analytics/search-console/SKILL.md b/analytics/search-console/SKILL.md
index f50d7f8c..c57df339 100644
--- a/analytics/search-console/SKILL.md
+++ b/analytics/search-console/SKILL.md
@@ -6,13 +6,13 @@ argument-hint: "<property, URL, query, date range, or sitemap>"
# Google Search Console
-Read `../shared/operating-contract.md`. Use the live NotFair Search Console MCP at `https://notfair.co/api/mcp/google_search_console` as the source of truth. For a full-site SEO audit that also needs crawling and on-page analysis, hand off to `/notfair:seo-analysis` after confirming access.
+Read `../shared/operating-contract.md`. Use the `search_console_` tools on the universal NotFair MCP as the source of truth. For a full-site SEO audit that also needs crawling and on-page analysis, hand off to `/notfair:seo-analysis` after confirming access.
## Select the exact property
1. Resolve `~~search-console` to the actual Search Console connector and inspect its current tools. Call `listProperties` or the equivalent harmless read before selecting a site.
2. Use the exact verified property form returned by the connector: `sc-domain:example.com` and `https://example.com/` are different properties.
-3. Define the search type, complete date window, comparison window, dimensions, and business question. If the connector is missing or unauthorized, provide the endpoint/setup path and stop before claiming live data.
+3. Define the search type, complete date window, comparison window, dimensions, and business question. If the platform is missing or unauthorized, direct the user to reconnect the universal NotFair plugin and stop before claiming live data.
## Analyze organic performance
diff --git a/analytics/shared/operating-contract.md b/analytics/shared/operating-contract.md
index 8f005e6d..9714c18f 100644
--- a/analytics/shared/operating-contract.md
+++ b/analytics/shared/operating-contract.md
@@ -2,7 +2,7 @@
Read this before using Search Console or Google Analytics data.
-1. Discover the requested platform's actual connector and harmlessly confirm the selected property. Do not treat another NotFair connector as proof of access.
+1. Discover the requested platform's actual tool prefix and harmlessly confirm the selected property. On the universal NotFair connector, call `listConnectedPlatforms` first and treat only the requested platform's prefixed tools as proof of access.
2. State the property, timezone, source, date window, comparison window, dimensions, filters, and metric or conversion definition beside material findings.
3. Prefer one broad, batched read over repeated narrow calls. Respect the tool's current quota and fan-out limits rather than copying limits from another platform.
4. Separate observed facts, inferences, and recommendations. State freshness, sampling, thresholding, row caps, attribution, or tracking limitations.
diff --git a/gemini/SKILL.md b/gemini/SKILL.md
index 055aae89..9233fac2 100644
--- a/gemini/SKILL.md
+++ b/gemini/SKILL.md
@@ -84,7 +84,7 @@ Determine what kind of changes are being reviewed. Check in this order:
### 2a — Check for Google Ads changes
Look for signs of Ads-related work in the current conversation context:
-- Recent MCP tool calls to `mcp__notfair__*` or `mcp__google_ads_mcp__*`
+- Recent MCP tool calls to universal `mcp__NotFair__google_ads_*` tools or a supported dedicated Google Ads namespace
- Discussion of campaigns, keywords, bids, budgets, ad copy, negative keywords
- Files like `.notfair/change-log.json` or Ads-related config changes
diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.md
index 87e2d688..a02d31e5 100644
--- a/google-ads/shared/preamble.md
+++ b/google-ads/shared/preamble.md
@@ -45,19 +45,14 @@ Continue to Step 2 (MCP detection always runs).
Always verify that a Google Ads MCP server is available — the MCP server could be down, unauthorized, or misconfigured even with a saved accountId.
-1. Check for NotFair tools. The MCP server may be exposed under several different tool-name prefixes depending on the host (across the NotFair → NotFair-GoogleAds namespace split, multiple prefixes may briefly coexist):
- - `mcp__NotFair-GoogleAds__*` / `mcp__notfair_googleads__*` / `mcp__NotFair_GoogleAds__*` — Claude Code CLI (NotFair plugin default, current; exact form depends on Claude Code's key sanitization)
- - `mcp__claude_ai_NotFairGoogleAds__*` — Claude Desktop / claude.ai plugin connector (current)
- - `mcp__notfair__*` / `mcp__claude_ai_NotFair__*` — pre-0.16.0 plugin (legacy NotFair prefix, before the GoogleAds namespace split)
- - any other prefix matching `mcp__.*[Nn]ot[Ff]air.*__` (future hosts)
+1. Check for NotFair tools. The current plugin registers one universal server whose platform tools are explicitly prefixed:
+ - `mcp__NotFair__google_ads_*` (or a host-sanitized equivalent) — current universal plugin default
+ - `mcp__NotFair-GoogleAds__*` / `mcp__notfair_googleads__*` / `mcp__NotFair_GoogleAds__*` — supported dedicated-server compatibility
+ - `mcp__claude_ai_NotFairGoogleAds__*` — supported hosted-connector compatibility
- **How to detect:** scan your available tool list for any tool whose name ends in `listConnectedAccounts`. Take everything before `listConnectedAccounts` as the detected prefix. If multiple candidates exist, prefer current over legacy: any `NotFair-GoogleAds`/`NotFairGoogleAds`/`notfair_googleads` variant > `mcp__notfair__` / `mcp__claude_ai_NotFair__` > any other match. Call `listConnectedAccounts` using that detected prefix, and save both the result and the prefix itself for reuse in Steps 3 and 4.
+ **How to detect:** first look for a tool whose name ends in `google_ads_listConnectedAccounts`; take everything before `listConnectedAccounts` as the detected prefix. If none exists, look for the dedicated form ending in `listConnectedAccounts`. Prefer the universal platform-prefixed form when both exist.
- **Legacy-prefix migration nudge:** if the chosen prefix is a legacy `mcp__notfair__` (or its `claude_ai_*` variant) and no current NotFair-GoogleAds variant is visible, briefly tell the user once:
-
- > Detected a legacy MCP server registration. The plugin's MCP server has been renamed to NotFair-GoogleAds — please **restart Claude Code** to pick up the new server registration. Continuing with the legacy server for this session.
-
- Then proceed normally — the legacy server still works (it points at the new `notfair.co/api/mcp/google_ads` endpoint after the recent rename); only the tool-name prefix is stale.
+ On the universal server, call `listConnectedPlatforms` **before** any platform-prefixed account tool. If `google_ads` is not connected, tell the user to connect Google Ads in the selected NotFair workspace and stop; do not call `google_ads_listConnectedAccounts`. Once connected, call the detected `listConnectedAccounts` once and save both the result and exact prefix for Steps 3 and 4. On a dedicated or hosted connector, call `listConnectedAccounts` directly.
2. If no NotFair variant exists, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*`.
3. If none exists, lead with the connection CTA — don't bury it in troubleshooting:
@@ -67,7 +62,7 @@ Always verify that a Google Ads MCP server is available — the MCP server could
> I can't see a Google Ads MCP server in this session, so I can't read your campaigns, pull spend, or make changes yet. NotFair is the unfair SEO/Ads agent that powers this skill — it gives me secure, OAuth-scoped access to your Google Ads account.
>
> **To connect:**
-> 1. Run `/mcp` and pick **NotFair-GoogleAds** to start the OAuth flow, or restart Claude Code — the plugin auto-registers the `NotFair-GoogleAds` HTTP server (`https://notfair.co/api/mcp/google_ads`) and opens a browser tab for sign-in on first use.
+> 1. Run `/mcp` and pick **NotFair**, or run `codex mcp login NotFair` in Codex CLI. The plugin auto-registers the universal HTTP server (`https://notfair.co/api/mcp/notfair_ads`); the host opens a browser tab for sign-in.
> 2. Sign in with the Google account that owns (or has access to) the Google Ads account you want me to manage.
> 3. Come back and re-run your request.
>
@@ -100,9 +95,8 @@ If the user explicitly asks to switch accounts, run `listConnectedAccounts`, let
Use whichever MCP server prefix was detected in Step 2:
-- **NotFair-GoogleAds MCP via Claude Code CLI (current):** `mcp__NotFair-GoogleAds__<toolName>` (or whatever sanitized form Claude Code emits — `mcp__notfair_googleads__`, `mcp__NotFair_GoogleAds__`, etc.)
-- **NotFair-GoogleAds MCP via Claude Desktop / claude.ai plugin (current):** `mcp__claude_ai_NotFairGoogleAds__<toolName>`
-- **Legacy NotFair MCP (pre-0.16.0 plugin):** `mcp__notfair__<toolName>` / `mcp__claude_ai_NotFair__<toolName>`
+- **Universal NotFair MCP (current plugin default):** `mcp__NotFair__google_ads_<toolName>` or the exact host-sanitized equivalent
+- **Dedicated NotFair Google Ads compatibility:** `mcp__NotFair-GoogleAds__<toolName>` / `mcp__claude_ai_NotFairGoogleAds__<toolName>`
- **Google's official MCP:** `mcp__google_ads_mcp__<toolName>`
Always call tools under the exact prefix detected in Step 2 — do not hardcode any prefix. Pass `accountId` from the resolved config (Step 1) to every tool call (except `listConnectedAccounts`).
diff --git a/install/README.md b/install/README.md
index 458d5b3d..b30a05ae 100644
--- a/install/README.md
+++ b/install/README.md
@@ -7,7 +7,7 @@ This directory is the home for **thin install adapters** that wire NotFair into
NotFair ships one source of truth for skills. Different agent hosts expect skills in different places:
- **Claude Code** — reads `.claude-plugin/plugin.json` directly from the repo. No adapter needed; the manifest at the repo root *is* the adapter.
-- **Codex** — reads `AGENTS.md` at the workspace root. No filesystem install yet; workspace-local usage is the supported path. A future `install/codex/` adapter can register skills into Codex's global skill directory.
+- **Codex** — installs the repository directly as `notfair@nowork-studio`. `.codex-plugin/plugin.json` loads the universal MCP configuration and a portable `skills/` wrapper index that forwards to the same host-agnostic skill sources; no separate copied adapter is needed.
- **Hermes** — reads `AGENTS.md` at the workspace root. Same shape as Codex.
## Adding a new host adapter
diff --git a/meta-ads/shared/preamble.md b/meta-ads/shared/preamble.md
index 18ab1eb2..ece62eea 100644
--- a/meta-ads/shared/preamble.md
+++ b/meta-ads/shared/preamble.md
@@ -56,12 +56,14 @@ Continue to Step 2 (MCP detection always runs).
Always verify that a Meta Ads MCP server is available — the MCP server could be down, unauthorized, or misconfigured even with a saved `metaAccountId`.
-1. Check for the NotFair Meta tools. The MCP server may be exposed under several different tool-name prefixes depending on the host:
- - `mcp__NotFair-MetaAds__*` / `mcp__notfair_metaads__*` / `mcp__NotFair_MetaAds__*` — Claude Code CLI (NotFair plugin default; exact form depends on Claude Code's key sanitization)
- - `mcp__claude_ai_NotFair-MetaAds__*` / `mcp__claude_ai_NotFairMetaAds__*` — Claude Desktop / claude.ai plugin connector
- - any other prefix matching `mcp__.*([Nn]ot[Ff]air[-_]?[Mm]eta[Aa]ds?)__` (future hosts)
+1. Check for the NotFair Meta tools. The current plugin registers one universal server whose Meta tools are platform-prefixed:
+ - `mcp__NotFair__meta_ads_*` (or a host-sanitized equivalent) — current universal plugin default
+ - `mcp__NotFair-MetaAds__*` / `mcp__notfair_metaads__*` / `mcp__NotFair_MetaAds__*` — supported dedicated-server compatibility
+ - `mcp__claude_ai_NotFair-MetaAds__*` / `mcp__claude_ai_NotFairMetaAds__*` — supported hosted-connector compatibility
- **How to detect:** scan your available tool list for any tool whose name ends in `listAdAccounts` AND whose prefix references Meta (matches the regex above — do not pick a generic `listAdAccounts` from another platform's MCP). Take everything before `listAdAccounts` as the detected prefix. Save the prefix and the result for reuse in Steps 3 and 4.
+ **How to detect:** first look for a tool whose name ends in `meta_ads_listAdAccounts`; take everything before `listAdAccounts` as the detected prefix. If none exists, look for a dedicated NotFair Meta form ending in `listAdAccounts`.
+
+ On the universal server, call `listConnectedPlatforms` **before** any platform-prefixed account tool. If `meta_ads` is not connected, tell the user to connect Meta Ads in the selected NotFair workspace and stop; do not call `meta_ads_listAdAccounts`. Once connected, call the detected `listAdAccounts` once and save both the result and exact prefix for Steps 3 and 4. On a dedicated or hosted connector, call `listAdAccounts` directly.
2. If no NotFair-MetaAds variant exists, check for Meta's official MCP or community Meta MCP servers (any `mcp__.*meta.*ads__listAdAccounts`). If you find one, fall back to it but warn the user that NotFair's heuristics are tuned for the NotFair MCP surface (specifically `runScript`'s `ads.graphParallel`).
@@ -69,7 +71,7 @@ Always verify that a Meta Ads MCP server is available — the MCP server could b
> No Meta Ads MCP server detected.
>
-> The NotFair plugin registers the `NotFair-MetaAds` HTTP MCP server (`https://notfair.co/api/mcp/meta_ads`) in `.mcp.json`. Try restarting Claude Code — on first connection it opens a browser tab for OAuth sign-in to NotFair. You can also trigger sign-in manually with `/mcp`.
+> The NotFair plugin registers one universal `NotFair` HTTP MCP server (`https://notfair.co/api/mcp/notfair_ads`) in `.mcp.json`. Trigger sign-in with the host's MCP UI (`/mcp` in Claude) or `codex mcp login NotFair` in Codex CLI; the host opens the browser OAuth flow.
>
> If the problem persists, run `/notfair:upgrade` to make sure your NotFair plugin includes the Meta server registration, or configure a Meta Ads MCP server manually.
@@ -100,8 +102,8 @@ If the user explicitly asks to switch accounts, run `listAdAccounts`, let them p
Use whichever MCP server prefix was detected in Step 2:
-- **NotFair-MetaAds via Claude Code CLI:** `mcp__NotFair-MetaAds__<toolName>` (or whatever sanitized form the host emits)
-- **NotFair-MetaAds via Claude Desktop / claude.ai plugin:** `mcp__claude_ai_NotFair-MetaAds__<toolName>` / `mcp__claude_ai_NotFairMetaAds__<toolName>`
+- **Universal NotFair MCP (current plugin default):** `mcp__NotFair__meta_ads_<toolName>` or the exact host-sanitized equivalent
+- **Dedicated NotFair Meta compatibility:** `mcp__NotFair-MetaAds__<toolName>` / `mcp__claude_ai_NotFairMetaAds__<toolName>`
Always call tools under the exact prefix detected in Step 2 — do not hardcode any prefix. The MCP server's `ads.activeAccountId` is the `act_<metaAccountId>` form derived from the saved `metaAccountId` (Step 1). For most tools you do not need to pass the account id explicitly (the server resolves it from the OAuth session); when a tool does take an `adAccountId` argument, pass `act_<metaAccountId>`.
diff --git a/paid-ads/paid-ads-guide/SKILL.md b/paid-ads/paid-ads-guide/SKILL.md
index 21b3ea62..a496fb7e 100644
--- a/paid-ads/paid-ads-guide/SKILL.md
+++ b/paid-ads/paid-ads-guide/SKILL.md
@@ -19,7 +19,7 @@ Answer NotFair product questions from the repository documentation or current of
## Essential facts
-NotFair supplies host-agnostic skills plus first-party MCP operating surfaces for Google Ads, Meta Ads, X Ads, and LinkedIn Ads. Each uses its dedicated workflow after OAuth connection. TikTok, Amazon, and ChatGPT Ads remain planning/review-first until the session has a verified connector; those skills are not a claim of publication access.
+NotFair supplies host-agnostic skills plus one OAuth-connected MCP operating surface for Google Ads, Meta Ads, X Ads, LinkedIn Ads, Google Analytics, and Search Console. Each platform keeps its dedicated workflow and platform-prefixed tools inside that universal connection. TikTok, Amazon, and ChatGPT Ads remain planning/review-first until the session has a verified connector; those skills are not a claim of publication access.
The goal-loop app makes an outcome measurable, verifies the baseline at the source, and revisits the metric on an approved cadence. The plugin is the hands-on companion for audits, briefs, and supported account operations. Explain the safety boundary plainly: an approved plan is not a live campaign, and a brief is not a published asset.
diff --git a/paid-ads/paid-ads-integrations/SKILL.md b/paid-ads/paid-ads-integrations/SKILL.md
index 3630dbd7..506afd4b 100644
--- a/paid-ads/paid-ads-integrations/SKILL.md
+++ b/paid-ads/paid-ads-integrations/SKILL.md
@@ -10,7 +10,7 @@ Read `../shared/operating-contract.md`. Treat tool discovery as the source of tr
## Verify before promising
-1. Inspect the available tool list and use the Google or Meta shared preamble when that surface is requested. For X Ads and LinkedIn Ads, resolve the platform-specific connector and require a harmless account/setup read before claiming access.
+1. Inspect the available tool list. On the universal NotFair MCP, call `listConnectedPlatforms` first. Use the Google or Meta shared preamble when that surface is requested; for X Ads and LinkedIn Ads, resolve the platform-prefixed tools and require a harmless account/setup read before claiming access.
2. Confirm OAuth/account access with a harmless account-list or read operation when the connector exposes one.
3. Record the exact platform, selected account, accessible date range, and whether the surface is read-only or mutation-capable.
4. If authorization fails, state the error and give the documented connection path. Do not retry a destructive operation or fall back to another account.
@@ -19,10 +19,10 @@ Read `../shared/operating-contract.md`. Treat tool discovery as the source of tr
| Platform | NotFair path | Safe response when unavailable |
|---|---|---|
-| Google Ads | `https://notfair.co/api/mcp/google_ads`; use the Google shared preamble | Connect/re-authenticate, then use the Google skills |
-| Meta Ads | `https://notfair.co/api/mcp/meta_ads`; use the Meta shared preamble | Connect/re-authenticate, then use the Meta skills |
-| X Ads | `https://notfair.co/api/mcp/x_ads`; resolve `~~x-ads` | Connect/re-authenticate, then use `/notfair:paid-ads-x` |
-| LinkedIn Ads | `https://notfair.co/api/mcp/linkedin_ads`; resolve `~~linkedin-ads` | Connect/re-authenticate, then use `/notfair:paid-ads-linkedin` |
+| Google Ads | Universal NotFair MCP `google_ads_` tools; use the Google shared preamble | Connect/re-authenticate, then use the Google skills |
+| Meta Ads | Universal NotFair MCP `meta_ads_` tools; use the Meta shared preamble | Connect/re-authenticate, then use the Meta skills |
+| X Ads | Universal NotFair MCP `x_ads_` tools; resolve `~~x-ads` | Connect/re-authenticate, then use `/notfair:paid-ads-x` |
+| LinkedIn Ads | Universal NotFair MCP `linkedin_ads_` tools; resolve `~~linkedin-ads` | Connect/re-authenticate, then use `/notfair:paid-ads-linkedin` |
| TikTok, Amazon, ChatGPT Ads | No first-party NotFair surface declared by this plugin | Request a verified connector or export; stay plan/review-only |
Never invent a router, endpoint, tool name, account ID, or platform capability. Quote prices, quotas, and platform eligibility only from current official documentation when a user asks; do not infer them from a plan or another connector.
diff --git a/paid-ads/paid-ads-linkedin/SKILL.md b/paid-ads/paid-ads-linkedin/SKILL.md
index fae454a9..bda0d8e1 100644
--- a/paid-ads/paid-ads-linkedin/SKILL.md
+++ b/paid-ads/paid-ads-linkedin/SKILL.md
@@ -6,11 +6,11 @@ argument-hint: "<B2B goal, audience, account, or date range>"
# LinkedIn Ads
-Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Prefer the live NotFair LinkedIn Ads MCP at `https://notfair.co/api/mcp/linkedin_ads`; use a supplied export only when no verified connector is available.
+Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Prefer the `linkedin_ads_` tools on the universal NotFair MCP; use a supplied export only when no verified connector is available.
## Establish access and qualified-demand context
-1. Resolve `~~linkedin-ads` to the actual LinkedIn connector and inspect its current tools. Confirm the selected account with a harmless account/setup read. Do not infer access from another NotFair connector.
+1. Resolve `~~linkedin-ads` to the universal connector's `linkedin_ads_` tool surface or a verified compatible connector. Call `listConnectedPlatforms` when using NotFair, then confirm the selected account with a harmless account/setup read. Do not infer LinkedIn access from another platform's tools.
2. If the connector is missing or unauthorized, request re-authorization or a current export and keep the result plan/review-only.
3. Define the sales-qualified conversion, CRM feedback loop, account currency, attribution basis, target CPA or pipeline outcome, and complete date window before diagnosing performance.
diff --git a/paid-ads/paid-ads-setup/SKILL.md b/paid-ads/paid-ads-setup/SKILL.md
index 27c69910..4a4bf0e1 100644
--- a/paid-ads/paid-ads-setup/SKILL.md
+++ b/paid-ads/paid-ads-setup/SKILL.md
@@ -10,7 +10,7 @@ Read `../shared/operating-contract.md`. Do not alter campaigns during setup.
## Establish access
-1. Detect the requested NotFair platform surface. Use the existing shared preambles for Google Ads and Meta Ads; use `https://notfair.co/api/mcp/x_ads` for X Ads and `https://notfair.co/api/mcp/linkedin_ads` for LinkedIn Ads. If the requested connector is missing, give its connection path and stop before claiming access.
+1. Detect the requested platform on the universal NotFair MCP. Call `listConnectedPlatforms`, then use the existing shared preambles for Google Ads and Meta Ads or the `x_ads_` and `linkedin_ads_` tool surfaces. If the requested platform is missing, direct the user to connect it in NotFair and stop before claiming access.
2. List only accounts actually returned by the connected surface. Let the user select the intended account when more than one is available; never infer it from an account name.
3. For TikTok, Amazon, and ChatGPT Ads, check the available tools before proposing a connection. If no verified connector exists, request a current export or describe the plan-only boundary.
diff --git a/paid-ads/paid-ads-x/SKILL.md b/paid-ads/paid-ads-x/SKILL.md
index e0fb0000..376c09ff 100644
--- a/paid-ads/paid-ads-x/SKILL.md
+++ b/paid-ads/paid-ads-x/SKILL.md
@@ -6,11 +6,11 @@ argument-hint: "<account, campaign, date range, or X Ads goal>"
# X Ads
-Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Use the live NotFair X Ads MCP as the source of truth; its dedicated endpoint is `https://notfair.co/api/mcp/x_ads`.
+Read `../shared/operating-contract.md` and `../shared/measurement-framework.md` before acting. Use the `x_ads_` tools on the universal NotFair MCP as the source of truth.
## Establish the live scope
-1. Discover the X Ads connector and its current tool surface. Resolve the tool-agnostic placeholder `~~x-ads` to that connector; do not infer access from a Google, Meta, or universal NotFair tool.
+1. Resolve `~~x-ads` to the universal connector's `x_ads_` tool surface or a verified compatible connector. On the universal connector, call `listConnectedPlatforms` and require X Ads to be connected; do not infer X access from another platform's tools.
2. Confirm the selected account with a harmless account/setup read. If the connector is missing or unauthorized, direct the user to connect or re-authorize X Ads and stop before claiming live access.
3. Record the account currency, timezone, objective, conversion definition, attribution basis, and requested date window. Treat tracking gaps as limitations, not zero performance.
diff --git a/seo/content-writer/SKILL.md b/seo/content-writer/SKILL.md
index b8c43821..3cbf5bd9 100644
--- a/seo/content-writer/SKILL.md
+++ b/seo/content-writer/SKILL.md
@@ -224,8 +224,8 @@ first surface that's actually available in the current host, in this order:
1. **Codex or other host with native image generation** (gpt-image, Imagen, etc.)
— generate the image inline. Save to `images/` or the path the user specifies.
-2. **NotFair MCP `generate_image`** — if a NotFair MCP server is connected
- (`mcp__NotFair-GoogleAds__generate_image` or `mcp__NotFair-MetaAds__generate_image`),
+2. **NotFair MCP `generate_image`** — if the universal NotFair MCP is connected
+ (`mcp__NotFair__google_ads_generate_image` or `mcp__NotFair__meta_ads_generate_image`, subject to host sanitization),
it generates marketing-grade visuals from a prompt. Works for blog imagery too.
3. **No image-gen surface available** — output the detailed prompt for each image
so the user can run it in their own tool (Midjourney, DALL·E, Figma AI, etc.),
diff --git a/skills/backlink-audit/SKILL.md b/skills/backlink-audit/SKILL.md
new file mode 100644
index 00000000..62e5de4a
--- /dev/null
+++ b/skills/backlink-audit/SKILL.md
@@ -0,0 +1,22 @@
+---
+name: backlink-audit
+argument-hint: "<site URL — optionally attach a backlink export CSV from GSC/Ahrefs/Semrush>"
+description: >
+ Backlink / off-page SEO audit. Works WITHOUT a paid tool by default — it uses the
+ Google Search Console Links report (your top linking sites, most-linked pages,
+ and anchor text) plus any backlink export the user provides (Ahrefs / Semrush /
+ Majestic / DataForSEO CSV). Analyzes referring-domain profile, anchor-text
+ distribution (over-optimized / spammy patterns), most-linked pages vs. money
+ pages (internal-linking opportunity), toxic/spam link signals, and link-building
+ priorities. Use this skill when the user asks about backlinks, link building,
+ off-page SEO, referring domains, anchor text, toxic/spam links, disavow, or their
+ link profile. Trigger on: "backlinks", "backlink audit", "link building", "off-
+ page SEO", "referring domains", "anchor text", "toxic links", "spam links",
+ "disavow file", "who links to me", "link profile", "domain authority". NOTE: rich
+ third-party metrics (DR/DA, full link index) require a paid data source; this
+ skill is explicit about what it can and can't see without one.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/backlink-audit/SKILL.md`](../../seo/backlink-audit/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/backlink-audit/`.
diff --git a/skills/broken-link-checker/SKILL.md b/skills/broken-link-checker/SKILL.md
new file mode 100644
index 00000000..6559cbc5
--- /dev/null
+++ b/skills/broken-link-checker/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: broken-link-checker
+argument-hint: "<URL to check, e.g. https://example.com>"
+description: >
+ Scans a website to find broken links (404s, 500s). Crawls internal pages,
+ identifies broken outbound links, and reports source pages for easy fixing.
+ Use this when the user asks to "check for broken links", "find 404s",
+ "audit my links", or "is my site healthy".
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/broken-link-checker/SKILL.md`](../../seo/broken-link-checker/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/broken-link-checker/`.
diff --git a/skills/competitor-pages/SKILL.md b/skills/competitor-pages/SKILL.md
new file mode 100644
index 00000000..2266456b
--- /dev/null
+++ b/skills/competitor-pages/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: competitor-pages
+argument-hint: "<your page URL + 1-3 competitor URLs ranking for the same query>"
+description: >
+ Competitor page gap analysis — take a query you want to win and the pages
+ currently outranking you, and produce a concrete brief on what to add or change
+ to compete. Compares content depth and coverage (subtopics they cover that you
+ don't), structure (headings, format, tables, media), search-intent match, E-E-A-T
+ signals, schema/rich-result eligibility, internal linking, and on-page
+ optimization — across your page vs. the top-ranking competitors. Use this skill
+ whenever the user wants to know why a competitor outranks them on a specific
+ query, what a top-ranking page does better, a content-gap analysis against
+ specific competitor URLs, or a brief to beat a specific SERP. Trigger on:
+ "why does competitor X outrank me", "content gap analysis", "competitor page
+ analysis", "what does the top result have that I don't", "how do I beat this
+ page", "analyze competitor pages", "SERP gap", "compete for [keyword]". For seed
+ keyword discovery use /keyword-research; for a content calendar use
+ /content-planner.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/competitor-pages/SKILL.md`](../../seo/competitor-pages/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/competitor-pages/`.
diff --git a/skills/content-planner/SKILL.md b/skills/content-planner/SKILL.md
new file mode 100644
index 00000000..449b86ff
--- /dev/null
+++ b/skills/content-planner/SKILL.md
@@ -0,0 +1,17 @@
+---
+name: content-planner
+argument-hint: "<site URL or 'plan from GSC'>"
+description: >
+ GSC-driven content calendar. Pulls real Search Console data, finds the highest
+ click-potential opportunities (striking-distance queries at positions 5-20,
+ unanswered query intent, related-keyword expansions), and produces a dated,
+ prioritized content calendar — ready to hand to /content-writer. Use when the
+ user asks "plan my content", "what should I write next", "content calendar",
+ "content plan", "content roadmap", "editorial calendar", "what topics will
+ rank", "find quick-win SEO topics", "click-potential analysis", or "schedule
+ my SEO content".
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/content-planner/SKILL.md`](../../seo/content-planner/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/content-planner/`.
diff --git a/skills/content-writer/SKILL.md b/skills/content-writer/SKILL.md
new file mode 100644
index 00000000..37d574c6
--- /dev/null
+++ b/skills/content-writer/SKILL.md
@@ -0,0 +1,17 @@
+---
+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
+ creation from a keyword or topic, and improving existing pages. Use when asked
+ to "write a blog post", "create a landing page", "improve this page", "write
+ content about X", "content for keyword X", "draft an article", "blog post
+ about", "landing page for", "service page", "product page copy", "rewrite
+ this page", "make this page rank better", "content brief", "how-to guide",
+ "listicle", or any content creation or improvement task for a website.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/content-writer/SKILL.md`](../../seo/content-writer/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/content-writer/`.
diff --git a/skills/ecommerce-seo/SKILL.md b/skills/ecommerce-seo/SKILL.md
new file mode 100644
index 00000000..3cf79eab
--- /dev/null
+++ b/skills/ecommerce-seo/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: ecommerce-seo
+argument-hint: "<store URL, e.g. https://example.com or a category/product URL>"
+description: >
+ E-commerce SEO audit for online stores (WooCommerce, Shopify, Magento, custom).
+ Covers the structural problems unique to commerce sites: category / product
+ listing pages (PLP), product detail pages (PDP), faceted navigation and the
+ crawl-budget / duplicate-content traps it creates, pagination, canonical
+ handling for variants and filters, out-of-stock / discontinued product handling,
+ internal linking and breadcrumbs, and Product / Offer / Review / AggregateRating
+ / BreadcrumbList structured data for rich results. Use this skill whenever the
+ user runs an online store and asks about e-commerce SEO, product page SEO,
+ category page SEO, faceted navigation, filter URLs being indexed, product schema
+ / rich results, out-of-stock SEO, or thin/duplicate product pages. Trigger on:
+ "e-commerce SEO", "ecommerce SEO", "product page SEO", "category page SEO",
+ "WooCommerce SEO", "Shopify SEO", "faceted navigation", "filter URLs in Google",
+ "product schema", "rich snippets for products", "out of stock SEO", "duplicate
+ product pages". For a single URL use /seo-page; for full-site use /seo-analysis.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/ecommerce-seo/SKILL.md`](../../seo/ecommerce-seo/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/ecommerce-seo/`.
diff --git a/skills/gemini/SKILL.md b/skills/gemini/SKILL.md
new file mode 100644
index 00000000..1bad80a2
--- /dev/null
+++ b/skills/gemini/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: gemini
+argument-hint: "'review', 'challenge', or 'consult' + optional context"
+description: >
+ Cross-model second opinion from Google Gemini — a different AI reviewing the
+ same changes, with deep Google ecosystem knowledge. Three modes: review
+ (pass/fail gate for Google Ads campaigns, SEO metadata, or code), challenge
+ (adversarial stress-test that tries to break your changes), and consult
+ (open Q&A with Gemini on Google Ads strategy, SEO best practices, or
+ implementation questions). Use when the user says "gemini review", "ask
+ gemini", "gemini challenge", "second opinion from gemini", "consult gemini",
+ "stress test with gemini", "what would gemini say", "cross-model review",
+ or "get another opinion". Voice aliases: "gem", "gemini check". Especially
+ useful for Google Ads changes, SEO metadata updates, campaign structure
+ decisions, keyword strategies, and bid/budget changes — Gemini has native
+ Google ecosystem knowledge that complements Claude's analysis.
+triggers:
+ - gemini
+ - gemini review
+ - gemini challenge
+ - gemini consult
+ - ask gemini
+ - second opinion gemini
+ - stress test gemini
+ - gem review
+ - gem consult
+---
+
+# Canonical NotFair workflow
+
+Read [`../../gemini/SKILL.md`](../../gemini/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../gemini/`.
diff --git a/skills/geo-optimizer/SKILL.md b/skills/geo-optimizer/SKILL.md
new file mode 100644
index 00000000..633957d8
--- /dev/null
+++ b/skills/geo-optimizer/SKILL.md
@@ -0,0 +1,20 @@
+---
+name: geo-optimizer
+argument-hint: "<URL, file path, or topic to optimize for AI search>"
+description: >
+ Generative Engine Optimization (GEO) — make content rank in AI search
+ answers from ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews.
+ Audits existing content, rewrites for AI citation, and produces per-engine
+ strategy. Use when asked to "optimize for AI search", "rank in ChatGPT",
+ "GEO audit", "improve AI citations", "rank in Perplexity", "AI Overview
+ optimization", "AI Overview ranking", "LLM SEO", "answer engine
+ optimization", "AEO", "get cited by AI", "GEO", "generative engine
+ optimization", "show up in ChatGPT", "appear in AI answers", "be cited
+ by Perplexity", "SGE optimization", "Search Generative Experience", or
+ "make my content show up in AI answers". Distinct from regular SEO —
+ this targets generative engines, not traditional Google rankings.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/geo-optimizer/SKILL.md`](../../seo/geo-optimizer/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/geo-optimizer/`.
diff --git a/skills/google-ads-assets/SKILL.md b/skills/google-ads-assets/SKILL.md
new file mode 100644
index 00000000..490277dc
--- /dev/null
+++ b/skills/google-ads-assets/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: google-ads-assets
+description: Plan, validate, and safely publish Google Ads assets, including sitelinks, callouts, structured snippets, image assets, and Performance Max asset briefs. Use when asked for Google Ads assets, ad extensions, sitelinks, callouts, snippets, image assets, Performance Max assets, PMax creative, or an asset audit.
+argument-hint: "<campaign, asset group, or 'build an asset brief'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../google-ads/assets/SKILL.md`](../../google-ads/assets/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../google-ads/assets/`.
diff --git a/skills/google-ads-audit/SKILL.md b/skills/google-ads-audit/SKILL.md
new file mode 100644
index 00000000..5ed28630
--- /dev/null
+++ b/skills/google-ads-audit/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: google-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 NotFair 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'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../google-ads/audit/SKILL.md`](../../google-ads/audit/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../google-ads/audit/`.
diff --git a/skills/google-ads-copy/SKILL.md b/skills/google-ads-copy/SKILL.md
new file mode 100644
index 00000000..fc38fded
--- /dev/null
+++ b/skills/google-ads-copy/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: google-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", "ad variation experiment", or when the user wants to improve click-through rate on existing ads.
+argument-hint: "<ad group name, keyword theme, or 'write new ads'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../google-ads/copy/SKILL.md`](../../google-ads/copy/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../google-ads/copy/`.
diff --git a/skills/google-ads-landing/SKILL.md b/skills/google-ads-landing/SKILL.md
new file mode 100644
index 00000000..79ff87ac
--- /dev/null
+++ b/skills/google-ads-landing/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: google-ads-landing
+description: Score and diagnose Google Ads landing pages. Use when asked to audit a landing page, check landing page quality, diagnose high-CTR but low-conversion-rate ad groups, improve Quality Score's Landing Page Experience component, or compare an ad group's messaging against its landing page. Trigger on "landing page audit", "landing page score", "landing page quality", "why is my conversion rate low", "LPX", "landing page experience", "ad to page match", or when `/google-ads-audit` surfaces a high-CTR / low-CVR ad group.
+argument-hint: "<landing page URL or ad group name>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../google-ads/landing/SKILL.md`](../../google-ads/landing/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../google-ads/landing/`.
diff --git a/skills/google-ads/SKILL.md b/skills/google-ads/SKILL.md
new file mode 100644
index 00000000..a068351d
--- /dev/null
+++ b/skills/google-ads/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: google-ads
+description: Manage Google Ads — performance, keywords, bids, budgets, negatives, campaigns, ads, search terms, QS, location targeting, bulk operations, experiments, asset management, portfolio bidding, offline conversions. Use for any mention of Google Ads, CPA, ROAS, ad spend, or campaign settings.
+argument-hint: "<campaign name, keyword, or 'show performance'>"
+triggers:
+ - google ads
+ - campaigns
+ - keywords
+ - ad spend
+ - CPA
+ - ROAS
+ - search terms
+ - negative keywords
+ - bid
+ - budget
+ - pause campaign
+ - ads performance
+ - location targeting
+ - geo targeting
+ - campaign settings
+ - rename campaign
+ - rename ad group
+ - bulk keywords
+ - check my changes
+ - did my changes work
+ - review my changes
+ - how are my changes doing
+ - change impact
+ - experiment
+ - bidding strategy
+ - performance max
+ - shopping campaign
+ - sitelink
+ - callout
+ - structured snippet
+---
+
+# Canonical NotFair workflow
+
+Read [`../../google-ads/manage/SKILL.md`](../../google-ads/manage/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../google-ads/manage/`.
diff --git a/skills/google-analytics/SKILL.md b/skills/google-analytics/SKILL.md
new file mode 100644
index 00000000..aeaa7fa8
--- /dev/null
+++ b/skills/google-analytics/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: google-analytics
+description: Analyze connected Google Analytics 4 traffic, acquisition, engagement, landing pages, ecommerce, events, and conversions, and safely manage supported GA4 key events or custom dimensions through NotFair MCP. Use for GA4, Google Analytics, traffic or conversion drops, channel attribution, realtime activity, report requests, measurement configuration, or Analytics MCP setup.
+argument-hint: "<property, date range, metric, or GA4 question>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../analytics/google-analytics/SKILL.md`](../../analytics/google-analytics/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../analytics/google-analytics/`.
diff --git a/skills/hreflang-international/SKILL.md b/skills/hreflang-international/SKILL.md
new file mode 100644
index 00000000..98eedccf
--- /dev/null
+++ b/skills/hreflang-international/SKILL.md
@@ -0,0 +1,24 @@
+---
+name: hreflang-international
+argument-hint: "<website URL, e.g. https://example.com>"
+description: >
+ International / multilingual SEO audit focused on hreflang correctness. Detects
+ and diagnoses the most common (and ranking-damaging) hreflang mistakes: missing
+ or broken return tags, wrong language/region codes, missing x-default,
+ self-referencing errors, conflicts between hreflang and canonical, and
+ inconsistent signals across HTML head / HTTP headers / XML sitemap. Also reviews
+ the broader international setup — URL structure (ccTLD vs subdirectory vs
+ subdomain), language targeting, and geo signals. Use this skill whenever the
+ user runs a multi-language or multi-region site and asks about hreflang,
+ international SEO, multilingual SEO, the wrong-language page showing in search,
+ duplicate-content across country versions, or "th/en page ranking in the wrong
+ country". Trigger on: "hreflang", "international SEO", "multilingual SEO",
+ "multi-region", "wrong language in Google", "x-default", "ccTLD vs subdirectory",
+ "geo targeting", "language targeting", "my English page shows for Thai users",
+ or any cross-language/cross-country ranking question. For full-site audits use
+ /seo-analysis; for a single URL use /seo-page.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/hreflang-international/SKILL.md`](../../seo/hreflang-international/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/hreflang-international/`.
diff --git a/skills/image-seo/SKILL.md b/skills/image-seo/SKILL.md
new file mode 100644
index 00000000..f16d34fd
--- /dev/null
+++ b/skills/image-seo/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: image-seo
+argument-hint: "<website URL or page URL, e.g. https://example.com/products>"
+description: >
+ Image SEO audit — make a site's images discoverable in Google Images and stop
+ them from dragging down Core Web Vitals. Audits alt text quality and coverage,
+ descriptive file names, modern formats (WebP/AVIF), dimensions and compression,
+ responsive srcset, lazy-loading, explicit width/height (CLS), image sitemaps,
+ and ImageObject structured data. Use this skill whenever the user asks about
+ image SEO, alt text, Google Images ranking, image optimization for search,
+ image file size hurting page speed, WebP/AVIF, or image structured data.
+ Trigger on: "image SEO", "alt text", "rank in Google Images", "optimize my
+ images for search", "image alt tags", "WebP", "image compression SEO", "image
+ sitemap", "ImageObject schema", or any image-discoverability / image-performance
+ question. For overall page speed use /seo-analysis; for generating new images use
+ the brand image skills.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/image-seo/SKILL.md`](../../seo/image-seo/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/image-seo/`.
diff --git a/skills/keyword-research/SKILL.md b/skills/keyword-research/SKILL.md
new file mode 100644
index 00000000..db882cf6
--- /dev/null
+++ b/skills/keyword-research/SKILL.md
@@ -0,0 +1,17 @@
+---
+name: keyword-research
+argument-hint: "<topic, niche, or seed keyword>"
+description: >
+ Discover, analyze, and prioritize keywords for SEO and GEO content strategies
+ from a seed keyword or niche. Identifies high-value opportunities based on
+ search volume, competition, intent, and business relevance. Generates topic
+ clusters. For building a dated editorial calendar from your own Search
+ Console data, use `content-planner` instead — this skill is seed-driven
+ keyword discovery, not calendar scheduling. Use when asked to "find
+ keywords", "keyword research", "keyword analysis", "search volume", "keyword
+ difficulty", "content ideas from a seed", or any keyword discovery task.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/keyword-research/SKILL.md`](../../seo/keyword-research/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/keyword-research/`.
diff --git a/skills/local-seo/SKILL.md b/skills/local-seo/SKILL.md
new file mode 100644
index 00000000..0653555e
--- /dev/null
+++ b/skills/local-seo/SKILL.md
@@ -0,0 +1,24 @@
+---
+name: local-seo
+argument-hint: "<business name or website URL, e.g. https://example.com or 'Dolly Solutions Bangkok'>"
+description: >
+ Local SEO and Google Business Profile audit — diagnose why a business isn't
+ ranking in the local pack / map results, and produce a fix plan. Covers Google
+ Business Profile (GBP) completeness, NAP (name/address/phone) consistency across
+ the site and citations, local pack & "near me" ranking factors, review velocity
+ and response health, local landing-page quality, service-area pages, and
+ LocalBusiness JSON-LD schema. Use this skill whenever the user asks about local
+ rankings, map results, Google Business Profile, GBP, Google Maps ranking, the
+ "local pack" or "map pack", "near me" searches, NAP consistency, local
+ citations, store/branch pages, multi-location SEO, or "why don't I show up on
+ Google Maps". Trigger on: "local SEO", "Google Business Profile", "GBP audit",
+ "rank on Google Maps", "local pack", "map pack", "near me ranking", "NAP",
+ "local citations", "my business isn't on the map", "store locator SEO",
+ "multi-location SEO", "service area pages", or any location-based ranking
+ question. For full-site (non-local) audits use /seo-analysis; for a single URL
+ use /seo-page.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/local-seo/SKILL.md`](../../seo/local-seo/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/local-seo/`.
diff --git a/skills/meta-ads-audit/SKILL.md b/skills/meta-ads-audit/SKILL.md
new file mode 100644
index 00000000..57a8a5ff
--- /dev/null
+++ b/skills/meta-ads-audit/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: meta-ads-audit
+description: Meta Ads (Facebook + Instagram) account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other Meta ads skills reuse. Trigger on "audit my Meta ads", "audit my Facebook ads", "Meta ads audit", "set up my Meta ads", "onboard Meta", "Meta account overview", "how's my Meta account", "Meta health check", "what should I fix in my Facebook ads", or when the user is new to NotFair Meta and hasn't run an audit before. Also trigger proactively when other Meta ads skills detect that meta business-context.json is missing.
+argument-hint: "<account name or 'audit my Meta ads'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../meta-ads/audit/SKILL.md`](../../meta-ads/audit/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../meta-ads/audit/`.
diff --git a/skills/meta-ads-creative/SKILL.md b/skills/meta-ads-creative/SKILL.md
new file mode 100644
index 00000000..851620b5
--- /dev/null
+++ b/skills/meta-ads-creative/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: meta-ads-creative
+description: Create evidence-based Meta ad creative briefs, copy angles, and testable asset concepts for Facebook and Instagram. Use when asked for Meta ad creative, Facebook ads copy, Instagram ad assets, UGC concepts, creative briefs, new ad concepts, or creative refreshes.
+argument-hint: "<campaign, audience, or 'build a creative slate'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../meta-ads/creative/SKILL.md`](../../meta-ads/creative/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../meta-ads/creative/`.
diff --git a/skills/meta-ads/SKILL.md b/skills/meta-ads/SKILL.md
new file mode 100644
index 00000000..f8c43178
--- /dev/null
+++ b/skills/meta-ads/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: meta-ads
+description: Manage Meta Ads (Facebook + Instagram) — performance, ROAS, CPM, frequency, audience overlap, learning phase, creative fatigue, budgets, ad sets, campaigns, ads. Use for any mention of Meta Ads, Facebook Ads, Instagram Ads, ROAS, CPM, ad spend, or campaign settings on Meta.
+argument-hint: "<campaign / ad set name, or 'show performance'>"
+triggers:
+ - meta ads
+ - facebook ads
+ - instagram ads
+ - meta campaigns
+ - ad sets
+ - ROAS
+ - CPM
+ - link CTR
+ - frequency
+ - creative fatigue
+ - audience overlap
+ - learning phase
+ - learning limited
+ - CBO
+ - ABO
+ - advantage shopping
+ - advantage plus
+ - lookalike
+ - retargeting
+ - prospecting
+ - pause campaign
+ - update budget
+---
+
+# Canonical NotFair workflow
+
+Read [`../../meta-ads/manage/SKILL.md`](../../meta-ads/manage/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../meta-ads/manage/`.
diff --git a/skills/meta-tags-optimizer/SKILL.md b/skills/meta-tags-optimizer/SKILL.md
new file mode 100644
index 00000000..9d1ee9a6
--- /dev/null
+++ b/skills/meta-tags-optimizer/SKILL.md
@@ -0,0 +1,15 @@
+---
+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
+ character counting and SERP preview. Use when asked to "optimize title tag",
+ "write meta description", "improve CTR", "Open Graph tags", "fix my meta
+ tags", "social media preview", "my click rate is low", "title optimization",
+ or any meta tag task.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/meta-tags-optimizer/SKILL.md`](../../seo/meta-tags-optimizer/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/meta-tags-optimizer/`.
diff --git a/skills/paid-ads-amazon/SKILL.md b/skills/paid-ads-amazon/SKILL.md
new file mode 100644
index 00000000..e46b7d76
--- /dev/null
+++ b/skills/paid-ads-amazon/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-amazon
+description: Plan and review Amazon Ads with margin-aware ACoS, product, and search-term guardrails. Use for Amazon advertising, Sponsored Products, Sponsored Brands, Sponsored Display, ASIN targeting, Amazon ACoS, or Amazon Ads performance exports.
+argument-hint: "<ASIN, product line, target ACoS, or Amazon export>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-amazon/SKILL.md`](../../paid-ads/paid-ads-amazon/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-amazon/`.
diff --git a/skills/paid-ads-chatgpt/SKILL.md b/skills/paid-ads-chatgpt/SKILL.md
new file mode 100644
index 00000000..852a5036
--- /dev/null
+++ b/skills/paid-ads-chatgpt/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-chatgpt
+description: Plan and review ChatGPT Ads experiments without assuming ad inventory, account access, or platform capabilities. Use for ChatGPT advertising, OpenAI ads, conversational ad concepts, ChatGPT campaign plans, or performance reviews from a verified export.
+argument-hint: "<objective, audience, or verified ChatGPT Ads export>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-chatgpt/SKILL.md`](../../paid-ads/paid-ads-chatgpt/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-chatgpt/`.
diff --git a/skills/paid-ads-creative/SKILL.md b/skills/paid-ads-creative/SKILL.md
new file mode 100644
index 00000000..40b4fa09
--- /dev/null
+++ b/skills/paid-ads-creative/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-creative
+description: Create grounded paid-media creative concepts, copy angles, refresh hypotheses, and measurable test briefs across advertising platforms. Use for ad copy, creative briefs, UGC concepts, headlines, creative fatigue, asset ideas, or a creative refresh.
+argument-hint: "<platform, audience, or campaign>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-creative/SKILL.md`](../../paid-ads/paid-ads-creative/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-creative/`.
diff --git a/skills/paid-ads-guide/SKILL.md b/skills/paid-ads-guide/SKILL.md
new file mode 100644
index 00000000..b0759a5d
--- /dev/null
+++ b/skills/paid-ads-guide/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-guide
+description: Explain NotFair's paid-ads skills, installation, platform boundaries, account connections, and current product capabilities. Use for questions about how NotFair works, what it supports, how to install or connect it, plans or limits, or paid-media troubleshooting that is not an account-performance request.
+argument-hint: "<installation, capability, connection, or product question>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-guide/SKILL.md`](../../paid-ads/paid-ads-guide/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-guide/`.
diff --git a/skills/paid-ads-integrations/SKILL.md b/skills/paid-ads-integrations/SKILL.md
new file mode 100644
index 00000000..ba3894c4
--- /dev/null
+++ b/skills/paid-ads-integrations/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-integrations
+description: Discover, connect, and verify NotFair paid-ad integrations and their actual capabilities. Use when asked to connect an ad account, configure an ads MCP, check available tools, troubleshoot access, or determine whether NotFair can read or change a platform.
+argument-hint: "<platform or connection issue>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-integrations/SKILL.md`](../../paid-ads/paid-ads-integrations/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-integrations/`.
diff --git a/skills/paid-ads-launch/SKILL.md b/skills/paid-ads-launch/SKILL.md
new file mode 100644
index 00000000..cf276b67
--- /dev/null
+++ b/skills/paid-ads-launch/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-launch
+description: Plan and prepare a new paid-media campaign or cross-channel test before it can spend. Use when asked to create, launch, start, set up, or allocate budget to an advertising campaign on any supported platform.
+argument-hint: "<business goal, budget, and target platform>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-launch/SKILL.md`](../../paid-ads/paid-ads-launch/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-launch/`.
diff --git a/skills/paid-ads-linkedin/SKILL.md b/skills/paid-ads-linkedin/SKILL.md
new file mode 100644
index 00000000..2a2255ac
--- /dev/null
+++ b/skills/paid-ads-linkedin/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-linkedin
+description: Audit, diagnose, plan, and safely operate connected LinkedIn Ads accounts through the NotFair MCP, with an export-based fallback. Use for LinkedIn advertising, sponsored content, lead-generation forms, job-title or company targeting, campaign groups, creatives, conversions, lead quality, budgets, bids, or approved LinkedIn campaign changes.
+argument-hint: "<B2B goal, audience, account, or date range>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-linkedin/SKILL.md`](../../paid-ads/paid-ads-linkedin/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-linkedin/`.
diff --git a/skills/paid-ads-optimize/SKILL.md b/skills/paid-ads-optimize/SKILL.md
new file mode 100644
index 00000000..c1206bc2
--- /dev/null
+++ b/skills/paid-ads-optimize/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-optimize
+description: Diagnose wasted paid-ad spend, pacing, and allocation, then propose safe evidence-backed optimizations. Use for waste, negatives, budgets, bid changes, poor CPA or ROAS, underpacing, overspend, or scaling decisions.
+argument-hint: "<campaign, target CPA/ROAS, or 'find waste'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-optimize/SKILL.md`](../../paid-ads/paid-ads-optimize/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-optimize/`.
diff --git a/skills/paid-ads-review/SKILL.md b/skills/paid-ads-review/SKILL.md
new file mode 100644
index 00000000..68de7988
--- /dev/null
+++ b/skills/paid-ads-review/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-review
+description: Produce a read-only, evidence-based paid-media performance review across connected platforms or supplied exports. Use for weekly or monthly reports, scorecards, performance, CPA, ROAS, CTR, spend trends, pacing, or conversion-tracking health.
+argument-hint: "<date range, platform, or 'weekly review'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-review/SKILL.md`](../../paid-ads/paid-ads-review/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-review/`.
diff --git a/skills/paid-ads-setup/SKILL.md b/skills/paid-ads-setup/SKILL.md
new file mode 100644
index 00000000..434cbf94
--- /dev/null
+++ b/skills/paid-ads-setup/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-setup
+description: Connect NotFair paid-ad accounts and establish reusable campaign context. Use when setting up paid media in a new workspace, connecting Google, Meta, X, or LinkedIn Ads, refreshing brand context, or preparing an agent to work on ads safely.
+argument-hint: "<connect accounts, workspace, or brand>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-setup/SKILL.md`](../../paid-ads/paid-ads-setup/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-setup/`.
diff --git a/skills/paid-ads-tiktok/SKILL.md b/skills/paid-ads-tiktok/SKILL.md
new file mode 100644
index 00000000..6a049a4e
--- /dev/null
+++ b/skills/paid-ads-tiktok/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-tiktok
+description: Plan and review TikTok Ads creative experiments with measurement, rights, and conversion guardrails. Use for TikTok advertising, Spark Ads, short-form video ads, creator briefs, TikTok campaign setup, or TikTok performance exports.
+argument-hint: "<goal, product, creator asset, or TikTok export>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-tiktok/SKILL.md`](../../paid-ads/paid-ads-tiktok/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-tiktok/`.
diff --git a/skills/paid-ads-x/SKILL.md b/skills/paid-ads-x/SKILL.md
new file mode 100644
index 00000000..03e39226
--- /dev/null
+++ b/skills/paid-ads-x/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads-x
+description: Audit, diagnose, and safely operate connected X Ads (Twitter Ads) accounts through the NotFair MCP. Use for X Ads performance, campaign or line-item analysis, spend, conversions, targeting, promoted posts, audiences, budgets, bids, creative, campaign setup, or approved X Ads changes.
+argument-hint: "<account, campaign, date range, or X Ads goal>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads-x/SKILL.md`](../../paid-ads/paid-ads-x/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads-x/`.
diff --git a/skills/paid-ads/SKILL.md b/skills/paid-ads/SKILL.md
new file mode 100644
index 00000000..0e38d48d
--- /dev/null
+++ b/skills/paid-ads/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: paid-ads
+description: Coordinate safe, evidence-based paid-media work across Google Ads, Meta Ads, X Ads, LinkedIn Ads, TikTok, Amazon, and ChatGPT Ads. Use for broad ads questions, multi-channel strategy, budgets, CPA or ROAS, campaign requests, spend, ad performance, or when routing to the right NotFair paid-ads skill.
+argument-hint: "<goal, platform, or 'review my ads'>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../paid-ads/paid-ads/SKILL.md`](../../paid-ads/paid-ads/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../paid-ads/paid-ads/`.
diff --git a/skills/programmatic-seo/SKILL.md b/skills/programmatic-seo/SKILL.md
new file mode 100644
index 00000000..bb84dfb3
--- /dev/null
+++ b/skills/programmatic-seo/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: programmatic-seo
+argument-hint: "<site URL + the templated page pattern, e.g. https://example.com/[city]-[service]>"
+description: >
+ Programmatic SEO planning and audit — building or evaluating large sets of
+ template-generated pages that target long-tail query patterns at scale (e.g.
+ "[service] in [city]", "[product] vs [product]", "[tool] for [use-case]").
+ Covers data-source and template design, the thin/duplicate-content and doorway-
+ page risks that get programmatic pages deindexed, uniqueness and value
+ thresholds per page, internal linking and hub structure, indexation management
+ (which pages to publish vs. noindex), and scaling without a quality manual
+ action. Use this skill whenever the user wants to generate many pages from a
+ template/dataset, do programmatic SEO, build location/comparison/use-case pages
+ at scale, or asks why their generated pages aren't indexing. Trigger on:
+ "programmatic SEO", "pSEO", "generate pages at scale", "templated pages",
+ "location pages at scale", "comparison pages", "[city] pages", "my generated
+ pages aren't indexed", "doorway pages", "scale content". For one-off content use
+ /content-writer; for keyword discovery use /keyword-research.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/programmatic-seo/SKILL.md`](../../seo/programmatic-seo/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/programmatic-seo/`.
diff --git a/skills/schema-markup-generator/SKILL.md b/skills/schema-markup-generator/SKILL.md
new file mode 100644
index 00000000..eba3cc5b
--- /dev/null
+++ b/skills/schema-markup-generator/SKILL.md
@@ -0,0 +1,15 @@
+---
+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.
+ Validates against Google requirements and provides implementation guidance.
+ Use when asked to "add schema markup", "generate structured data", "JSON-LD",
+ "rich snippets", "FAQ schema", "product markup", "add structured data to my
+ page", "how to get rich snippets", or any structured data task.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/schema-markup-generator/SKILL.md`](../../seo/schema-markup-generator/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/schema-markup-generator/`.
diff --git a/skills/search-console/SKILL.md b/skills/search-console/SKILL.md
new file mode 100644
index 00000000..4daae909
--- /dev/null
+++ b/skills/search-console/SKILL.md
@@ -0,0 +1,9 @@
+---
+name: search-console
+description: Query and operate connected Google Search Console properties through NotFair MCP. Use for live GSC query or page performance, clicks, impressions, CTR, position, traffic changes, indexing status, URL inspection, sitemap reads or approved sitemap submission/removal, and Search Console MCP setup. Route full-site SEO audits to seo-analysis.
+argument-hint: "<property, URL, query, date range, or sitemap>"
+---
+
+# Canonical NotFair workflow
+
+Read [`../../analytics/search-console/SKILL.md`](../../analytics/search-console/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../analytics/search-console/`.
diff --git a/skills/seo-analysis/SKILL.md b/skills/seo-analysis/SKILL.md
new file mode 100644
index 00000000..57b0e09e
--- /dev/null
+++ b/skills/seo-analysis/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: seo-analysis
+argument-hint: "<URL to audit, e.g. https://example.com>"
+description: >
+ Full SEO audit: Google Search Console data + URL Inspection API + PageSpeed
+ Insights API + technical crawl + keyword research + metadata audit + schema
+ markup audit + search intent analysis + Core Web Vitals monitoring. Feeds real
+ GSC data and PageSpeed metrics into AI to surface quick wins, diagnose traffic
+ drops, find content gaps, identify metadata mismatches, detect schema gaps,
+ monitor page performance, and produce an actionable 30-day plan. Use this skill
+ whenever the user asks about SEO, search rankings, organic traffic, Google
+ Search Console, keyword performance, traffic drops, content gaps, search
+ visibility, technical SEO, meta tags, schema markup, structured data, URL
+ indexing, keyword research, indexing issues, page speed, performance, Core Web
+ Vitals, LCP, INP, CLS, or Lighthouse scores. Also trigger on: "why is my
+ traffic down", "what keywords am I ranking for", "improve my rankings", "check
+ my search console", "SEO audit", "analyze my SEO", "technical SEO", "meta
+ tags", "indexing issues", "crawl errors", "content strategy", "keyword
+ cannibalization", "search intent", "schema markup", "structured data", "URL
+ inspection", "page speed", "performance score", "core web vitals", "lighthouse",
+ or any organic search question. If in doubt, trigger. This skill handles
+ everything from quick GSC checks to deep technical audits with performance
+ monitoring.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/seo-analysis/SKILL.md`](../../seo/seo-analysis/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/seo-analysis/`.
diff --git a/skills/seo-drift/SKILL.md b/skills/seo-drift/SKILL.md
new file mode 100644
index 00000000..50b020a6
--- /dev/null
+++ b/skills/seo-drift/SKILL.md
@@ -0,0 +1,22 @@
+---
+name: seo-drift
+argument-hint: "<site URL — optionally 'baseline' to snapshot or 'compare' to diff>"
+description: >
+ SEO drift monitoring — snapshot a site's SEO state and detect regressions over
+ time. Captures a baseline (rankings/positions, indexed page count, titles & meta
+ descriptions, canonical/robots directives, schema presence, key on-page
+ elements) and on later runs diffs against it to surface what changed: ranking
+ drops, pages that fell out of the index, titles/metas that were accidentally
+ overwritten (a CMS/redeploy classic), canonicals or noindex flipped, schema that
+ disappeared. Use this skill when the user wants to monitor SEO over time, catch
+ regressions after a site change / migration / redeploy, set a baseline, diff
+ against a previous state, or asks "what changed on my site's SEO" or "did my
+ redesign break SEO". Trigger on: "SEO drift", "SEO monitoring", "track SEO over
+ time", "did my site change break SEO", "after migration SEO", "SEO regression",
+ "baseline my SEO", "compare SEO to last month", "my titles changed", "pages fell
+ out of the index". For a one-time full audit use /seo-analysis.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/seo-drift/SKILL.md`](../../seo/seo-drift/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/seo-drift/`.
diff --git a/skills/seo-page/SKILL.md b/skills/seo-page/SKILL.md
new file mode 100644
index 00000000..e6510ab4
--- /dev/null
+++ b/skills/seo-page/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: seo-page
+argument-hint: "<URL of the page to analyze, e.g. https://example.com/blog/my-post>"
+description: >
+ Single-page SEO audit: deep content quality evaluation using Google's E-E-A-T
+ framework, Helpful Content guidelines, on-page SEO factors, search intent
+ alignment, technical signals, and readability analysis. Fetches GSC performance
+ data for that specific page, crawls the live HTML, evaluates metadata, schema
+ markup, internal linking, content depth, and produces a scored report with
+ actionable fixes. Use this skill whenever the user wants to analyze a specific
+ page or URL — not the whole site. Trigger on: "analyze this page", "audit this
+ URL", "how is this page doing", "evaluate my blog post", "check this landing
+ page", "page SEO", "content quality check", "is this page good enough",
+ "review this page's SEO", "what's wrong with this page", "how can I improve
+ this page", "page analysis", "single page audit", "content audit for [URL]",
+ or any request that names a specific URL/page for SEO evaluation. If the user
+ provides a specific URL (not just a domain), this is likely the right skill —
+ use /seo-analysis for full-site audits instead.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/seo-page/SKILL.md`](../../seo/seo-page/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/seo-page/`.
diff --git a/skills/setup-cms/SKILL.md b/skills/setup-cms/SKILL.md
new file mode 100644
index 00000000..20dee7e2
--- /dev/null
+++ b/skills/setup-cms/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: setup-cms
+argument-hint: "<CMS name: wordpress, strapi, contentful, or ghost>"
+description: >
+ Connect a CMS to notfair SEO tools. Guides users through configuring
+ WordPress, Strapi, Contentful, or Ghost — tests the connection, and writes
+ credentials to .env.local. Once set up, seo-analysis automatically cross-
+ references CMS content against Google Search Console data. Use whenever the
+ user says "connect my CMS", "set up WordPress", "configure Strapi", "add
+ Contentful", "connect Ghost", or "CMS setup". Also trigger if the user asks
+ why no CMS data appears in a seo-analysis report.
+allowed-tools:
+ - Bash
+ - Read
+ - Write
+ - AskUserQuestion
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/setup-cms/SKILL.md`](../../seo/setup-cms/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/setup-cms/`.
diff --git a/skills/sitemap-audit/SKILL.md b/skills/sitemap-audit/SKILL.md
new file mode 100644
index 00000000..637ecb3d
--- /dev/null
+++ b/skills/sitemap-audit/SKILL.md
@@ -0,0 +1,22 @@
+---
+name: sitemap-audit
+argument-hint: "<website URL or sitemap URL, e.g. https://example.com or https://example.com/sitemap.xml>"
+description: >
+ XML sitemap audit — find and fix the sitemap problems that quietly waste crawl
+ budget and slow indexing. Discovers the sitemap (robots.txt, /sitemap.xml,
+ sitemap index), validates structure and size limits, and cross-checks the URLs
+ it lists against reality: non-200 / redirected / noindex / canonicalized-away
+ URLs that shouldn't be in a sitemap, plus indexable pages that are missing from
+ it. Reviews lastmod accuracy, sitemap-index organization, and robots.txt
+ reference. Use this skill whenever the user asks about sitemaps, sitemap errors
+ in Search Console, "sitemap couldn't fetch / has errors", crawl budget, pages
+ not getting indexed, or whether their sitemap is clean. Trigger on: "sitemap",
+ "sitemap.xml", "XML sitemap", "sitemap errors", "sitemap audit", "couldn't
+ fetch sitemap", "crawl budget", "pages not indexed sitemap", "sitemap index",
+ "lastmod", "robots.txt sitemap", or any sitemap/crawl-coverage question. For a
+ full-site SEO audit use /seo-analysis; for broken links use /broken-link-checker.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/sitemap-audit/SKILL.md`](../../seo/sitemap-audit/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/sitemap-audit/`.
diff --git a/skills/sxo/SKILL.md b/skills/sxo/SKILL.md
new file mode 100644
index 00000000..238c6972
--- /dev/null
+++ b/skills/sxo/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: sxo
+argument-hint: "<page or site URL, e.g. https://example.com/landing>"
+description: >
+ Search Experience Optimization (SXO) — the bridge between SEO and UX/CRO. Audits
+ the full journey from the SERP click to the on-page goal: SERP click-through
+ factors (title/meta/rich results that win the click), then post-click experience
+ signals that keep users and drive conversions — above-the-fold relevance and
+ intent match, page speed / Core Web Vitals as experience, readability and
+ scannability, clear CTAs, mobile usability, and the things that cause pogo-
+ sticking back to Google. Use this skill when the user has decent rankings but
+ poor CTR or poor on-page conversion, wants to improve dwell time / engagement,
+ reduce bounce/pogo-sticking, or align a page's experience with search intent.
+ Trigger on: "SXO", "search experience optimization", "good rankings but low
+ CTR", "high bounce rate from search", "pogo-sticking", "improve dwell time",
+ "SEO and conversion", "ranking but not converting", "engagement signals", "make
+ this page convert search traffic". For pure landing-page conversion in ads use
+ /google-ads-landing; for content quality use /seo-page.
+---
+
+# Canonical NotFair workflow
+
+Read [`../../seo/sxo/SKILL.md`](../../seo/sxo/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../seo/sxo/`.
diff --git a/skills/upgrade/SKILL.md b/skills/upgrade/SKILL.md
new file mode 100644
index 00000000..1abd1ae6
--- /dev/null
+++ b/skills/upgrade/SKILL.md
@@ -0,0 +1,17 @@
+---
+name: upgrade
+argument-hint: "<or just run '/notfair:upgrade'>"
+description: >
+ Upgrade the NotFair plugin to the latest version. Updates the marketplace repo,
+ installs the new version to the plugin cache, and updates installed_plugins.json.
+ Use when asked to "upgrade notfair", "update notfair", or "get latest version".
+ Also handles inline upgrade prompts when a skill detects UPGRADE_AVAILABLE at startup.
+allowed-tools:
+ - Bash
+ - Read
+ - AskUserQuestion
+---
+
+# Canonical NotFair workflow
+
+Read [`../../notfair-upgrade-skill/SKILL.md`](../../notfair-upgrade-skill/SKILL.md) completely, then follow it as the active workflow. Resolve every relative reference from that file against `../../notfair-upgrade-skill/`.
diff --git a/test/install.test.sh b/test/install.test.sh
index f883f9a7..714b13e4 100755
--- a/test/install.test.sh
+++ b/test/install.test.sh
@@ -220,9 +220,22 @@ assert_file "$REPO_ROOT/bin/notfair-change-watch" "bin/notfair-change-watch exis
&& pass "legacy toprank-upgrade-skill/ removed" \
|| fail "toprank-upgrade-skill/ still exists (should have been git-mv'd to notfair-upgrade-skill/)"
-[ ! -d "$REPO_ROOT/skills" ] \
- && pass "skills/ flat directory removed" \
- || fail "skills/ directory still exists (skills should be in google-ads/, seo/, meta-ads/, notfair-upgrade-skill/, gemini/)"
+CODEX_SKILL_DIR_COUNT=$(find "$REPO_ROOT/skills" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d '[:space:]')
+[ "$CODEX_SKILL_DIR_COUNT" -eq "${#SKILL_ENTRIES[@]}" ] \
+ && pass "skills/ exposes all ${#SKILL_ENTRIES[@]} canonical skills to Codex as portable wrappers" \
+ || fail "skills/ has $CODEX_SKILL_DIR_COUNT directories, expected ${#SKILL_ENTRIES[@]}"
+
+[ -z "$(find "$REPO_ROOT/skills" -mindepth 1 -maxdepth 1 -type l -print -quit)" ] \
+ && pass "skills/ contains no symlinks that Codex packaging could drop" \
+ || fail "skills/ contains symlinks that Codex packaging could drop"
+
+for entry in "${SKILL_ENTRIES[@]}"; do
+ skill=$(skill_name "$entry")
+ path=$(skill_path "$entry")
+ wrapper="$REPO_ROOT/skills/$skill/SKILL.md"
+ assert_file "$wrapper" "Codex skill wrapper: $skill"
+ assert_contains "$wrapper" "../../$path/SKILL.md" "Codex skill wrapper forwards $skill to $path"
+done
[ ! -d "$REPO_ROOT/.agents" ] \
&& pass ".agents/ directory removed" \
@@ -260,17 +273,18 @@ done
echo ""
echo "=== 5. MCP server config ==="
-assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair-GoogleAds\"" ".mcp.json registers the NotFair-GoogleAds server"
+assert_file "$REPO_ROOT/.codex-plugin/plugin.json" "Codex plugin manifest exists"
+assert_contains "$REPO_ROOT/.codex-plugin/plugin.json" '"mcpServers": "./.mcp.json"' "Codex manifest loads the MCP config"
+assert_contains "$REPO_ROOT/.codex-plugin/plugin.json" '"skills": "./skills/"' "Codex manifest loads the canonical skill index"
+assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair\"" ".mcp.json registers the universal NotFair server"
assert_contains "$REPO_ROOT/.mcp.json" "\"type\": \"http\"" ".mcp.json uses native HTTP transport (no mcp-remote bridge)"
-assert_contains "$REPO_ROOT/.mcp.json" "notfair.co/api/mcp/google_ads" ".mcp.json points at NotFair-GoogleAds MCP endpoint"
-assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair-XAds\"" ".mcp.json registers the NotFair-XAds server"
-assert_contains "$REPO_ROOT/.mcp.json" "notfair.co/api/mcp/x_ads" ".mcp.json points at the X Ads MCP endpoint"
-assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair-LinkedInAds\"" ".mcp.json registers the NotFair-LinkedInAds server"
-assert_contains "$REPO_ROOT/.mcp.json" "notfair.co/api/mcp/linkedin_ads" ".mcp.json points at the LinkedIn Ads MCP endpoint"
-assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair-GoogleSearchConsole\"" ".mcp.json registers the canonical Search Console server"
-assert_contains "$REPO_ROOT/.mcp.json" "notfair.co/api/mcp/google_search_console" ".mcp.json points at the Search Console MCP endpoint"
-assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair-GoogleAnalytics\"" ".mcp.json registers the NotFair-GoogleAnalytics server"
-assert_contains "$REPO_ROOT/.mcp.json" "notfair.co/api/mcp/google_analytics" ".mcp.json points at the Google Analytics MCP endpoint"
+assert_contains "$REPO_ROOT/.mcp.json" "https://notfair.co/api/mcp/notfair_ads" ".mcp.json points at the canonical universal NotFair MCP endpoint"
+assert_not_contains "$REPO_ROOT/.mcp.json" "https://www.notfair.co" ".mcp.json origin matches the OAuth issuer exactly"
+assert_not_contains "$REPO_ROOT/.mcp.json" "api/mcp/google_ads" ".mcp.json does not auto-register the dedicated Google Ads endpoint"
+assert_not_contains "$REPO_ROOT/.mcp.json" "api/mcp/meta_ads" ".mcp.json does not auto-register the dedicated Meta Ads endpoint"
+assert_contains "$REPO_ROOT/README.md" "codex mcp login NotFair" "README Codex install starts the OAuth flow"
+assert_contains "$REPO_ROOT/INSTALL_FOR_AGENTS.md" "codex mcp login NotFair" "agent installer starts the Codex OAuth flow"
+assert_contains "$REPO_ROOT/INSTALL_FOR_AGENTS.md" "codex plugin marketplace upgrade nowork-studio" "agent installer handles an existing marketplace"
# ─── Test 6: Connectors section in README ─────────────────────
diff --git a/test/test_mcp_skill_e2e.py b/test/test_mcp_skill_e2e.py
index bea1d3ed..cdef506b 100644
--- a/test/test_mcp_skill_e2e.py
+++ b/test/test_mcp_skill_e2e.py
@@ -9,6 +9,7 @@ import json
import os
import re
import urllib.error
+import urllib.parse
import urllib.request
from pathlib import Path
@@ -17,56 +18,73 @@ import pytest
ROOT = Path(__file__).parent.parent
-SURFACES = {
- "NotFair-XAds": {
- "endpoint": "https://notfair.co/api/mcp/x_ads",
- "skill": "paid-ads/paid-ads-x",
- "placeholder": "~~x-ads",
- },
- "NotFair-LinkedInAds": {
- "endpoint": "https://notfair.co/api/mcp/linkedin_ads",
- "skill": "paid-ads/paid-ads-linkedin",
- "placeholder": "~~linkedin-ads",
- },
- "NotFair-GoogleSearchConsole": {
- "endpoint": "https://notfair.co/api/mcp/google_search_console",
- "skill": "analytics/search-console",
- "placeholder": "~~search-console",
- },
- "NotFair-GoogleAnalytics": {
- "endpoint": "https://notfair.co/api/mcp/google_analytics",
- "skill": "analytics/google-analytics",
- "placeholder": "~~google-analytics",
- },
+UNIVERSAL_SERVER = "NotFair"
+UNIVERSAL_ENDPOINT = "https://notfair.co/api/mcp/notfair_ads"
+
+PLATFORM_SKILLS = {
+ "paid-ads/paid-ads-x": ("~~x-ads", "x_ads_"),
+ "paid-ads/paid-ads-linkedin": ("~~linkedin-ads", "linkedin_ads_"),
+ "analytics/search-console": ("~~search-console", "search_console_"),
+ "analytics/google-analytics": ("~~google-analytics", "google_analytics_"),
+}
+
+UNIVERSAL_PREFLIGHTS = {
+ "google-ads/shared/preamble.md": "google_ads_listConnectedAccounts",
+ "meta-ads/shared/preamble.md": "meta_ads_listAdAccounts",
}
-def test_mcp_surfaces_are_registered_to_corresponding_skills():
+def test_universal_mcp_is_the_only_registered_server_and_skills_use_platform_prefixes():
config = json.loads((ROOT / ".mcp.json").read_text())
plugin = json.loads((ROOT / ".claude-plugin/plugin.json").read_text())
+ codex_plugin = json.loads((ROOT / ".codex-plugin/plugin.json").read_text())
servers = config["mcpServers"]
- for server_name, expected in SURFACES.items():
- assert servers[server_name] == {
- "type": "http",
- "url": expected["endpoint"],
- }
-
- skill_path = ROOT / expected["skill"] / "SKILL.md"
+ assert servers == {
+ UNIVERSAL_SERVER: {"type": "http", "url": UNIVERSAL_ENDPOINT}
+ }
+ assert codex_plugin["name"] == "notfair"
+ assert codex_plugin["skills"] == "./skills/"
+ assert codex_plugin["mcpServers"] == "./.mcp.json"
+ assert codex_plugin["version"] == plugin["version"]
+
+ codex_wrappers = {path.name: path for path in (ROOT / "skills").iterdir()}
+ assert len(codex_wrappers) == len(plugin["skills"])
+ for skill in plugin["skills"]:
+ canonical = (ROOT / skill).resolve()
+ canonical_text = (canonical / "SKILL.md").read_text()
+ skill_name = re.search(r"^name:\s*(.+)$", canonical_text, re.MULTILINE)
+ assert skill_name, skill
+ wrapper = codex_wrappers[skill_name.group(1).strip()]
+ assert wrapper.is_dir() and not wrapper.is_symlink()
+ wrapper_text = (wrapper / "SKILL.md").read_text()
+ assert wrapper_text.split("---\n", 2)[1] == canonical_text.split("---\n", 2)[1]
+ canonical_rel = canonical.relative_to(ROOT).as_posix()
+ assert f"../../{canonical_rel}/SKILL.md" in wrapper_text
+
+ for skill, (placeholder, platform_prefix) in PLATFORM_SKILLS.items():
+ skill_path = ROOT / skill / "SKILL.md"
assert skill_path.is_file()
skill_text = skill_path.read_text()
- assert expected["endpoint"] in skill_text
- assert expected["placeholder"] in skill_text
- assert f'./{expected["skill"]}' in plugin["skills"]
+ assert placeholder in skill_text
+ assert platform_prefix in skill_text
+ assert f"./{skill}" in plugin["skills"]
+
+ for preamble, gated_account_tool in UNIVERSAL_PREFLIGHTS.items():
+ preamble_text = (ROOT / preamble).read_text()
+ preflight = "call `listConnectedPlatforms` **before**"
+ disconnected_stop = f"do not call `{gated_account_tool}`"
+ assert preflight in preamble_text
+ assert disconnected_stop in preamble_text
+ assert preamble_text.index(preflight) < preamble_text.index(disconnected_stop)
@pytest.mark.skipif(
os.environ.get("LIVE_MCP_E2E") != "1",
reason="Set LIVE_MCP_E2E=1 to verify production OAuth discovery",
)
[email protected]("server_name", SURFACES)
-def test_live_mcp_oauth_discovery_round_trip(server_name):
- endpoint = SURFACES[server_name]["endpoint"]
+def test_live_mcp_oauth_discovery_round_trip():
+ endpoint = UNIVERSAL_ENDPOINT
request = urllib.request.Request(
endpoint,
headers={"Accept": "application/json, text/event-stream"},
@@ -90,5 +108,17 @@ def test_live_mcp_oauth_discovery_round_trip(server_name):
metadata = json.load(metadata_response)
assert metadata["resource"] == endpoint
- assert "https://notfair.co" in metadata["authorization_servers"]
+ assert metadata["authorization_servers"] == ["https://notfair.co"]
assert metadata["resource_name"].startswith("NotFair ")
+
+ authorization_server = metadata["authorization_servers"][0]
+ authorization_metadata_url = (
+ f"{authorization_server}/.well-known/oauth-authorization-server"
+ )
+ with urllib.request.urlopen(authorization_metadata_url, timeout=20) as response:
+ authorization_metadata = json.load(response)
+
+ assert authorization_metadata["issuer"] == authorization_server
+ assert urllib.parse.urlparse(endpoint).netloc == urllib.parse.urlparse(
+ authorization_metadata["issuer"]
+ ).netloc