{"id":27873,"plugin_id":"plugin_asdk_app_6aa944d20a3081919d9f65692616ff4d","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-08T06:23:45.226Z","digest":"b6eb22871f7eab0f6a7bcc21aab0f0e025c4529cee0a9726399ea0a0548d140b","against":null,"payload":{"description":"Read Omneky paid-media performance: ROAS, CTR, CPA, spend, impressions, conversions, trends, daily metrics, and dimension summaries. Use when the user asks how Meta/Facebook, Google, TikTok, LinkedIn, Reddit, Pinterest, or X Ads are performing, or wants HubSpot CRM / Semrush / Ahrefs / GSC lookups for the signed-in brand. Intent keywords: ROAS, CTR, CPA, spend, paid media, Meta ads, Facebook ads, Google Ads, TikTok ads, which ads should I make more of, campaign breakdown, creative leaderboard, trending, HubSpot, Semrush, Ahrefs, GSC, coverage check.","included_files":[],"name":"omneky-analytics","skill_md_contents":"---\nname: omneky-analytics\ndescription: >-\n  Read Omneky paid-media performance: ROAS, CTR, CPA, spend, impressions,\n  conversions, trends, daily metrics, and dimension summaries. Use when the\n  user asks how Meta/Facebook, Google, TikTok, LinkedIn, Reddit, Pinterest,\n  or X Ads are performing, or wants HubSpot CRM / Semrush / Ahrefs / GSC\n  lookups for the signed-in brand. Intent keywords: ROAS, CTR, CPA, spend,\n  paid media, Meta ads, Facebook ads, Google Ads, TikTok ads, which ads\n  should I make more of, campaign breakdown, creative leaderboard,\n  trending, HubSpot, Semrush, Ahrefs, GSC, coverage check.\n---\n\n# Omneky analytics\n\n## Activation analytics\n\nIf the host exposes a skill-activation / analytics hook, call it once per new user request with this skill name; otherwise skip silently. Never invent a tracking tool. Omneky MCP does **not** expose `track_skill_activation`.\n\n## Purpose\n\nRead-only performance and brand-connector reporting for the signed-in user's\nbrands. Answer “how did we do?” and “what should we make more of?” with\nstructured MCP tools only — never invented SQL, warehouse tables, or lift\nendpoints.\n\n## When to use\n\n- How ads performed (ROAS, CTR, CPA, spend, conversions) over a date range\n- Which creatives, campaigns, or channels are winning\n- What rose or fell versus the prior period (also see\n  `omneky-performance-movers`)\n- Coverage check before querying (dates + channels)\n- HubSpot CRM search, Semrush domain/keyword overview, Ahrefs DR /\n  keywords / backlink stats, or Google Search Console analytics\n\n## When not to use\n\n- Launching, pausing, or budgeting ads → `omneky-launch-manage` /\n  `omneky-pause-budget`\n- Generating or editing creatives → `omneky-creative` /\n  `omneky-image-ads` / `omneky-product-video` / `omneky-edit-resize`\n- Catalogue SKU writes → `omneky-catalogue` / `omneky-product-import`\n- Arbitrary SQL — there is **no** public `run_sql_query`\n- Plan / Stripe portal as the primary ask → `omneky-billing`\n\n## OpenAI runtime contract\n\n- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.\n- Prefer native ChatGPT / host widgets and question UI for decisions. Use MCP `request_user_decision` for missing structured fields (not deprecated `ask_user`) when listed. Else follow `omneky-failure-modes` § Approval / plain-chat fallback.\n- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.\n- Approval / Generate turns: end the turn after Approve / Deny (or Generate / Cancel) via host UI or plain chat; mutate only after affirmative Approve / Generate. Never invent a fake widget tool.\n- Never invent tokens; OAuth is host-managed.\n\n## Non-negotiable output / safety contract\n\n- Never invent metrics, score / lift endpoints, or warehouse table names.\n- Always call `check_reporting_data_available` (preferred over deprecated\n  `data_available`) **before** treating empty results as real zeros.\n- `selected_conversion_metric_value` **varies per channel**. Never sum it\n  across channels; group by channel or use a named metric.\n- Prefer `get_performance_breakdown` over deprecated\n  `get_dimension_summary`; prefer `get_performance_movers` over deprecated\n  `get_trending` (aliases may still appear on `tools/list`).\n- Prefer `search_reporting_values` over deprecated\n  `search_dimension_values` when both exist.\n- If brand or date range is missing, ask once. Do not guess `brand_id`.\n- Lead with the answer; name the channel / campaign when filtered.\n- Auth is host OAuth; never ask for a token.\n\n## Staged workflow\n\n### Stage 1 — Session + brand\n\n1. `get_current_user` when `user_id` is required by later tools.\n2. `list_brands` / brand picker if `brand_id` unknown.\n3. `get_brand` / `get_brand_details` as needed.\n\n### Stage 2 — Coverage gate\n\n1. Confirm date range with the user (default a tight recent window if they\n   said “lately” / “this week” — still state the range you will use).\n2. Call `check_reporting_data_available` for brand + dates + channels.\n3. If coverage is empty for the requested slice, report coverage — do not\n   fabricate zeros.\n\n### Stage 3 — Choose the performance tool\n\n| Intent | Tool |\n| --- | --- |\n| What moved vs prior period | `get_performance_movers` |\n| Day-by-day time series | `get_daily_metrics` |\n| Ranked breakdown (campaign / creative / channel / …) | `get_performance_breakdown` |\n| Resolve a name → id for filters | `search_reporting_values` |\n| AI creative / media recommendations | `get_recommendations` (tight window; on `status=timeout` narrow — no identical retry this turn) |\n| Channel spend / budget snapshot | `get_channel_budget` |\n\n### Stage 4 — Interpret safely\n\n1. Summarize winners / losers with evidence from tool payloads only.\n2. Keep conversion metric commentary channel-scoped when using\n   `selected_conversion_metric_value`.\n3. If the user asks what to create or launch next, hand off to\n   `omneky-creative` / `omneky-launch-manage` after the read-out.\n\n### Stage 5 — Brand connectors (reads only)\n\nHubSpot / Semrush / Ahrefs / GSC have **no** connect or disconnect tools on\nthis surface. Check status first. Semrush is **not** in\n`list_connector_statuses` — call `get_semrush_connection_status` directly.\nGSC is included in that fanout.\n\n**HubSpot**\n\n1. `get_hubspot_connection_status`\n2. `hubspot_search_contacts` / `hubspot_search_companies` /\n   `hubspot_search_deals`\n3. Then `hubspot_get_contact` / `hubspot_get_company` / `hubspot_get_deal`\n\n**Semrush**\n\n1. `get_semrush_connection_status`\n2. `get_semrush_domain_overview` / `get_semrush_keyword_overview`\n3. Respect Nexus unit quotas (HTTP 429 / 503 → say capped; do not hammer)\n\n**Ahrefs**\n\n1. `ahrefs_connection_status`\n2. `ahrefs_domain_rating` / `ahrefs_organic_keywords` /\n   `ahrefs_backlinks_stats`\n\n**GSC (organic — not paid media)**\n\n1. `get_gsc_connection_status`\n2. `gsc_list_sites`\n3. `gsc_query_analytics` with a `site_url` from the list\n\n### Stage 6 — Billing adjacent\n\nCompany plan / Stripe portal / credit balance live on prod\n`mcp.omneky.com` when listed. See `omneky-billing` /\n`omneky-credit-balance`. Out of credits for creatives → upgrade plan path\n— never invent prepaid purchase tools.\n\n## Failure boundaries\n\n| Failure | Required response |\n| --- | --- |\n| Empty-looking metrics | Run `check_reporting_data_available`; explain coverage gaps. |\n| Temptation to sum conversions across channels | Refuse; break out by channel. |\n| `get_recommendations` timeout | Narrow dates; no identical retry this turn. |\n| Missing brand / dates | One question; stop. |\n| Invented `run_sql_query` | Refuse; stay on structured tools. |\n| Connector disconnected | Status-first; tell user to connect in brand settings (no public connect tools for HubSpot/Semrush/Ahrefs/GSC). |\n| Semrush / Ahrefs 429 | Report quota; do not tight-loop. |\n| User pivots to launch / gen | Hand off to the matching skill with safety contracts. |\n| Auth failure | `omneky-failure-modes` / host re-OAuth. |\n\n## Worked intake example\n\nUser: “How did Meta and TikTok do last week for Brand X?”\n\n1. Resolve Brand X → `brand_id` via `list_brands` (picker if ambiguous).\n2. `check_reporting_data_available` for last 7 days, channels facebook + tiktok.\n3. If covered: `get_daily_metrics` for trend + `get_performance_breakdown` by\n   creative or campaign (channel-filtered when the tool allows).\n4. Optional movers: `get_performance_movers`.\n5. Report channel-separated conversion commentary; never sum\n   `selected_conversion_metric_value` across Meta + TikTok.\n6. Offer: recommendations (`get_recommendations`) or hand off to creative /\n   pause-budget if they ask what to do next.\n\n## Sibling map\n\n| Need | Skill |\n| --- | --- |\n| Movers-only | `omneky-performance-movers` |\n| Credits / plan | `omneky-billing` / `omneky-credit-balance` |\n| Launch / pause | `omneky-launch-manage` / `omneky-pause-budget` |\n| Failures | `omneky-failure-modes` |\n| First-run | `omneky-getting-started` |\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}