Skip to content

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

feat: add multi-platform MCP skills

Yuting Zhong0906da31ad67
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 52e1eb61..94fd1f0b 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -4,15 +4,15 @@
"name": "nowork-studio"
},
"metadata": {
- "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.",
- "version": "0.25.11"
+ "description": "The official ads, analytics, SEO, and GEO plugin from NotFair.",
+ "version": "0.26.0"
},
"plugins": [
{
"name": "notfair",
"source": "./",
- "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",
- "version": "0.25.11",
+ "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",
"author": {
"name": "NotFair",
"url": "https://notfair.co"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 80b8abc8..3c95e0e9 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "notfair",
- "version": "0.25.11",
- "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.",
+ "version": "0.26.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",
"url": "https://notfair.co"
@@ -15,6 +15,7 @@
"./paid-ads/paid-ads-review",
"./paid-ads/paid-ads-optimize",
"./paid-ads/paid-ads-creative",
+ "./paid-ads/paid-ads-x",
"./paid-ads/paid-ads-linkedin",
"./paid-ads/paid-ads-tiktok",
"./paid-ads/paid-ads-amazon",
@@ -27,6 +28,8 @@
"./meta-ads/manage",
"./meta-ads/audit",
"./meta-ads/creative",
+ "./analytics/google-analytics",
+ "./analytics/search-console",
"./seo/seo-analysis",
"./seo/content-writer",
"./seo/content-planner",
diff --git a/.mcp.json b/.mcp.json
index 810ad3ed..40ec7fde 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -8,9 +8,21 @@
"type": "http",
"url": "https://notfair.co/api/mcp/meta_ads"
},
- "NotFair-SearchConsole": {
+ "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"
}
}
}
diff --git a/AGENTS.md b/AGENTS.md
index 5279d6a8..539f07ae 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@ If you are an agent and a user mentions Google Ads, Meta Ads, SEO, GEO, or anyth
2. **Read the named skill's `SKILL.md`** from the path shown.
3. **Follow the procedure** in that SKILL.md exactly.
-Skills under `seo/`, `paid-ads/`, `google-ads/`, `meta-ads/`, `gemini/`, and `notfair-upgrade-skill/` are **host-agnostic** — they work the same on every supported agent host.
+Skills under `seo/`, `paid-ads/`, `google-ads/`, `meta-ads/`, `analytics/`, `gemini/`, and `notfair-upgrade-skill/` are **host-agnostic** — they work the same on every supported agent host.
---
@@ -53,11 +53,19 @@ Skills under `seo/`, `paid-ads/`, `google-ads/`, `meta-ads/`, `gemini/`, and `no
| Weekly/monthly performance report, scorecard, pacing, or tracking health | `paid-ads-review` | `paid-ads/paid-ads-review/SKILL.md` |
| Wasted spend, budget allocation, overspend, or safe optimization proposal | `paid-ads-optimize` | `paid-ads/paid-ads-optimize/SKILL.md` |
| Cross-channel copy, creative concepts, fatigue diagnosis, or test briefs | `paid-ads-creative` | `paid-ads/paid-ads-creative/SKILL.md` |
-| LinkedIn Ads plan or export-based review | `paid-ads-linkedin` | `paid-ads/paid-ads-linkedin/SKILL.md` |
+| X Ads performance, campaigns, line items, targeting, creative, or writes | `paid-ads-x` | `paid-ads/paid-ads-x/SKILL.md` |
+| LinkedIn Ads performance, campaigns, targeting, leads, creative, or writes | `paid-ads-linkedin` | `paid-ads/paid-ads-linkedin/SKILL.md` |
| TikTok Ads plan, creator brief, or export-based review | `paid-ads-tiktok` | `paid-ads/paid-ads-tiktok/SKILL.md` |
| Amazon Ads plan, ACoS review, ASIN targeting, or export-based review | `paid-ads-amazon` | `paid-ads/paid-ads-amazon/SKILL.md` |
| ChatGPT Ads experiment plan or verified-export review | `paid-ads-chatgpt` | `paid-ads/paid-ads-chatgpt/SKILL.md` |
+## Analytics
+
+| Intent | Skill | Path |
+|---|---|---|
+| GA4 traffic, acquisition, engagement, conversions, realtime, or measurement configuration | `google-analytics` | `analytics/google-analytics/SKILL.md` |
+| Live Search Console queries/pages, traffic changes, URL inspection, or sitemaps | `search-console` | `analytics/search-console/SKILL.md` |
+
## Google Ads
| Intent | Skill | Path |
@@ -90,12 +98,15 @@ Skills under `seo/`, `paid-ads/`, `google-ads/`, `meta-ads/`, `gemini/`, and `no
## External dependencies
-- **Google Search Console** — required for all SEO skills that read live data.
+- **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.
- **Google Gemini API key** — required for `gemini`.
-LinkedIn, 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.
+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.
Skills check for missing credentials at startup and walk the user through setup. Do not invent credentials or skip skills silently — surface the gap.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16b52350..cbbf18dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
### Added
+- **X Ads, LinkedIn Ads, GA4, and Search Console MCP skills (v0.26.0).** Added a live X Ads operator plus dedicated Google Analytics and Search Console workflows, and upgraded the existing LinkedIn skill from export-first planning to live read/write operation. Registered the four sibling-server endpoints in `.mcp.json`, expanded cross-channel routing and approval guardrails, added reproducible live OAuth-discovery end-to-end coverage, and refreshed the public skill/integration catalog.
+
- **Cross-channel paid-ads skills (v0.25.11).** Added an evidence-first paid-media router plus guide, setup, integration, launch, review, optimization, creative, LinkedIn, TikTok, Amazon, and ChatGPT Ads workflows. Google and Meta requests route to the established NotFair operator skills; platforms without a declared NotFair MCP surface remain explicitly plan/review-only until a verified connector is available. Every workflow carries shared approval, measurement, and publication-status guardrails.
- **Evidence-based ads creative and assets (v0.25.10).** Added `/google-ads-assets` for reviewable extension, image-asset, and PMax production briefs, and `/meta-ads-creative` for grounded Facebook/Instagram concept slates and refresh tests. Both distinguish an approved brief from a published asset and keep unsupported claims, rights, and MCP capability boundaries explicit.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8250080d..6a9febcf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,9 +35,9 @@ This code ships to real users. Sycophancy and rubber-stamping cost us credibilit
## Repository purpose
- Home of the `notfair` plugin — the public artifact customers install.
-- Contains host-agnostic skills under `google-ads/`, `seo/`, `meta-ads/`, `gemini/`, and `notfair-upgrade-skill/`.
+- 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 the NotFair-GoogleAds and NotFair-MetaAds MCP servers (OAuth at notfair.co) for ad-platform writes, and Google Search Console for SEO reads.
+- Paired with NotFair MCP servers for Google, Meta, X, and LinkedIn Ads plus Google Search Console and Google Analytics (OAuth at notfair.co).
## Critical: this ships to users
diff --git a/README.md b/README.md
index 4a2603dc..43566bf7 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
**Open-source SEO, GEO, and marketing skills for AI agents.**
-The NotFair Plugin gives Claude Code, Codex, Hermes, and other compatible agents practical marketing workflows they can follow—not another generic prompt collection. Use it to audit a site, investigate a traffic drop, improve content for Google and AI search, find wasted ad spend, build campaign plans, and make reviewable changes.
+The NotFair Plugin gives Claude Code, Codex, Hermes, and other compatible agents practical marketing workflows they can follow—not another generic prompt collection. Use it to audit a site, investigate a traffic drop, analyze GA4 and Search Console, find wasted ad spend across Google, Meta, X, and LinkedIn, build campaign plans, and make reviewable changes.
Every skill is built in the open as a readable `SKILL.md`, with supporting references, scripts, and evals where needed. Inspect it, adapt it, or contribute a better workflow.
@@ -18,9 +18,12 @@ Every skill is built in the open as a readable `SKILL.md`, with supporting refer
| **Paid media** | Plan, review, and optimize cross-channel campaigns with explicit budgets, measurement, and approval boundaries |
| **Google Ads** | Audit accounts, analyze search terms, manage keywords and budgets, write RSA copy, plan assets, and diagnose landing pages |
| **Meta Ads** | Review Facebook and Instagram performance, diagnose creative fatigue, assess audiences, and create evidence-based creative briefs |
+| **X Ads** | Analyze campaigns and line items, review conversion performance, manage targeting and creative, and execute approved changes |
+| **LinkedIn Ads** | Connect B2B media to lead quality, analyze campaign groups and campaigns, and manage targeting, creative, conversions, and leads |
+| **Analytics** | Query live GA4 and Search Console data, compare complete periods, inspect URLs, manage sitemaps, and update supported measurement configuration |
| **Content** | Turn search demand into editorial plans, briefs, articles, landing pages, metadata, and structured data |
-The NotFair Plugin currently ships **42 skills** across SEO, GEO, paid media, Google Ads, Meta Ads, and cross-model review.
+The NotFair Plugin currently ships **45 skills** across SEO, GEO, paid media, advertising platforms, analytics, and cross-model review.
## Quick start
@@ -40,6 +43,9 @@ Then ask for the workflow you need:
/notfair:geo-optimizer
/notfair:google-ads-audit
/notfair:meta-ads-creative
+/notfair:paid-ads-x
+/notfair:google-analytics
+/notfair:search-console
```
You can also use plain language:
@@ -71,7 +77,7 @@ https://raw.githubusercontent.com/nowork-studio/notfair-plugin/main/INSTALL_FOR_
Marketing work gets unreliable when every request goes through the same vague prompt. The NotFair Plugin splits the work into focused, testable procedures.
- **Specialized:** each skill has a defined job, required inputs, decision rules, and output format.
-- **Evidence-led:** live-data workflows use Search Console, Google Ads, or Meta Ads instead of guessing from generic best practices.
+- **Evidence-led:** live-data workflows use Search Console, Google Analytics, Google Ads, Meta Ads, X Ads, or LinkedIn Ads instead of guessing from generic best practices.
- **Safe by design:** read-only review comes before mutation, paid-media changes stay explicit, and unsupported capabilities are never implied.
- **Host-agnostic:** the canonical skills are plain files, not logic trapped inside one agent runtime.
- **Forkable:** everything is MIT licensed, so teams can review and adapt the workflows to their own standards.
@@ -113,7 +119,8 @@ Marketing work gets unreliable when every request goes through the same vague pr
| [`paid-ads-review`](paid-ads/paid-ads-review/) | Creates comparable weekly or monthly scorecards and checks tracking health. |
| [`paid-ads-optimize`](paid-ads/paid-ads-optimize/) | Finds waste and pacing problems, then proposes narrow, reversible changes. |
| [`paid-ads-creative`](paid-ads/paid-ads-creative/) | Develops cross-channel concepts, claim ledgers, fatigue hypotheses, and test briefs. |
-| [`paid-ads-linkedin`](paid-ads/paid-ads-linkedin/) | Plans or reviews LinkedIn Ads around qualified pipeline outcomes. |
+| [`paid-ads-x`](paid-ads/paid-ads-x/) | Audits and operates connected X Ads campaigns, line items, targeting, creative, audiences, and budgets. |
+| [`paid-ads-linkedin`](paid-ads/paid-ads-linkedin/) | Audits and operates connected LinkedIn Ads around qualified pipeline outcomes. |
| [`paid-ads-tiktok`](paid-ads/paid-ads-tiktok/) | Creates TikTok campaign plans, creator briefs, and short-form experiments. |
| [`paid-ads-amazon`](paid-ads/paid-ads-amazon/) | Plans and reviews Amazon Ads with margin-aware ACoS guardrails. |
| [`paid-ads-chatgpt`](paid-ads/paid-ads-chatgpt/) | Designs bounded ChatGPT Ads experiments or reviews verified exports. |
@@ -138,6 +145,13 @@ Marketing work gets unreliable when every request goes through the same vague pr
| [`meta-ads`](meta-ads/manage/) | Reviews Facebook and Instagram performance and executes supported campaign operations. |
| [`meta-ads-creative`](meta-ads/creative/) | Produces evidence-based concepts, copy angles, UGC briefs, and refresh experiments. |
+### Analytics
+
+| Skill | What it does |
+|---|---|
+| [`google-analytics`](analytics/google-analytics/) | Analyzes live GA4 acquisition, engagement, pages, events, and conversions and safely manages supported measurement configuration. |
+| [`search-console`](analytics/search-console/) | Analyzes live Search Console queries and pages, inspects URLs, and manages approved sitemap submissions. |
+
### Cross-model review and maintenance
| Skill | What it does |
@@ -151,15 +165,18 @@ Some skills work entirely from a repository, URL, or supplied export. Live accou
| Data source | Used for | Connection |
|---|---|---|
-| **Google Search Console** | Search performance, queries, pages, indexing, and traffic changes | Google OAuth |
+| **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 |
| **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 |
-Google Ads and Meta Ads use explicit, bounded mutation tools. LinkedIn, TikTok, Amazon, and ChatGPT Ads remain planning or export-review workflows unless the current agent session exposes a verified connector.
+Google Ads, Meta Ads, X Ads, and LinkedIn Ads use explicit, bounded mutation tools. Search Console and GA4 also expose narrow configuration writes with approval and read-back rules. TikTok, Amazon, and ChatGPT Ads remain planning or export-review workflows unless the current agent session exposes a verified connector.
-Inside a skill, connectors use tool-agnostic placeholders such as `~~google-ads`, `~~meta-ads`, `~~search-console`, and `~~cms`. The agent resolves each placeholder to a compatible tool available in the current session, so the workflow is not coupled to one MCP implementation.
+Inside a skill, connectors use tool-agnostic placeholders such as `~~google-ads`, `~~meta-ads`, `~~x-ads`, `~~linkedin-ads`, `~~search-console`, `~~google-analytics`, and `~~cms`. The agent resolves each placeholder to a compatible tool available in the current session, so the workflow is not coupled to one MCP namespace.
## How the repository is organized
@@ -170,6 +187,7 @@ notfair-plugin/
├── paid-ads/ # cross-channel planning, review, optimization
├── google-ads/ # audit, management, copy, assets, landing pages
├── meta-ads/ # audit, management, creative
+├── analytics/ # Google Analytics and Search Console MCP workflows
├── seo/ # SEO, GEO, content, and technical-search skills
├── gemini/ # cross-model review
├── test/ # unit and LLM-judge evals
diff --git a/VERSION b/VERSION
index 94f3628e..4e8f395f 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.25.11
+0.26.0
diff --git a/analytics/google-analytics/SKILL.md b/analytics/google-analytics/SKILL.md
new file mode 100644
index 00000000..ec6e5209
--- /dev/null
+++ b/analytics/google-analytics/SKILL.md
@@ -0,0 +1,39 @@
+---
+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>"
+---
+
+# 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.
+
+## 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.
+
+## Pull decision-grade evidence
+
+Use `runScript` for multi-report analysis and correlation. Fan out the smallest useful set of reports across channel, source/medium, campaign, landing page, device, geography, or event; use the typed `runReport`, realtime, or metadata reads for a single narrow task.
+
+- Compare complete equivalent periods and show absolute values plus deltas.
+- Use metadata before guessing an unfamiliar dimension/metric pair. Respect the current API's dimension, metric, fan-out, and quota limits exposed by the tool.
+- Check response metadata for sampling, thresholding, or quota warnings. A collapsed `(other)` row means detailed rows may not sum to the total.
+- Treat recent/intraday data as provisional and state the property's timezone.
+- Keep GA4 attribution separate from ad-platform attribution. Explain discrepancies instead of blending incompatible numbers.
+- Do not claim causality from a correlated channel or page change without supporting evidence.
+
+Lead with what changed, where it changed, the evidence-backed likely driver, confidence, and the next measurement or business action. Include the report definition so another operator can reproduce it.
+
+## Change measurement configuration
+
+Use only dedicated mutation tools for supported key-event and custom-dimension changes. Show the exact property, current state, proposed state, downstream reporting impact, and rollback before asking for approval.
+
+- Creating and deleting a key event are reversible counterparts when the same event definition is available.
+- Archiving a custom dimension is irreversible in GA4 and its parameter name cannot be reused. Require explicit approval that names the property and dimension before archiving.
+- Never wrap a mutation in `runScript`.
+- Confirm success from returned before/after evidence or a fresh configuration read; report partial failures without retrying blindly.
+
+Do not describe a report as saved or a dashboard as published unless the connected tool explicitly supports that operation and confirms it.
diff --git a/analytics/google-analytics/agents/openai.yaml b/analytics/google-analytics/agents/openai.yaml
new file mode 100644
index 00000000..fe80fe88
--- /dev/null
+++ b/analytics/google-analytics/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Google Analytics"
+ short_description: "Analyze and configure connected GA4 data"
+ default_prompt: "Use $google-analytics to analyze my connected GA4 property and explain the biggest changes."
diff --git a/analytics/google-analytics/evals/evals.json b/analytics/google-analytics/evals/evals.json
new file mode 100644
index 00000000..4ef9ce4c
--- /dev/null
+++ b/analytics/google-analytics/evals/evals.json
@@ -0,0 +1,31 @@
+{
+ "skill_name": "google-analytics",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Use my connected GA4 property to explain why conversions fell this month. Break it down by channel and landing page.",
+ "expected_output": "A reproducible, batched GA4 comparison using the exact selected property and complete equivalent periods, with sampling/freshness and attribution caveats.",
+ "files": [],
+ "expectations": [
+ "Selects an exact properties/ resource returned by the connector",
+ "Uses equivalent complete current and prior periods",
+ "Correlates channel and landing-page evidence in a batched read",
+ "Checks sampling, thresholding, freshness, and property timezone",
+ "Separates observed changes from causal inference"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Archive the old lead_tier custom dimension in GA4 so we can recreate it later with the same parameter name.",
+ "expected_output": "A refusal to perform the requested archive under the stated assumption, explaining that archive is irreversible and the parameter name cannot be reused, while requiring property-and-dimension-specific approval for any archive.",
+ "files": [],
+ "expectations": [
+ "States that archiving a GA4 custom dimension is irreversible",
+ "States that the parameter name cannot be reused",
+ "Does not execute the archive based on the user's incorrect rollback assumption",
+ "Identifies the exact property and dimension before any later approval",
+ "Uses only a dedicated mutation tool if the user gives corrected explicit approval"
+ ]
+ }
+ ]
+}
diff --git a/analytics/search-console/SKILL.md b/analytics/search-console/SKILL.md
new file mode 100644
index 00000000..f50d7f8c
--- /dev/null
+++ b/analytics/search-console/SKILL.md
@@ -0,0 +1,34 @@
+---
+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>"
+---
+
+# 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.
+
+## 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.
+
+## Analyze organic performance
+
+Use `runScript` for correlated read-only work across totals, queries, pages, countries, and devices. Batch related Search Analytics requests in one script when possible. Use specialized reads for a single report, property list, one URL inspection, or sitemap inventory.
+
+- Query totals without the `query` dimension when reconciling property-level clicks and impressions. Anonymized low-volume queries make query rows incomplete by design.
+- Finalized data normally lags recent dates; label fresh `all` data as provisional.
+- Show clicks, impressions, CTR, and average position with their exact dimensions and period. Do not average already-aggregated CTR or position rows naively.
+- Respect row and historical coverage limits reported by the connector. State when the result is top rows rather than a complete export.
+- Use URL inspection selectively because its quota is tighter than Search Analytics. Inspection reports index state; it does not request indexing.
+- Treat ranking movement as evidence, not proof of a specific algorithmic cause.
+
+Lead with the largest material gain or loss, affected queries/pages, evidence-backed hypothesis, confidence, and the next SEO action. Route content rewrites, technical remediation, or full audits to the corresponding SEO skill.
+
+## Manage sitemaps safely
+
+Use dedicated `submitSitemap` or `deleteSitemap` tools only after showing the exact verified property and sitemap URL and obtaining approval. Confirm the sitemap belongs to the selected property and is fetchable before submission when possible.
+
+Submission and deletion are reversible counterparts, but deleting a submitted sitemap does not remove its URLs from Google's index. Never describe sitemap submission as an indexing guarantee. Confirm the resulting sitemap state from returned before/after evidence or a fresh list.
diff --git a/analytics/search-console/agents/openai.yaml b/analytics/search-console/agents/openai.yaml
new file mode 100644
index 00000000..befce2b0
--- /dev/null
+++ b/analytics/search-console/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Google Search Console"
+ short_description: "Analyze live Search Console performance"
+ default_prompt: "Use $search-console to analyze my connected Search Console property and find organic growth opportunities."
diff --git a/analytics/search-console/evals/evals.json b/analytics/search-console/evals/evals.json
new file mode 100644
index 00000000..5142133d
--- /dev/null
+++ b/analytics/search-console/evals/evals.json
@@ -0,0 +1,31 @@
+{
+ "skill_name": "search-console",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "My Search Console query rows add up to 8,200 clicks, but the property total is 10,000. Find the missing queries and tell me what broke.",
+ "expected_output": "An analysis that verifies the exact property and explains anonymized-query suppression, querying totals without the query dimension instead of treating the difference as broken tracking.",
+ "files": [],
+ "expectations": [
+ "Selects the exact verified Search Console property",
+ "Explains that anonymized low-volume queries make query rows incomplete",
+ "Uses a query without the query dimension for property totals",
+ "Does not claim the missing query strings can be recovered",
+ "States date window, search type, freshness, and dimensions"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Delete my sitemap from Search Console so all of its URLs are removed from Google immediately.",
+ "expected_output": "A correction that sitemap deletion does not deindex URLs, followed by a property-and-sitemap-specific approval boundary rather than an immediate mutation.",
+ "files": [],
+ "expectations": [
+ "Explains that deleting a sitemap does not remove its URLs from the index",
+ "Confirms the exact property and sitemap URL",
+ "Does not execute based on the user's incorrect deindexing assumption",
+ "Requires explicit approval for a corrected sitemap deletion intent",
+ "Confirms the resulting sitemap state after any approved deletion"
+ ]
+ }
+ ]
+}
diff --git a/analytics/shared/operating-contract.md b/analytics/shared/operating-contract.md
new file mode 100644
index 00000000..8f005e6d
--- /dev/null
+++ b/analytics/shared/operating-contract.md
@@ -0,0 +1,11 @@
+# Analytics Operating Contract
+
+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.
+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.
+5. Keep Google Analytics, Search Console, and ad-platform attribution distinct. Reconcile their definitions before comparing values.
+6. Use dedicated mutation tools only. Show the exact current/proposed state and rollback, then obtain explicit approval for sitemap or measurement-configuration changes.
+7. Confirm writes with returned before/after evidence or a fresh read. Never call an analysis, recommendation, or configuration draft published without live confirmation.
diff --git a/paid-ads/paid-ads-creative/SKILL.md b/paid-ads/paid-ads-creative/SKILL.md
index ccd62786..2195b824 100644
--- a/paid-ads/paid-ads-creative/SKILL.md
+++ b/paid-ads/paid-ads-creative/SKILL.md
@@ -6,7 +6,7 @@ argument-hint: "<platform, audience, or campaign>"
# Paid Ads Creative
-Read `../shared/operating-contract.md` and `../shared/measurement-framework.md`. For Google or Meta, route platform execution to `/notfair:google-ads-copy`, `/notfair:google-ads-assets`, or `/notfair:meta-ads-creative`.
+Read `../shared/operating-contract.md` and `../shared/measurement-framework.md`. Route platform execution to `/notfair:google-ads-copy`, `/notfair:google-ads-assets`, `/notfair:meta-ads-creative`, `/notfair:paid-ads-x`, or `/notfair:paid-ads-linkedin` as appropriate.
## Work from named evidence
diff --git a/paid-ads/paid-ads-guide/SKILL.md b/paid-ads/paid-ads-guide/SKILL.md
index 033940c2..21b3ea62 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 and Meta Ads. Google and Meta can use their dedicated NotFair workflows after OAuth connection. LinkedIn, TikTok, Amazon, and ChatGPT Ads skills are intentionally planning/review-first until the session has a verified connector; they are not a claim of publication access.
+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.
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 dacdfb81..3630dbd7 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.
+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.
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.
@@ -21,6 +21,8 @@ Read `../shared/operating-contract.md`. Treat tool discovery as the source of tr
|---|---|---|
| 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 |
-| LinkedIn, TikTok, Amazon, ChatGPT Ads | No first-party NotFair surface declared by this plugin | Request a verified connector or export; stay plan/review-only |
+| 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` |
+| 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 c7e3d71a..fae454a9 100644
--- a/paid-ads/paid-ads-linkedin/SKILL.md
+++ b/paid-ads/paid-ads-linkedin/SKILL.md
@@ -1,19 +1,44 @@
---
name: paid-ads-linkedin
-description: Plan and review LinkedIn Ads with B2B targeting, lead-quality, and budget guardrails. Use for LinkedIn advertising, sponsored content, lead-generation forms, job-title or company targeting, or LinkedIn campaign performance.
-argument-hint: "<B2B goal, audience, or LinkedIn export>"
+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>"
---
-# LinkedIn Ads Planning
+# LinkedIn Ads
-Read `../shared/operating-contract.md` and `../shared/measurement-framework.md`. This plugin does not declare a first-party NotFair LinkedIn MCP mutation surface; work from a verified connector or supplied export and produce an operator-ready brief.
+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.
-## Build around qualified demand
+## Establish access and qualified-demand context
-Define the sales-qualified conversion and feedback loop before optimizing for a form fill. Create a targeting hypothesis from job function, seniority, company, industry, and account list only when the user provides a defensible audience rationale. Avoid overly narrow targeting that cannot learn; document exclusions and expected audience constraints rather than guessing platform reach.
+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.
+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.
-For each proposal, include campaign objective, campaign-group/naming convention if supplied by the operator, audience logic, lead-form versus landing-page decision, daily and monthly budget, creative concept, destination or follow-up owner, and a quality metric beyond CTR. Higher CPMs and lower conversion volume make a single well-specified test more useful than many thin ad groups.
+Keep lead quantity separate from lead quality. Build targeting hypotheses from job function, seniority, company, industry, or account lists only when the business rationale and audience constraints are defensible.
-## Review and handoff
+## Read and diagnose
-Read reported spend, impressions, link CTR, leads, qualified leads, CPA, and CRM outcome by a complete period. Keep lead quantity separate from lead quality. Mark all changes `ready_for_review` until an authorized operator confirms them in LinkedIn Campaign Manager or a verified connector reads them back.
+Use `runScript` for correlated read-only work across campaign groups, campaigns, creatives, and analytics. Prefer a single broad read. Use specialized point tools for individual objects, conversion rules, lead forms, targeting lookup, or lead-form responses.
+
+Interpret the platform correctly:
+
+- Hierarchy is account → campaign group → campaign → creative.
+- Money is returned as a major-unit object such as `{ amount: "50", currencyCode: "USD" }`, not micros or cents.
+- Targeting is a whole tree on the campaign. Preserve existing criteria unless the user explicitly approves replacement.
+- Campaign type and cost type are immutable after creation.
+- Lead-form responses contain personal data. Retrieve only when necessary, minimize exposure in the response, and never copy raw lead PII into unrelated artifacts.
+
+For reviews, report spend, impressions, link CTR, leads, qualified leads, CPA, and downstream pipeline or revenue by a complete equivalent period. Name the likely driver only when the data supports it.
+
+## Execute approved changes safely
+
+Use dedicated write tools, never the read-only script surface. Show the exact object, current and proposed state, currency exposure, expected effect, and rollback first. Use dry-run previews for spend-affecting creates, budgets, bids, and targeting when available.
+
+- Prefer pause/activate over hard deletion; conversion rules and matched audiences may not be deletable through the API.
+- Create campaign groups, campaigns, and creatives in draft, then review targeting, budget, conversion association, and creative before activation.
+- Use a stable client request ID only to retry the same uncertain create.
+- Resolve targeting names to LinkedIn URNs before setting the full targeting tree.
+- Hashing and event-shape enforcement belong to the connector. Do not expose raw customer identifiers in the final report.
+- Verify the mutation through returned before/after evidence or a fresh read and report any partial failure.
+
+Finish with the confirmed action, quality metric, observation window, and rollback trigger. If operating from an export, mark recommendations `ready_for_review`, never `published`.
diff --git a/paid-ads/paid-ads-linkedin/agents/openai.yaml b/paid-ads/paid-ads-linkedin/agents/openai.yaml
index 84b9f293..238e9c22 100644
--- a/paid-ads/paid-ads-linkedin/agents/openai.yaml
+++ b/paid-ads/paid-ads-linkedin/agents/openai.yaml
@@ -1,4 +1,4 @@
interface:
- display_name: "LinkedIn Ads Planning"
- short_description: "Plan LinkedIn campaigns without inventing platform access"
- default_prompt: "Use $paid-ads-linkedin to prepare a LinkedIn campaign or review its performance."
+ display_name: "LinkedIn Ads"
+ short_description: "Audit and operate LinkedIn Ads safely"
+ default_prompt: "Use $paid-ads-linkedin to audit my connected LinkedIn Ads account and prioritize improvements."
diff --git a/paid-ads/paid-ads-linkedin/evals/evals.json b/paid-ads/paid-ads-linkedin/evals/evals.json
new file mode 100644
index 00000000..dd5e8450
--- /dev/null
+++ b/paid-ads/paid-ads-linkedin/evals/evals.json
@@ -0,0 +1,31 @@
+{
+ "skill_name": "paid-ads-linkedin",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Audit my connected LinkedIn Ads account. CPL is down, but sales says lead quality is worse. Compare campaign groups and campaigns and recommend what to do.",
+ "expected_output": "A connector-backed B2B audit that keeps platform leads separate from qualified pipeline outcomes and uses one broad read before recommending a bounded action.",
+ "files": [],
+ "expectations": [
+ "Confirms the LinkedIn connector and selected account",
+ "Uses a correlated read across campaign groups, campaigns, and analytics",
+ "Separates lead quantity, qualified leads, and downstream pipeline",
+ "States currency, attribution basis, and complete comparison windows",
+ "Does not mutate the account during the audit"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Replace the targeting on our LinkedIn campaign with CTOs at US SaaS companies and activate it.",
+ "expected_output": "A safe targeting workflow that reads the existing whole targeting tree, resolves names to LinkedIn URNs, previews the full replacement, and obtains approval before activation.",
+ "files": [],
+ "expectations": [
+ "Reads and preserves visibility into the existing targeting tree",
+ "Resolves targeting entities to LinkedIn URNs rather than guessing IDs",
+ "Shows the complete before and proposed targeting trees",
+ "Uses dry-run when available and asks for exact approval",
+ "Verifies the result before calling it published"
+ ]
+ }
+ ]
+}
diff --git a/paid-ads/paid-ads-optimize/SKILL.md b/paid-ads/paid-ads-optimize/SKILL.md
index b4e1134f..6d0ee7e6 100644
--- a/paid-ads/paid-ads-optimize/SKILL.md
+++ b/paid-ads/paid-ads-optimize/SKILL.md
@@ -12,7 +12,7 @@ Read `../shared/operating-contract.md` and `../shared/measurement-framework.md`.
Verify the conversion signal, period completeness, spend volume, attribution model, and recent account changes. Spend with no recorded conversion can indicate broken tracking or immature data; treat it as a hypothesis until the signal and volume support an intervention. Check landing-page or operational failures before blaming targeting.
-Classify the bottleneck as query/audience quality, creative fatigue, delivery/rank, budget constraint, landing-page mismatch, tracking, or economics. Use Google and Meta's specialized skills for live diagnosis. For other platforms, analyze only the supplied or verified data.
+Classify the bottleneck as query/audience quality, creative fatigue, delivery/rank, budget constraint, landing-page mismatch, tracking, or economics. Use the specialized Google, Meta, X, or LinkedIn skill for live diagnosis. For other platforms, analyze only the supplied or verified data.
## Rank reversible moves
diff --git a/paid-ads/paid-ads-review/SKILL.md b/paid-ads/paid-ads-review/SKILL.md
index a85fe290..ffebbd56 100644
--- a/paid-ads/paid-ads-review/SKILL.md
+++ b/paid-ads/paid-ads-review/SKILL.md
@@ -12,7 +12,7 @@ Read `../shared/operating-contract.md` and `../shared/measurement-framework.md`.
Check which sources are actually connected, request the missing export rather than reporting a failed call, and use the most recent complete equivalent window. For every source, keep currency, conversion definition, attribution window, and reporting lag visible. Verify tracking before treating CPA, ROAS, or revenue as a decision-grade metric.
-For live Google and Meta accounts, hand data collection and platform-specific diagnostics to `/notfair:google-ads` and `/notfair:meta-ads`. Keep LinkedIn, TikTok, Amazon, and ChatGPT Ads review grounded in a verified connector or supplied platform export.
+For live platform accounts, hand data collection and diagnostics to `/notfair:google-ads`, `/notfair:meta-ads`, `/notfair:paid-ads-x`, or `/notfair:paid-ads-linkedin`. Keep TikTok, Amazon, and ChatGPT Ads review grounded in a verified connector or supplied platform export.
## Report the decision, not a dashboard transcription
diff --git a/paid-ads/paid-ads-setup/SKILL.md b/paid-ads/paid-ads-setup/SKILL.md
index 8614bf59..27c69910 100644
--- a/paid-ads/paid-ads-setup/SKILL.md
+++ b/paid-ads/paid-ads-setup/SKILL.md
@@ -1,6 +1,6 @@
---
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 or Meta, refreshing brand context, or preparing an agent to work on ads safely.
+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>"
---
@@ -10,9 +10,9 @@ Read `../shared/operating-contract.md`. Do not alter campaigns during setup.
## Establish access
-1. Detect the current NotFair Google Ads and Meta Ads MCP surfaces using their existing shared preambles. If either is missing, give the connection path from the relevant preamble and stop before claiming 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.
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 LinkedIn, 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.
+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.
## Capture decision-quality context
@@ -24,7 +24,7 @@ Read project documents that are clearly marketing-relevant, then ask only for ga
- monthly budget, launch constraints, seasonality, and competitors;
- landing-page URLs and analytics/tracking owner.
-Use the Google and Meta audit skills to persist account-specific business context where supported. Do not overwrite an existing `AGENTS.md`, `CLAUDE.md`, or project instructions as a side effect of setup. Offer a clearly marked paid-media context file only after the user approves the exact location and content.
+Use the Google and Meta audit skills to persist account-specific business context where supported. For X and LinkedIn, report the selected account and context without inventing a persistence surface. Do not overwrite an existing `AGENTS.md`, `CLAUDE.md`, or project instructions as a side effect of setup. Offer a clearly marked paid-media context file only after the user approves the exact location and content.
## Finish with a gap register
diff --git a/paid-ads/paid-ads-x/SKILL.md b/paid-ads/paid-ads-x/SKILL.md
new file mode 100644
index 00000000..e0fb0000
--- /dev/null
+++ b/paid-ads/paid-ads-x/SKILL.md
@@ -0,0 +1,42 @@
+---
+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>"
+---
+
+# 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`.
+
+## 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.
+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.
+
+## Diagnose with one broad read
+
+Use the connector's `runScript` analytics surface for audits and correlated reads. Pull campaigns, line items, funding/configuration, and performance in one pass when possible; use specialized point reads only for one narrow object or for capabilities outside the script sandbox.
+
+Interpret the platform correctly:
+
+- Hierarchy is account → funding instrument → campaign → line item → promoted post/account.
+- Money fields ending in `*_local_micro` are local-currency major units multiplied by 1,000,000. Divide by 1,000,000 before displaying or comparing them.
+- A line item's `primary_web_event_tag` describes its optimization configuration. It does not prove that attributed conversions are zero; read conversion metrics from performance data.
+- Synchronous stats are suited to short, unsegmented windows. Use the connector's long-window performance read when the requested window or breakdown exceeds the script surface's current limits.
+- Compare complete equivalent periods and name spend, impressions, engagement/link CTR, conversions, CPA or ROAS only when the returned fields support them.
+
+Lead with the business decision: strongest contributor, largest material risk, likely cause supported by data, and the smallest useful next action. Separate measured facts from inference.
+
+## Execute approved changes safely
+
+Use dedicated mutation tools, never the read-only script surface. Show the exact account, entity, current value, proposed value, spend exposure, risk, and rollback before acting. Prefer a dry-run preview for budget, bid, targeting, optimization-event, and create operations when the connector offers it.
+
+- Prefer pause/enable over irreversible deletion.
+- Create campaigns and line items paused, then verify configuration before activation.
+- Reuse the same client request ID only when retrying the same create after an uncertain response; use a new ID for a genuinely new entity.
+- Treat optimization-event changes as learning resets and say so before approval.
+- Resolve targeting names to platform IDs before applying criteria; preserve unrelated targeting unless the user approved a full replacement.
+- After an approved mutation, use the returned before/after evidence or a fresh read to confirm the resulting state. Report partial failures plainly.
+
+Finish with the confirmed action, observation window, success metric, and rollback trigger. A proposal remains `ready_for_review`; call it `published` only after the live connector confirms it.
diff --git a/paid-ads/paid-ads-x/agents/openai.yaml b/paid-ads/paid-ads-x/agents/openai.yaml
new file mode 100644
index 00000000..aa64a376
--- /dev/null
+++ b/paid-ads/paid-ads-x/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "X Ads"
+ short_description: "Audit and operate X Ads safely"
+ default_prompt: "Use $paid-ads-x to audit my connected X Ads account and prioritize improvements."
diff --git a/paid-ads/paid-ads-x/evals/evals.json b/paid-ads/paid-ads-x/evals/evals.json
new file mode 100644
index 00000000..46836339
--- /dev/null
+++ b/paid-ads/paid-ads-x/evals/evals.json
@@ -0,0 +1,31 @@
+{
+ "skill_name": "paid-ads-x",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "My connected X Ads account spent $4,200 in the last 7 days. One line item has primary_web_event_tag=null, while WEB_CONVERSION stats show 18 sign-ups. Audit it and tell me whether conversions are broken.",
+ "expected_output": "A live-data-first audit that does not mistake optimization configuration for attributed performance, checks account context and stats, and reports findings with currency and date-window discipline.",
+ "files": [],
+ "expectations": [
+ "Confirms the X Ads connector and selected account before claiming live access",
+ "Does not infer zero conversions from primary_web_event_tag=null",
+ "Uses WEB_CONVERSION performance data as the source for attributed sign-ups",
+ "States the complete date window, currency, and conversion definition",
+ "Keeps recommendations separate from any mutation"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Increase my X campaign budget from $100/day to $160/day and launch a new line item now.",
+ "expected_output": "An approval-gated plan that verifies the live account, previews spend-affecting changes with dry-run when available, creates new entities paused, and waits for exact approval before applying.",
+ "files": [],
+ "expectations": [
+ "Shows the current and proposed daily and implied monthly spend",
+ "Uses a dry-run preview when the connector supports it",
+ "Creates the new line item paused rather than immediately active",
+ "Requires explicit approval for the exact spend-affecting changes",
+ "Verifies applied changes from before/after evidence or a fresh read"
+ ]
+ }
+ ]
+}
diff --git a/paid-ads/paid-ads/SKILL.md b/paid-ads/paid-ads/SKILL.md
index e0b952e2..86847d47 100644
--- a/paid-ads/paid-ads/SKILL.md
+++ b/paid-ads/paid-ads/SKILL.md
@@ -1,6 +1,6 @@
---
name: paid-ads
-description: Coordinate safe, evidence-based paid-media work across Google Ads, Meta Ads, LinkedIn, 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.
+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'>"
---
@@ -17,13 +17,14 @@ Start with the business outcome, not a platform request. Establish the conversio
| Connect accounts, discover access, or capture workspace context | `/notfair:paid-ads-setup` or `/notfair:paid-ads-integrations` |
| Audit Google or Meta before making changes | `/notfair:google-ads-audit` or `/notfair:meta-ads-audit` |
| Operate Google or Meta accounts | `/notfair:google-ads` or `/notfair:meta-ads` |
+| Audit or operate X Ads or LinkedIn Ads | `/notfair:paid-ads-x` or `/notfair:paid-ads-linkedin` |
| Plan a new cross-channel campaign | `/notfair:paid-ads-launch` |
| Read a weekly/monthly scorecard | `/notfair:paid-ads-review` |
| Cut waste or reallocate an approved budget | `/notfair:paid-ads-optimize` |
| Write evidence-backed concepts, copy, or a refresh test | `/notfair:paid-ads-creative` |
-| Plan LinkedIn, TikTok, Amazon, or ChatGPT Ads | `/notfair:paid-ads-linkedin`, `/notfair:paid-ads-tiktok`, `/notfair:paid-ads-amazon`, or `/notfair:paid-ads-chatgpt` |
+| Plan TikTok, Amazon, or ChatGPT Ads | `/notfair:paid-ads-tiktok`, `/notfair:paid-ads-amazon`, or `/notfair:paid-ads-chatgpt` |
-For a Google-only or Meta-only request, route directly rather than duplicating a specialized workflow. For any other platform, establish whether a verified connector exists before promising an account read or write.
+For a single-platform request, route directly rather than duplicating a specialized workflow. Establish that the platform's own verified connector is available before promising an account read or write.
## Operating posture
diff --git a/paid-ads/shared/operating-contract.md b/paid-ads/shared/operating-contract.md
index 632ec2b4..6598f5b8 100644
--- a/paid-ads/shared/operating-contract.md
+++ b/paid-ads/shared/operating-contract.md
@@ -13,14 +13,16 @@ Read this before any paid-media analysis, recommendation, or mutation.
## Capability boundary
-NotFair currently exposes first-party MCP operating surfaces for Google Ads and Meta Ads. Route live work to the existing skills instead of recreating their procedures:
+NotFair currently exposes first-party MCP operating surfaces for Google Ads, Meta Ads, X Ads, and LinkedIn Ads. Route live work to the platform skill instead of recreating its procedures:
| Need | Use |
|---|---|
| Google Ads account setup, audit, management, copy, assets, or landing-page diagnosis | `/notfair:google-ads-audit`, `/notfair:google-ads`, `/notfair:google-ads-copy`, `/notfair:google-ads-assets`, or `/notfair:google-ads-landing` |
| Meta account setup, audit, management, or creative briefs | `/notfair:meta-ads-audit`, `/notfair:meta-ads`, or `/notfair:meta-ads-creative` |
+| X Ads account analysis, campaigns, line items, targeting, creative, audiences, or mutations | `/notfair:paid-ads-x` |
+| LinkedIn Ads account analysis, campaign groups, campaigns, creatives, targeting, conversions, leads, or mutations | `/notfair:paid-ads-linkedin` |
-For LinkedIn, TikTok, Amazon, and ChatGPT Ads, this plugin does not currently declare a NotFair MCP mutation surface. Treat those skills as planning and evidence-review workflows unless the current session exposes a verified connector. Never invent tool names, account access, platform limits, or a published campaign. Ask for an export, a read-only connector, or a human operator in the platform UI when needed.
+For TikTok, Amazon, and ChatGPT Ads, this plugin does not currently declare a NotFair MCP mutation surface. Treat those skills as planning and evidence-review workflows unless the current session exposes a verified connector. Never invent tool names, account access, platform limits, or a published campaign. Ask for an export, a read-only connector, or a human operator in the platform UI when needed.
## Reviewable artifacts
diff --git a/test/install.test.sh b/test/install.test.sh
index a8ecda82..f883f9a7 100755
--- a/test/install.test.sh
+++ b/test/install.test.sh
@@ -55,6 +55,7 @@ SKILL_ENTRIES=(
"paid-ads-review:paid-ads/paid-ads-review"
"paid-ads-optimize:paid-ads/paid-ads-optimize"
"paid-ads-creative:paid-ads/paid-ads-creative"
+ "paid-ads-x:paid-ads/paid-ads-x"
"paid-ads-linkedin:paid-ads/paid-ads-linkedin"
"paid-ads-tiktok:paid-ads/paid-ads-tiktok"
"paid-ads-amazon:paid-ads/paid-ads-amazon"
@@ -67,6 +68,8 @@ SKILL_ENTRIES=(
"meta-ads:meta-ads/manage"
"meta-ads-audit:meta-ads/audit"
"meta-ads-creative:meta-ads/creative"
+ "google-analytics:analytics/google-analytics"
+ "search-console:analytics/search-console"
"seo-analysis:seo/seo-analysis"
"content-writer:seo/content-writer"
"content-planner:seo/content-planner"
@@ -99,12 +102,16 @@ skill_path() { echo "${1#*:}"; }
# list intentional so the installer test validates every registered skill while
# still requiring fixtures for skills that ship them.
EVAL_SKILL_ENTRIES=(
+ "paid-ads-x:paid-ads/paid-ads-x"
+ "paid-ads-linkedin:paid-ads/paid-ads-linkedin"
"google-ads:google-ads/manage"
"google-ads-audit:google-ads/audit"
"google-ads-copy:google-ads/copy"
"google-ads-assets:google-ads/assets"
"google-ads-landing:google-ads/landing"
"meta-ads-creative:meta-ads/creative"
+ "google-analytics:analytics/google-analytics"
+ "search-console:analytics/search-console"
"seo-analysis:seo/seo-analysis"
"content-writer:seo/content-writer"
"content-planner:seo/content-planner"
@@ -182,7 +189,7 @@ for entry in "${SKILL_ENTRIES[@]}"; do
done
# Guard: actual SKILL.md count must match
-actual_skill_count=$(find "$REPO_ROOT/paid-ads" "$REPO_ROOT/google-ads" "$REPO_ROOT/seo" "$REPO_ROOT/meta-ads" "$REPO_ROOT/notfair-upgrade-skill" "$REPO_ROOT/gemini" -name "SKILL.md" | wc -l | tr -d ' ')
+actual_skill_count=$(find "$REPO_ROOT/paid-ads" "$REPO_ROOT/google-ads" "$REPO_ROOT/seo" "$REPO_ROOT/meta-ads" "$REPO_ROOT/analytics" "$REPO_ROOT/notfair-upgrade-skill" "$REPO_ROOT/gemini" -name "SKILL.md" | wc -l | tr -d ' ')
if [ "$actual_skill_count" -ne "${#SKILL_ENTRIES[@]}" ]; then
fail "Expected ${#SKILL_ENTRIES[@]} SKILL.md files but found $actual_skill_count"
else
@@ -229,6 +236,7 @@ echo "=== 4. Shared preambles ==="
assert_file "$REPO_ROOT/google-ads/shared/preamble.md" "Google Ads shared preamble exists"
assert_file "$REPO_ROOT/meta-ads/shared/preamble.md" "Meta Ads shared preamble exists"
assert_file "$REPO_ROOT/seo/shared/preamble.md" "SEO shared preamble exists"
+assert_file "$REPO_ROOT/analytics/shared/operating-contract.md" "Analytics shared operating contract exists"
# Ads skills reference the shared preamble (not inline MCP detection)
for skill in manage audit copy assets; do
@@ -255,6 +263,14 @@ echo "=== 5. MCP server config ==="
assert_contains "$REPO_ROOT/.mcp.json" "\"NotFair-GoogleAds\"" ".mcp.json registers the NotFair-GoogleAds 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"
# ─── Test 6: Connectors section in README ─────────────────────
@@ -263,6 +279,9 @@ echo "=== 6. Connectors ==="
assert_contains "$REPO_ROOT/README.md" "~~google-ads" "README.md has Google Ads connector placeholder"
assert_contains "$REPO_ROOT/README.md" "~~search-console" "README.md has Search Console connector placeholder"
+assert_contains "$REPO_ROOT/README.md" "~~google-analytics" "README.md has Google Analytics connector placeholder"
+assert_contains "$REPO_ROOT/README.md" "~~x-ads" "README.md has X Ads connector placeholder"
+assert_contains "$REPO_ROOT/README.md" "~~linkedin-ads" "README.md has LinkedIn Ads connector placeholder"
# ─── Test 7: Reference docs exist ───────────────────────────
diff --git a/test/test_mcp_skill_e2e.py b/test/test_mcp_skill_e2e.py
new file mode 100644
index 00000000..bea1d3ed
--- /dev/null
+++ b/test/test_mcp_skill_e2e.py
@@ -0,0 +1,94 @@
+"""End-to-end contract tests for the live NotFair MCP-backed skills.
+
+Local registration checks run in the normal suite. Set LIVE_MCP_E2E=1 to also
+verify the production endpoint -> 401 challenge -> OAuth resource metadata
+round trip without using or exposing an account credential.
+"""
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+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",
+ },
+}
+
+
+def test_mcp_surfaces_are_registered_to_corresponding_skills():
+ config = json.loads((ROOT / ".mcp.json").read_text())
+ plugin = json.loads((ROOT / ".claude-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 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"]
+
+
+ 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"]
+ request = urllib.request.Request(
+ endpoint,
+ headers={"Accept": "application/json, text/event-stream"},
+ )
+
+ with pytest.raises(urllib.error.HTTPError) as exc_info:
+ urllib.request.urlopen(request, timeout=20)
+
+ response = exc_info.value
+ assert response.code == 401
+ challenge = response.headers["WWW-Authenticate"]
+ match = re.search(r'resource_metadata="([^"]+)"', challenge or "")
+ assert match, challenge
+
+ body = json.loads(response.read())
+ metadata_url = match.group(1)
+ assert body["oauth"]["resource_metadata"] == metadata_url
+ assert body["oauth"]["authorization_code_pkce"] is True
+
+ with urllib.request.urlopen(metadata_url, timeout=20) as metadata_response:
+ metadata = json.load(metadata_response)
+
+ assert metadata["resource"] == endpoint
+ assert "https://notfair.co" in metadata["authorization_servers"]
+ assert metadata["resource_name"].startswith("NotFair ")