Skill instructions
omneky-ab-tests4.83 KB
View saved version →
---
name: omneky-ab-tests
description: >-
Create or measure an Omneky paid-media A/B test. Use for A/B
test creation (one hypothesis, one variable, precommitted
plan, launch live or paused as the user chooses) or A/B test measurement (z-test, CI,
power, SRM, interim peek with no verdict, refuse a thin
winner). Do not use for generic ROAS tables
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), first-run onboarding
(omneky-onboarding), agency (omneky-agency), weekly marketing
plans (omneky-marketing-plan), generating creatives
(omneky-image-ads, omneky-product-video, omneky-avatar-ugc),
or credit balance (omneky-billing). Keywords: A/B test,
ab test create, ab test measurement, which variant won,
significance, two-proportion z-test, MDE, SRM, interim peek,
underpowered, commercially meaningful, budget split.
---
# A/B tests
Use this when the user wants to set up an A/B test or read out which
variant won. One job: own the test plan and the readout.
Gate every tool on this session's `tools/list`. If a step's tool is
missing, say so and point to the Omneky app.
Plan fields: [handoff-contract](../_shared/references/handoff-contract.md).
Formulas: [ab-test-statistics](../_shared/references/ab-test-statistics.md).
Sourced ids: [preconditions](../_shared/references/preconditions.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Brief: [creative-brief](../_shared/references/creative-brief.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
Step detail: [playbook](references/playbook.md) (Hard rules, Create, Measure).
## Goal
Create a one-variable test with a precommitted plan (live or paused is
the user's choice in the host), or
measure it with a two-proportion z-test and a marketer verdict.
## When to use
- Create an A/B test, measure one, "which variant won", significance,
stop rule, interim peek, SRM, MDE
## When not to use
- Generic ROAS table → `omneky-analytics-and-catalogue`
- Launch without a test plan → `omneky-launch-and-connect`
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which |
| Channel | `list_connections` (`connector`) | Connect or managed |
| Budget floor | `get_launch_requirements` | Do not launch under the floor |
| Variants | prior creative handoff | Owning creative skill |
| Baseline | `get_performance_summary` with `date_range` | State an assumed `baseline_rate` |
| Coverage (measure) | `get_performance_summary` (`include_coverage=true`) | Do not declare a winner |
| Metrics (measure) | `get_performance_breakdown` / `get_performance_summary` | Narrow the window |
## Flow
**Create**
1. Write one hypothesis with one changed variable.
2. Record metric, MDE, duration (`horizon`) and stop rule before launch.
3. Budget at or above the floor. One ad group with one ad per variant
does not guarantee an even spend split (delivery is auction-driven);
say so. For an even split, use one ad group (or campaign) per variant
with equal budgets, or the platform's A/B / split-test feature.
4. Launch through `omneky-launch-and-connect`, live or paused as the
user chose (the host confirms).
**Measure**
1. Confirm coverage for the window; empty is missing data, not zero.
2. Run the setup check on every look (broken setup; SRM only for a
randomized planned allocation, not default auction delivery). If it
fails, give the verdict Invalid at once and recommend a pause.
Never mutate here.
3. Before `horizon`, report INTERIM with no statistical verdict.
4. At `horizon`, run the z-test and give one verdict: Winner, Not
commercially meaningful, Inconclusive, or No detectable difference.
5. Refuse a winner when the sample is thin.
## Failure and recovery
Auth / 401 → `omneky-getting-started-and-failures` (host OAuth).
Empty reporting → `ge
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
omneky-agency3.89 KB
View saved version →
---
name: omneky-agency
description: >-
Agency multi-brand Omneky work. Use for a weekly cross-brand
report (per-client summaries) or a multi-brand campaign rollout
with per-brand confirmation. Never silent-switch brands. Do not
use for a single-brand ROAS table
(omneky-analytics-and-catalogue), first-run onboarding
(omneky-onboarding), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests), or
credit balance (omneky-billing). Keywords: weekly cross-brand
report, per-client summary, multi-brand rollout, agency
clients, all brands this week.
---
# Agency multi-brand work
Use this when an agency operator wants numbers or a rollout across
several client brands. One job: cross-brand reports and rollouts,
one brand at a time. A single brand goes to
`omneky-analytics-and-catalogue` or the matching creative or launch skill.
Gate every tool on this session's `tools/list`; a missing tool → the
Omneky app. Never ask for internal ids.
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids: [preconditions](../_shared/references/preconditions.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
## Goal
Per-client numbers and a safe multi-brand rollout. Never switch
brands silently.
## When to use
- Weekly cross-brand / per-client report
- Multi-brand campaign rollout
- "All my clients this week"
## When not to use
- One brand's ROAS / movers → `omneky-analytics-and-catalogue`
- First-run setup → `omneky-onboarding`
- Credit ledger → `omneky-billing`
- Sign-in only → `omneky-getting-started-and-failures`
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Session | `get_account` | Host OAuth reconnect |
| Brand list | `list_brands` | No brands → Omneky app. Do not invent |
| Reporting coverage | `get_performance_summary` (`include_coverage=true`) per `brand_id` | Skip that brand; empty is not zero |
| Metrics | `get_performance_breakdown` / `get_performance_summary` / `get_performance_movers` | Narrow the window; do not invent ROAS |
| Launch apply | matching `launch_*` tool / `set_ad_budget` / `set_ad_status` | Name the brand first; the host confirms. Status as asked |
## Flow
### weekly-cross-brand-report
1. `list_brands`. Show the name + id list. Confirm the set
(or the named subset) before any metric call.
2. For each confirmed `brand_id`:
- `get_performance_summary` (`include_coverage=true`)
- `get_performance_breakdown` (winners / spend)
- `get_performance_movers` when they asked what changed
- `get_performance_summary` when they asked for the chart
3. Thin samples: "too little data to conclude" + the numbers.
4. Deliverable: one short card per client (spend, ROAS, CTR,
mover, recommendation) and a one-line roll-up. Confidence =
coverage + sample size per brand.
### multi-brand-rollout
1. Resolve the brand set from `list_brands`. One brand per cycle.
2. Name the brand and id before generating or launching for it. Never reuse one brand's id for another.
3. Creative / launch follow those skills. Set `campaign_spec.status_on_launch` as asked (no server default).
Pass each brand's own `brand_id`.
4. Deliverable: per-brand status table (quoted, generated,
launched `PAUSED`, skipped).
## Failure and recovery
Auth / 401 → `omneky-getting-started-and-failures`.
One brand empty → skip it; do not pull another brand's rows
to fill the card.
`status=timeout` → narrow that brand's window; do not retry
the identical call this turn.
`credit_insufficient` → stop that brand and state the shortfall
(`omneky-billing`). Carry on with the other brands.
## Gaps
No agency inbox, no organic scheduler, no cross-account
login. See
[capability-gaps](../_shared/references/capability-gaps.md).
omneky-analytics7.83 KB
View saved version →
---
name: omneky-analytics
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.
---
# Omneky analytics
## Activation analytics
If 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`.
## Purpose
Read-only performance and brand-connector reporting for the signed-in user's
brands. Answer “how did we do?” and “what should we make more of?” with
structured MCP tools only — never invented SQL, warehouse tables, or lift
endpoints.
## When to use
- How ads performed (ROAS, CTR, CPA, spend, conversions) over a date range
- Which creatives, campaigns, or channels are winning
- What rose or fell versus the prior period (also see
`omneky-performance-movers`)
- Coverage check before querying (dates + channels)
- HubSpot CRM search, Semrush domain/keyword overview, Ahrefs DR /
keywords / backlink stats, or Google Search Console analytics
## When not to use
- Launching, pausing, or budgeting ads → `omneky-launch-manage` /
`omneky-pause-budget`
- Generating or editing creatives → `omneky-creative` /
`omneky-image-ads` / `omneky-product-video` / `omneky-edit-resize`
- Catalogue SKU writes → `omneky-catalogue` / `omneky-product-import`
- Arbitrary SQL — there is **no** public `run_sql_query`
- Plan / Stripe portal as the primary ask → `omneky-billing`
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- 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.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Never invent metrics, score / lift endpoints, or warehouse table names.
- Always call `check_reporting_data_available` (preferred over deprecated
`data_available`) **before** treating empty results as real zeros.
- `selected_conversion_metric_value` **varies per channel**. Never sum it
across channels; group by channel or use a named metric.
- Prefer `get_performance_breakdown` over deprecated
`get_dimension_summary`; prefer `get_performance_movers` over deprecated
`get_trending` (aliases may still appear on `tools/list`).
- Prefer `search_reporting_values` over deprecated
`search_dimension_values` when both exist.
- If brand or date range is missing, ask once. Do not guess `brand_id`.
- Lead with the answer; name the channel / campaign when filtered.
- Auth is host OAuth; never ask for a token.
## Staged workflow
### Stage 1 — Session + brand
1. `get_current_user` when `user_id` is required by later tools.
2. `list_brands` / brand picker if `brand_id` unknown.
3. `get_brand` / `get_brand_details` as needed.
### Stage 2 — Coverage gate
1. Confirm date range with the user (default a tight recent window if they
said “lately” / “this week” — still state the range you will use).
2. Call `check_reporting_data_available` for bra
Preview of the first 4,000 characters. Read full instructions →
omneky-analytics-and-catalogue5.44 KB
View saved version →
---
name: omneky-analytics-and-catalogue
description: >-
Call get_products, import_product_from_url, and
get_products by name (list my products, import this
product URL, SKU, PDP). Also winning ads, ROAS, CTR, weekly
performance report, HubSpot, and read-only budget
reallocation. Do not use for first-run onboarding
(omneky-onboarding), agency cross-brand (omneky-agency),
competitor positioning (omneky-competitor-analysis), A/B
tests (omneky-ab-tests), weekly marketing plans
(omneky-marketing-plan), generating creatives, launch
(omneky-launch-and-connect), or credit balance
(omneky-billing). Keywords: list my products, import this URL,
catalogue, SKU, PDP, which ads should I make more of, winning
ads, ROAS drop, CPA drop, CTR, weekly performance report,
fatigue refresh, budget reallocation, waste pruner, audience
targeting, target CPA, HubSpot attribution, ABM, Semrush,
Ahrefs.
---
# Ad performance and product catalogue
Use this when the user asks how their ads perform, which ads to make
more of, or wants to list or import products. One job: ranked
evidence and catalogue records. No render, no spend change.
Call tools by their exact names when they are on `tools/list`.
Catalogue tools are optional; if they are missing, say that
capability isn't available on this connector.
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
<!-- host:begin name="scan-tools-routing" -->
Acceptance gates (for a later creative): [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Structured brief (for a later creative): [creative-brief](../_shared/references/creative-brief.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
<!-- host:end -->
## Goal
Ranked evidence, catalogue records, and connector reads.
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which; do not invent |
| Coverage | `get_performance_summary` (`include_coverage=true`) | Say there is no imported data; do not report zeros |
| Winners / diagnosis | `get_performance_breakdown` / `get_performance_summary` / `get_performance_movers` | Narrow the window |
| Product | `get_products` when listed | Import via `import_product_from_url` (`url`), then `save_imported_product` (`draft_id`). If catalogue tools are not on `tools/list`, say that capability isn't available on this connector |
| HubSpot | `list_connections` (`connector="hubspot"`) | Skip CRM joins; say disconnected |
| Semrush / Ahrefs | matching status tool | Skip that source |
| Budget apply | (read-only here) | `omneky-launch-and-connect` (`set_ad_budget` / `set_ad_status`; the host confirms) |
## Flow
1. Resolve the brand and confirm coverage for the window.
2. Run the recipe the user asked for: winners, fatigue, weekly
report, ROAS/CPA drop, waste pruner (evidence only), targeting
evidence, target-CPA plan, HubSpot attribution, ABM brief, or
catalogue import. Details: [playbook](references/playbook.md).
3. Lead with the answer (ROAS, CPA, CTR, spend, lift), one
recommendation, and confidence.
4. When handing off to creative or a plan-driven launch, attach
`source_evidence` (metric, window, channel, ad ids, sample size)
and `approved_claims`, each with its source. Never invent a claim.
## When to use
- "Which ads should I make more of?", winning ads, next batch brief
- ROAS, CTR, CPA, spend, movers, daily paid-media charts
- List products / SKUs, or import a product URL before an ad
(only when those catalogue tools appear on `tools/list`)
## When not to use
- Competitor positioning / messaging gaps
(`omneky-competitor-analysis`)
<!-- host:begin name="ab-tests-when-not" -->
- A/B test create or "which variant won" (`omneky-ab-tests`)
<!-- host:end -->
-
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
omneky-avatar-ugc5.3 KB
View saved version →
---
name: omneky-avatar-ugc
description: >-
Create Omneky avatar and UGC talking-head video ads, including
ugc-review (truthful claims only), ugc-unboxing (reveal arc),
ugc-tutorial (demonstrable steps), and ugc-website-demo (accurate
UI evidence). Use for an avatar video or talking-head ad. Do not
use for still image ads (omneky-image-ads), product video
commercials (omneky-product-video), voice or video clone
(omneky-voice-and-video-clone), edit or resize
(omneky-edit-and-resize), ROAS-only
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
weekly plans (omneky-marketing-plan), first-run onboarding
(omneky-onboarding), agency (omneky-agency), launch/connect
(omneky-launch-and-connect), or credit-balance-only
(omneky-billing). Keywords: avatar video, UGC talking-head,
talking-head ad, founder video, spokesperson, localized ad
set, ugc-product, ugc-review, ugc-unboxing, ugc-tutorial,
ugc-website-demo, testimonial avatar.
---
# Avatar and UGC talking-head ads
Use this when the user wants a talking-head ad: founder or
spokesperson, a localized voice, or a UGC genre (review, unboxing,
tutorial, website demo). One job: avatar and UGC video ads.
Gate on `find_avatars_and_voices` (`include="filters"`), `find_avatars_and_voices` (`include="avatars"`), `find_avatars_and_voices` (`include="voices"`) and
`generate_avatar_video_ad` being on `tools/list`; if a step's tool is
missing, say so and point to the Omneky app.
Step detail: [playbook](references/playbook.md) (hard rules, avatar
video ad, UGC genre recipes).
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
Quote, retry, and polls: [creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Structured brief: [creative-brief](../_shared/references/creative-brief.md).
QA and cheapest repair: [media-qa-and-repair](../_shared/references/media-qa-and-repair.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
## Goal
Ship a talking-head: founder/spokesperson, localized voice, or a UGC genre. On-screen person: a stock avatar, or a brand-asset image of a person who has consented to appear. Voice clone is a sibling skill.
## When to use
- Avatar / UGC / founder / spokesperson / localized talking-head / ugc-product / review / unboxing / tutorial / website-demo
## When not to use
- Clone a winning video → `omneky-voice-and-video-clone`
- Faceless product video → `omneky-product-video`
- Virtual try-on → decline (gap)
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which |
| Avatars | `find_avatars_and_voices` (`include="filters"`) + `find_avatars_and_voices` (`include="avatars"`) | Custom HTTPS face allowed |
| Voices / locale | `find_avatars_and_voices` (`include="voices"`) | Omit `voice_id`, or `clone_voice` after consent in `omneky-voice-and-video-clone` |
| Product still | `get_products` | Omit `product_image_url` |
| Cost | no quote tool; state the cost and proceed | Report credits actually charged (`credits_charged`) |
| Generate | `generate_avatar_video_ad` | Say avatar video is not on this connector |
## Flow
1. Fill the brief. Take `approved_claims` from the handoff, product
page, catalogue, or the user's words; leave out any claim you
cannot ground. Pass `product_id` for product ads.
Otherwise: brand-general work passes `brand_id` only.
Add `source_evidence` only for performance-informed work.
2. Pick the face and the voice with one
`find_avatars_and_voices` call (stock or custom portraits, voices;
one voice per language for localized).
3. State the cos
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
omneky-billing4.29 KB
View saved version →
---
name: omneky-billing
description: >-
Call get_account by name for remaining Omneky prepaid ad
credits. Also plan entitlements and credit history. Use when the user asks how many ad credits remain,
credit balance, credit history, out of credits, which plan,
or card on file. Do not use for campaign spend/ROAS
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
first-run onboarding (omneky-onboarding), agency
(omneky-agency), weekly marketing plans
(omneky-marketing-plan), creating ads, launching
campaigns (omneky-launch-and-connect), or collecting card numbers.
Keywords: ad credits, credit balance, remaining credits, how many
credits, credit history audit, top-up, plan, card on file.
---
# Ad credits and plan (read only)
Use this when the user asks how many ad credits remain, what they
have spent credits on, which plan they are on, or what card is on
file. One job: read-only billing answers.
There is no upgrade, portal or checkout tool, and no payment links.
<!-- host:begin name="stripe-redirect" -->
Never collect a PAN. Never invent a purchase or upgrade tool, and never
send payment, checkout or portal links. The user adds credits or
changes plan in the Omneky app.
<!-- host:end -->
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids: [preconditions](../_shared/references/preconditions.md).
<!-- host:begin name="scan-tools-routing" -->
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
<!-- host:end -->
## Goal
Show credits, the shortfall if any, and the credit history.
## When to use
- Remaining credits, credit history, which plan, card on file
- `credit_insufficient` after a creative or launch
## When not to use
- Campaign spend, ROAS, or daily metrics (analytics skill)
- Weekly marketing plans (`omneky-marketing-plan`)
<!-- host:begin name="billing-creative-when-not" -->
- Creating ads (`omneky-image-ads`) or launching them
(`omneky-launch-and-connect`)
<!-- host:end -->
- Collecting a card number
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Balance | `get_account` | Say the tool is missing; Omneky app |
| Ledger | `get_account` (`include_credit_history=true`) | Skip the audit line |
## Call by name
Call only names on this session's `tools/list`.
| User ask | Tool |
|---|---|
| how many credits remain | `get_account` |
| credit grants and usage ledger | `get_account` (`include_credit_history=true`) |
| plan and credit snapshot | `get_account` |
| which plans exist, buy credits, change plan | no tool: the user does it on omneky.com |
| card brand and last4 | `get_account` |
| company record | `get_account` |
## Flow
1. Call the tool for the ask. Lead with the number, the shortfall if
any, and one next step.
2. For "what will this cost": there is no quote tool. Say a paid run
uses credits and its result reports `credits_charged`; the amount
shows in `get_account` (`include_credit_history=true`). Never invent a figure.
3. Present `get_account` (`include_credit_history=true`) as a dated ledger, not the balance.
4. For plans, plan changes or top-ups, say the user buys credits or
changes plan on omneky.com (Ads Central).
## credit_insufficient
Nothing started and nothing was charged. Tell the user `required` and
`balance` in one line and that credits are added in the Omneky app.
Do not retry until they say they have enough.
<!-- host:begin name="creative-quote-rules" -->
Quote rules for creative jobs:
[creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
<!-- host:end -->
## Failure and recovery
Auth / 401 → `omneky-getting-started-and-failures` (host OAuth).
A billing tool is missing → say so; the user checks in the Omnek
Preview of the first 4,000 characters. Read full instructions →
omneky-catalogue5.25 KB
View saved version →
---
name: omneky-catalogue
description: >-
Maintain the Omneky brand product catalogue: list products, fetch details,
create or update SKUs, and import a product-page URL. Use when the user
wants to add, update, or inspect catalogue products before a paid-media
launch or creative. Intent keywords: list my products, turn this product
URL into, product catalogue, catalog, SKU, PDP, scrape product, import URL,
product images, merchandise, upsert product.
---
# Omneky product catalogue
## Activation analytics
If 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`.
## Purpose
Read and write the brand product catalogue that grounds product-specific
creatives and launches. There is **no product-delete tool** on this public
surface.
## When to use
- List or inspect products for a brand before a launch or creative
- Add a product by hand (name, description, images, URL)
- Update an existing completed product or its PDP URL
- Import a single product page (identify → scrape → confirm → finalize)
## When not to use
- ROAS / CTR / spend → `omneky-analytics`
- Launching the product onto Meta / Google / TikTok →
`omneky-launch-manage` after `product_id` + imagery exist
- Generating image/video from the product → `omneky-creative` /
`omneky-image-ads` / `omneky-product-video`
- Listing / category URLs without classify — always
`identify_product_from_url` first (see `omneky-product-import`)
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- 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.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Prefer numeric `brand_id` when thumbnails matter.
- Confirm create / update fields with the user before writes when they asked
to confirm, or when fields are ambiguous — use `request_user_decision` or
a host Approve widget; end turn after the widget.
- Scrape drafts: complete with `finalize_scraped_product`, **not**
`upsert_brand_product`.
- `scrape_product_from_url` creates a **new draft** each successful start —
do not spam scrapes.
- No public product-delete — say so if asked; do not invent one.
- Do not launch or charge creative credits from this skill.
## Staged workflow
### Stage 1 — Resolve brand
1. If `brand_id` unknown: `list_brands` → picker → `get_brand_details` when
logo / colors / `company_id` are needed.
### Stage 2 — Read
1. List: `list_brand_products` (`brand_id`).
2. One product: `get_product_details` (also accepted: `fetch_product_details`)
with `brand_id` + `product_id`.
### Stage 3 — Create or update (manual)
1. New product: `create_product` **or** `upsert_brand_product` /
`update_brand_product` without `product_id`. Confirm fields first.
2. Update completed product: `upsert_brand_product` with `product_id`. Pass
current `product_name` / `product_description` when leaving them unchanged.
3. URL only: `update_product_url`.
### Stage 4 — Import from URL (delegate detail)
Follow `omneky-product-import` stages, summarized:
1. `identify_product_from_url` — skip scrape on listing/category pages.
2. `scrape_product_from_url` — if `status=pending`, retry later same
`brand_id` + url; no tight loop this turn.
3. Confirm fields + selected images with the user (widget / one
Preview of the first 4,000 characters. Read full instructions →
omneky-channel-connect3.12 KB
View saved version →
---
name: omneky-channel-connect
description: >-
Connect Meta, Google, TikTok, LinkedIn, Reddit, Pinterest, or X ad
accounts for a brand via OAuth URL and link_ad_channel_account. Keywords:
connect ads, link ad account, Facebook page, channel OAuth, Pinterest,
twitter, TikTok ads connect.
---
# Connect ad channels
## Activation analytics
If 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`.
## Purpose
Focused paid-media channel attachment (OAuth URL → authorized accounts →
link). Prefer `omneky-self-connect` when OpenAI Ads / PostHog / Drive are
also in scope.
## When to use
- User asks to connect Meta / Google / TikTok / LinkedIn / Reddit /
Pinterest / X Ads only
- Launch blocked by disconnected channel
## When not to use
- OpenAI Ads / PostHog / Drive → `omneky-self-connect`
- HubSpot / Semrush / Ahrefs / GSC connect (not on this surface)
- Launch / pause / budget mutations → launch-manage / pause-budget skills
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- 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.
- Never invent tokens; OAuth is host-managed. Never ask the user to paste a JWT or API key into chat.
## Non-negotiable output / safety contract
- X Ads wire name is `twitter`, never `x`.
- Do not claim connected until status re-check succeeds.
- Never invent API keys for paid-media channels — use
`get_channel_connect_url` OAuth.
## Staged workflow
### Stage 1 — Brand + status
1. Resolve brand (`list_brands` / picker) if needed.
2. `get_channel_connection_status` (and `get_pinterest_connection_status`
when Pinterest). Optional snapshot: `list_connector_statuses`.
### Stage 2 — OAuth
1. `get_channel_connect_url` for the channel.
2. Hand URL to user; end turn while they complete browser OAuth.
### Stage 3 — Link
1. `list_authorized_ad_accounts`.
2. Meta: also `list_authorized_facebook_pages` when needed.
3. Confirm selection → `link_ad_channel_account`.
4. Re-check status.
### Stage 4 — Next
Offer launch via `omneky-launch-manage` (paused by default) or Meta path
`omneky-meta-launch`.
## Failure boundaries
| Failure | Required response |
| --- | --- |
| Still disconnected after OAuth | Re-check once; ask user to retry OAuth; do not invent tokens. |
| Wrong wire name `x` | Use `twitter`. |
| Multiple accounts | Confirm before `link_ad_channel_account`. |
| Non–paid-media connector | Hand off to `omneky-self-connect` or analytics (reads-only). |
omneky-competitor-analysis3.82 KB
View saved version →
---
name: omneky-competitor-analysis
description: >-
Analyze competitors and brand positioning with Omneky. Use for
competitor analysis, positioning, messaging angles, messaging
gaps, or a competitive brief that cites Semrush, Ahrefs,
analyze_brand, or a scraped PDP. Every claim must cite its
evidence source. Do not use for ROAS / winning-ads tables
(omneky-analytics-and-catalogue), A/B tests (omneky-ab-tests),
first-run onboarding (omneky-onboarding), agency
(omneky-agency), weekly marketing plans
(omneky-marketing-plan), generating creatives,
launch/connect (omneky-launch-and-connect), or credit balance
(omneky-billing). Keywords: competitor analysis, positioning,
messaging angles, messaging gaps, competitive brief,
keyword gaps, domain rating, backlinks, Semrush
competitor, Ahrefs competitor.
---
# Competitor analysis
Use this when the user asks how competitors position themselves,
which angles to test, or where keyword and backlink gaps are. One
job: cited positioning, angles, and gaps that feed a creative brief.
ROAS tables stay in `omneky-analytics-and-catalogue`.
Gate every tool on `tools/list`; a missing tool → the Omneky app.
Step detail: [playbook](references/playbook.md) (hard rules, path).
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids: [preconditions](../_shared/references/preconditions.md).
<!-- host:begin name="scan-tools-routing" -->
Acceptance gates (for a later creative): [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Structured brief (output of this skill): [creative-brief](../_shared/references/creative-brief.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
<!-- host:end -->
## Goal
Cite positioning, keyword/query gaps, and domain-rating/backlink checks that feed a creative brief.
## When to use
- Competitor analysis, positioning, messaging gaps, Semrush/Ahrefs keyword gaps, domain rating / backlinks
## When not to use
- Paid ROAS tables → `omneky-analytics-and-catalogue`
- Meta Ad Library competitor ads → decline (gap)
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which |
| Analysis | `analyze_brand` | Call it |
| Semrush | `list_connections` (`connector="semrush"`) | Skip Semrush |
| Ahrefs | `list_connections` (`connector="ahrefs"`) | Skip Ahrefs |
| PDP copy | `import_product_from_url` (`url`) | Ask for one product URL |
## Flow
1. Check each source's connection status (Semrush, Ahrefs,
HubSpot). Skip a disconnected source.
2. Pull both sides of every comparison before stating a gap.
3. Cite every claim with its source.
4. Lead with the angles worth testing, then the gaps, then confidence
per source. Hand the brief to the creative skill.
## Failure and recovery
Auth / 401 → `omneky-getting-started-and-failures` (host OAuth).
Empty reporting → `get_performance_summary` (`include_coverage=true`); empty is not zero.
`credit_insufficient` → nothing charged; state balance vs required
(`omneky-billing`). No payment links.
`needs_user_decision` → fill the missing detail and call again; ask in plain chat only if you cannot. Never dump JSON.
Missing tool → this session may run an older published app snapshot: look
the name up in [tool-name-fallbacks](../_shared/references/tool-name-fallbacks.md)
and call the older name if that one is on `tools/list`. If neither is
listed, say so; Omneky app. Do not invent it.
Never ask for internal ids. Never silent-switch `brand_id`.
<!-- host:begin name="capability-gaps-link" -->
## Gaps
Decline social inbox, landing pages, subtitle burn-in, email/SMS,
organic scheduling, Ad Library ads, try-on, and website builder
([capability-gaps](../_shared/references/capability-gaps.md)).
<!-- host:end -->
Referenced files: 1 — file references are metadata, not package contents.
omneky-creative11.6 KB
View saved version →
---
name: omneky-creative
description: >-
Generate, edit, or resize Omneky paid-media image and video ads, grounded
in the brand product catalogue when the brief is product-specific. Use
when the user wants a new image ad, a multi-scene product video, an edit
of an existing creative, or another aspect ratio (9:16, 4:5, Stories,
Reels). Intent keywords: turn this product URL into video ads, generate
image ads for this product, image ad, product video, creative, catalogue,
edit ad, resize ad, Meta creative, TikTok video, Reels, credits.
---
# Omneky creative
## Activation analytics
If 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`.
## Purpose
Paid-media image and multi-scene product video generation plus sync edit /
resize on `https://mcp.omneky.com/mcp`. Ground product-specific briefs in the
catalogue. Never claim success without a completed status or sync result URL.
## When to use
- New static image ads or multi-scene product video commercials
- Edit copy, layout, or style on an existing finished ad
- Resize a paid-media creative into another placement (9:16, 4:5, 16:9)
- Product-specific briefs that need the brand catalogue first
## When not to use
- Launching the finished creative → `omneky-launch-manage` after
`register_creative_for_launch` (Approve before launch)
- ROAS / CTR → `omneky-analytics`
- Creating / updating catalogue products → `omneky-catalogue`
- Central-only names (`trigger_ac_ad_generation`,
`trigger_multi_scene_product_video`, sibling video triggers, UGC,
`edit_video`, `trigger_product_video_v2`) — clients use public aliases below
- Thin single-path asks may use `omneky-image-ads` /
`omneky-product-video` / `omneky-edit-resize` instead
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- Generate / Cancel / Approve turns: end the turn after the choice UI (or plain chat); mutate only after affirmative Generate / Approve.
- Never invent tokens; OAuth is host-managed.
- Prefer runtime `tools/list` when it differs from skill hardcoding.
## Non-negotiable output / safety contract
- **Credit callout before paid generation**: image ads typically **~5**
credits; multi-scene product videos typically **~30**, charged when the job
is submitted. Show Generate / Cancel (host UI preferred; else plain chat).
Billing gating: `omneky-failure-modes` § Billing tools absent —
call balance only when listed; if absent, state operational cost, proceed
after user confirms, rely on `credit_insufficient` as the hard gate.
- `credit_insufficient` ⇒ render **did not start** — relay that; do not retry;
upgrade path via billing skill **when those tools are listed**.
- Never claim success without `get_generation_status` completion (async) or a
sync tool’s returned URL (`edit_image` / `resize_ad` / `resize_image`).
- On hosts with MCP Apps widgets (ChatGPT): the widget owns
`poll_image_generation` / `poll_video_generation` / `sync_generation_group`
— do **not** call those as the agent and do not loop
`get_generation_status` in one turn. On text-only hosts: stop after
submit; on the next user message call `get_generation_status(job_id,
kind=…)` **once**.
- Ask whether the creative is for a **specific product** or the **brand in
general**. Product-specific: catalogue grounding. Brand-general:
`get_brand_details` assets only.
- Unique `gpt_ad_gen_id` per image job (`<short-slug>-<uuid4>`), nev
Preview of the first 4,000 characters. Read full instructions →
omneky-credit-balance4.07 KB
View saved version →
---
name: omneky-credit-balance
description: >-
Check prepaid creative credit balance and history before paid generation.
Keywords: credits, credit balance, out of credits, credit history,
usd_per_credit, credit_insufficient.
---
# Credit balance
## Activation analytics
If 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`.
## Purpose
Lightweight prepaid-credit gate before image / video generation. Balance and
history only; upgrades live in `omneky-billing`.
## When to use
- Before `generate_image_ad` / `generate_product_video` / paid `edit_image`
(not for uncharged `resize_ad` / `resize_image`)
- After `credit_insufficient`
- User asks “how many credits do I have?”
## When not to use
- Full plan / portal / checkout flows as the primary task → `omneky-billing`
- Campaign budgets / media spend → `get_channel_budget` via analytics /
launch-manage (different concept)
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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 `omneky-failure-modes` § Approval / plain-chat fallback.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- Generate / Cancel turns: end the turn after the choice UI (or plain chat); mutate only after affirmative Generate.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Confirm `get_account_credit_balance` (and related) appear on `tools/list`
first (`omneky-failure-modes` § Billing tools absent).
- **If present**: call balance before paid creative jobs when unknown.
- **If absent**: skip the balance call; state operational cost (image ~5 /
video ~30); proceed after user confirms intent; rely on
`credit_insufficient` as the hard gate. Never invent a balance number.
- Operational credit callouts are OK — not subscription promo copy.
- On `credit_insufficient`, the job **did not start** — do not retry generate;
hand off to `omneky-billing` only when upgrade/portal tools are listed;
else point to Omneky app / settings.
- Never invent Nexus debit / auto-topup tools. Never collect a PAN.
- Resize is not charged — do not gate `resize_ad` / `resize_image` on
balance (`omneky-failure-modes` § Resize / edit charge).
## Staged workflow
### Stage 1 — Presence + balance
1. If `get_account_credit_balance` is **absent** from `tools/list`: state
operational cost (~5 image / ~30 video), return to creative skill after
user confirms intent; skip Stages 2–3 balance reads.
2. If present: call it → report `credit_balance` and `usd_per_credit` when
present.
### Stage 2 — Optional history
1. Only if `get_credit_history` is listed: recent grants / usage (capped
rows).
### Stage 3 — Gate or upgrade
1. If balance tools were absent: creative path uses operational callout +
`credit_insufficient` hard gate.
2. If balance is sufficient for the intended job, return to
`omneky-creative` / `omneky-image-ads` / `omneky-product-video` /
`omneky-edit-resize` with a credit callout (Generate / Cancel; host UI
or plain chat) before submit. Do not gate uncharged resizes.
3. If insufficient and upgrade tools are listed: `omneky-billing`
(`list_available_plans` + `start_plan_upgrade` or
`create_billing_portal_session`). If upgrade tools absent: Omneky app /
settings.
## Failure boundaries
| Failure | Required response |
| --- | --- |
| Tool missing | Say unavailable; Omneky app / settings; never invent balance (`omneky-failure-modes` § Billing tools absent). |
| `credit_insufficient` | No retry; billing upgrade path if tools present; else Omneky app. |
| User confuses cr
Preview of the first 4,000 characters. Read full instructions →
omneky-edit-and-resize3.93 KB
View saved version →
---
name: omneky-edit-and-resize
description: >-
Edit a finished Omneky image or resize it for a placement. Use for
an edit, resize, Reels, Stories, 1:1, 4:5, or 9:16. Do not use for
a brand-new image concept (omneky-image-ads), product video
(omneky-product-video), avatar/UGC (omneky-avatar-ugc), voice or
video clone (omneky-voice-and-video-clone), ROAS-only
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
weekly plans (omneky-marketing-plan), first-run onboarding
(omneky-onboarding), agency (omneky-agency), launch/connect
(omneky-launch-and-connect), or credit-balance-only
(omneky-billing). Keywords: edit ad, resize ad, Reels, Stories,
1:1, 4:5, 9:16, hero to every placement.
---
# Edit and resize
Use this when the user wants a finished still changed or resized for
other placements (Reels, Stories, 1:1, 4:5, 9:16). One job: edit and
resize existing stills. A new concept is `omneky-image-ads`.
Gate on `edit_image`, `resize_creative` and `resize_creative` (`width` + `height`) being on
`tools/list`; a missing tool → the Omneky app.
Step detail: [playbook](references/playbook.md) (hard rules, edit,
resize).
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
Quote, retry, and polls: [creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
QA and cheapest repair: [media-qa-and-repair](../_shared/references/media-qa-and-repair.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
## Goal
Fix a finished still or explode one hero into every channel size.
## When to use
- Edit headline, resize, hero-to-every-placement, Reels / Stories / 1:1 / 4:5 / 9:16
## When not to use
- New concept → `omneky-image-ads`
- Video edit → decline (gap)
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| HTTPS still | prior generate URL | Ask for a public link; no upload |
| Cost | no quote tool; state the cost and proceed | Report credits actually charged (`credits_charged`) |
| Edit | `edit_image` | Say edit is not on this connector |
| Resize | `resize_creative` / `resize_creative` (`width` + `height`) | Say resize is not on this connector |
## Flow
1. Resolve the finished image URL from the conversation or
`list_creatives`.
2. Edit: `edit_image` with `images` (HTTPS URLs) and a `prompt`.
Edited text must match the requested wording exactly.
New claims come only from `approved_claims`; plain edits need no
`source_evidence`.
3. Resize: `resize_creative` once per remaining ratio.
4. State the cost and proceed; these tools charge on each call, so
never auto-retry one.
5. Check each result against the image gates and deliver one URL per
placement.
## Failure and recovery
Auth / 401 → `omneky-getting-started-and-failures` (host OAuth).
Empty reporting → `get_performance_summary` (`include_coverage=true`); empty is not zero.
`credit_insufficient` → nothing charged; state balance vs required
(`omneky-billing`). No payment links.
`needs_user_decision` → fill the missing detail and call again; ask in plain chat only if you cannot. Never dump JSON.
Missing tool → this session may run an older published app snapshot: look
the name up in [tool-name-fallbacks](../_shared/references/tool-name-fallbacks.md)
and call the older name if that one is on `tools/list`. If neither is
listed, say so; Omneky app. Do not invent it.
Never ask for internal ids. Never silent-switch `brand_id`.
## Gaps
Decline social inbox, landing pages, subtitle burn-in, email/SMS,
organic scheduling, Ad Library ads, try-on, and website builder
([capability-gaps](../_shared/references/capability-gaps
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
omneky-edit-resize3.79 KB
View saved version →
---
name: omneky-edit-resize
description: >-
Edit an existing Omneky creative or resize it for Stories, Reels, 9:16,
4:5, or 16:9. Resizes are not charged (adapt an already-paid creative).
Keywords: edit ad, resize ad, Stories, Reels, aspect ratio, outpaint,
edit_image, resize_ad, uncharged resize.
---
# Edit and resize
## Activation analytics
If 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`.
## Purpose
Synchronous edit / resize of **existing** finished creatives. No async
`job_id` polling for these tools.
## When to use
- Change copy / layout / style on a finished image ad
- New placement aspect ratio for an already-paid creative
## When not to use
- Net-new concepts → `omneky-image-ads` / `omneky-creative`
- Product video generation → `omneky-product-video`
- Calling `get_generation_status` for these sync tools
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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 `omneky-failure-modes` § Approval / plain-chat fallback.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- `edit_image`, `resize_ad`, and `resize_image` are **synchronous** — they
return URLs when done. Do **not** call `get_generation_status` for them.
- **Resizes are not charged** (live tool text): `resize_ad` / `resize_image`
adapt an already-paid creative. Do **not** invent “premium resize tiers”
or require balance-before-resize. Follow
`omneky-failure-modes` § Resize / edit charge. If a future `tools/list`
description changes, follow the live tool text over this skill.
- `edit_image` charge: follow live tool text for that tool only; gate with
balance tools only when listed and the live text indicates a charge
(`omneky-failure-modes` § Billing tools absent).
- Confirm the source asset id / URL with the user when ambiguous.
- Never invent Central-only enhance / variation / upscale tool names if they
are not on `tools/list`.
## Staged workflow
### Stage 1 — Resolve asset + brand
1. Confirm brand if needed.
2. Confirm which finished creative to edit/resize.
### Stage 2 — Charge check (edit only when applicable)
1. Resize path: no credit gate — uncharged per live tool text.
2. Edit path: if live tool text indicates a charge and
`get_account_credit_balance` is on `tools/list`, check balance; else skip
inventing a balance. Optional Apply vs Cancel for paid edit.
### Stage 3 — Mutate (sync)
1. Edit: `edit_image` with natural-language instruction → edited image URL
(often 30–120s).
2. Placement resize: `resize_ad` → `resized_ad_url` (often 30–180s).
3. Pixel resize: `resize_image` → `presigned_url` / `resized_image_url`.
Prefer `resize_ad` for marketing placements.
### Stage 4 — Next
1. More variants, or `register_creative_for_launch` + launch-manage handoff
(Approve, paused default — `omneky-failure-modes` § Approval / plain-chat
fallback).
## Failure boundaries
| Failure | Required response |
| --- | --- |
| Agent starts status poll loop | Stop — sync tools do not use job polling. |
| “Premium resize” / balance-before-resize | Forbidden — resizes not charged; § Resize / edit charge. |
| `credit_insufficient` on edit | Billing path if tools present; no retry. |
| Missing source asset | Ask once; do not invent URLs. |
| Invented upscale / UGC tool | Refuse unless on `tools/list`. |
omneky-failure-modes12.7 KB
View saved version →
---
name: omneky-failure-modes
description: >-
Recover from Omneky MCP failures: JWT re-OAuth, missing brand_id, empty
reporting, timeouts, launch 400s, needs_user_decision, credit_insufficient,
billing tools absent from tools/list, approval plain-chat fallback,
ambiguous paid-submit recovery, disconnected connectors, and pending
scrapes. Intent keywords: unauthorized, reconnect, empty metrics, timeout,
400, credits, billing absent, needs_user_decision, pending scrape, failure
playbook.
---
# Omneky — failure modes (shared playbook)
## Activation analytics
If 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`.
## Purpose
Cross-cutting recovery rules other skills point to by section (§). Encode
recoveries with **exact** public tools. Do not invent SQL, auto-topup,
card-PAN, Nexus debit, Central-only tools, fake widgets, or shared files
outside skill folders.
## When to use
- A tool returned 401 / unauthorized / invalid token
- `brand_id` missing or unresolvable from user language
- Metrics look empty or “zero”
- `status=timeout` / `status=pending` / `status=needs_user_decision`
- Launch 400s (locations, LinkedIn start_date, Reddit microcurrency)
- `credit_insufficient` on creative submit
- Billing / balance tools missing from this session’s `tools/list`
- Approval UI needed and no host widget / `request_user_decision` is available
- Ambiguous paid submit (timeout / transport error after a possible charge)
- Connector disconnected mid-workflow
- User asks “what went wrong?” after an Omneky tool error
## When not to use
- Not a substitute for happy-path skills (`omneky-getting-started`,
`omneky-analytics`, `omneky-creative`, `omneky-launch-manage`, …)
- Not a license to invent tools absent from `tools/list`
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- Prefer native ChatGPT / host widgets and question UI for decisions. Use MCP `request_user_decision` for missing structured fields (not deprecated `ask_user`) **when that tool is on tools/list**.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- Approval / Generate turns: follow **§ Approval / plain-chat fallback** below — never invent a fake “summary widget” tool; never stall waiting for a widget that did not appear.
- Never invent tokens; OAuth is host-managed. Never ask the user to paste a JWT or API key into chat.
## Non-negotiable output / safety contract
- Credits / deductions / balance: **cgp-backend path only** via existing MCP
tools when present on `tools/list`. Never invent Nexus debit routes or
prepaid-purchase tools. When billing tools are absent, follow **§ Billing
tools absent**.
- Never dump raw `clarification_needed` JSON into chat — present plain
questions / host UI.
- Never identical tight-loop retries in one turn for timeout / pending.
- Prefer pause over delete when a mutate failed mid-flight and the user
only wanted to stop spend.
- Point siblings back here by name + section from other skills’ failure tables.
---
## § Billing tools absent / tools/list gating
Billing tools (`get_account_credit_balance`, `get_billing_summary`,
`list_available_plans`, `start_plan_upgrade`, `create_billing_portal_session`,
`get_credit_history`, …) may be present on some connectors and **absent** on
some ChatGPT / host sessions (smaller tool snapshots).
1. **Before calling**: check whether the tool appears on the host’s
`tools/list` / available tools.
2. **If present**: call balance before paid gen when unknown; on low balance
offer upgrade / portal tools **only if those are also present**.
3. **If absent**:
- Do **not** call balance / billing tools.
- Do **not** invent a balance number or a billing tool name.
- State oper
Preview of the first 4,000 characters. Read full instructions →
omneky-getting-started6.92 KB
View saved version →
---
name: omneky-getting-started
description: >-
Start any Omneky ChatGPT plugin session: host OAuth, health_check,
get_current_user, list_brands / brand picker, get_brand_details, and
list_connector_statuses. Use when the user is new, auth failed, brand_id
is unknown, or they ask what Omneky can do. Intent keywords: sign in,
OAuth, who am I, list brands, brand picker, connector status, getting
started, first run, reconnect, capability summary.
---
# Omneky — getting started
## Activation analytics
If 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`.
## Purpose
Bootstrap a signed-in Omneky session before brand-scoped analytics, catalogue,
creative, or launch work. Prove the connector is up, resolve identity and
`brand_id`, summarize connected channels, and route to the right sibling
skill — without inventing keys, charging credits, or launching spend.
Omneky helps with paid-media on Meta/Facebook, Google (Performance Max and
Demand Gen), TikTok, LinkedIn, Reddit, Pinterest, and X Ads (`twitter`):
catalogue, image/video creatives, paused-by-default launches, and ROAS/CTR
reporting.
## When to use
- First turn on a new host / plugin session
- Auth / JWT / 401 errors (re-run host OAuth)
- Need `user_id`, `brand_id`, company context, or a capability snapshot
- User asks “what can Omneky do?” or “which brands do I have?”
## When not to use
- ROAS / CTR reporting → `omneky-analytics` / `omneky-performance-movers`
- Launches, pause, budget, delete → `omneky-launch-manage` /
`omneky-meta-launch` / `omneky-pause-budget`
- Image/video generation → `omneky-creative` / `omneky-image-ads` /
`omneky-product-video`
- Catalogue writes → `omneky-catalogue` / `omneky-product-import`
- Plan upgrade / Stripe portal as the primary goal → `omneky-billing`
- Do not treat `health_check` as a data source — reachability only
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- 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.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Never ask the user to paste a JWT, Nexus token, or API key into chat.
- Prefer a **brand-picker** host widget when multiple brands exist (≤3 options
+ custom when the host allows). Confirm before guessing `brand_id`.
- Prefer a **numeric** `brand_id` when thumbnails / catalogue imagery matter.
- Do not launch, delete, pause, enable, change budget, or submit paid
generation from this skill — hand off with a clear next skill name.
- Safety defaults to mention when orienting: launches paused by default;
pause > delete; credit callout before paid gen (image ~5 / video ~30);
never invent metrics; `check_reporting_data_available` before empty=zero.
- ChatGPT-safe: omit Cursor-only / Grok-Bot-only avatar / profile-picture
steps unless the host explicitly supports avatar update; if unsupported,
skip silently.
- Cross-link siblings by name. Recovery detail → `omneky-failure-modes`.
## Staged workflow
### Stage 1 — Session / auth
1. If the host has no Omneky login, tell the user to complete the plugin
connector OAuth for Omneky. On JWT / 401 / unauthorized, ask them to
re-OAuth in the host. Never paste a token.
2. Optionally call `health_check` when diagnosing connect failures
Preview of the first 4,000 characters. Read full instructions →
omneky-getting-started-and-failures5.52 KB
View saved version →
---
name: omneky-getting-started-and-failures
description: >-
Recover Omneky session context: sign-in/OAuth, unknown brand,
unauthorized, pending/timeout/needs_user_decision/credit_insufficient.
Also the named-preset menu when they ask what they can do. Do not
use for first-run onboarding (omneky-onboarding), agency
cross-brand (omneky-agency), weekly marketing plans
(omneky-marketing-plan), paid-media analysis or catalogue
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
generating creatives, launch/connect
(omneky-launch-and-connect), or credits (omneky-billing).
Keywords: sign in, OAuth, list brands, unauthorized, timeout,
empty data, no brands, which brand, needs user decision,
credit insufficient, named presets, what can you do.
---
# Session context and failure recovery
Use this when sign-in fails, the brand is unknown, a call returns an
error state, or the user asks what they can do. One job: get the
session working again and point to the owning skill.
<!-- host:begin name="oauth-sign-in" -->
The user signs in to the connected Omneky MCP server through the host's
OAuth. Never ask for or paste a JWT, token, or password.
<!-- host:end -->
<!-- host:begin name="recovery-routing" -->
This skill is the recovery entry. Healthy creative (`omneky-image-ads`,
`omneky-product-video`, `omneky-avatar-ugc`,
`omneky-voice-and-video-clone`, `omneky-edit-and-resize`), launch,
analytics, catalogue, billing, and marketing-plan requests go straight
to those skills.
<!-- host:end -->
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
<!-- host:begin name="scan-tools-routing" -->
Quote, retry, and polls: [creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Structured brief: [creative-brief](../_shared/references/creative-brief.md).
QA and cheapest repair: [media-qa-and-repair](../_shared/references/media-qa-and-repair.md).
Named presets and other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
<!-- host:end -->
## Goal
<!-- host:begin name="goal-first-run" -->
Recover a broken session and list named presets. First-run setup is `omneky-onboarding`.
<!-- host:end -->
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Session | `get_account` | Host OAuth reconnect |
| Brand | `list_brands` | Ask which; no brands → Omneky app |
| Connectors | `list_connections` | Connect via `omneky-launch-and-connect` |
| Credits (shortfall) | `get_account` | `omneky-billing` |
## Flow
1. Act on the request; there is no mandatory first-turn sequence.
2. Reuse the chosen `brand_id`. If unknown, `list_brands` (pass
`search`). No brands → Omneky app. Several matches → list name and
id and ask. One match → say it and keep it. Never switch brands
because metrics are empty.
3. On 401, ask the user to reconnect Omneky in the host.
4. Match the error to its recovery in
[playbook](references/playbook.md) (Failures; creative states
such as pending, terminal failure, and ambiguous paid submits).
5. Tell the user what broke, the fix, and the next step.
## When to use
- 401 / JWT errors, unknown or ambiguous `brand_id`
- Empty metrics, `status=timeout` / `pending` / `needs_user_decision`
- `credit_insufficient`
<!-- host:begin name="creative-when-to-use" -->
- A video pick that returns `narrative_unresolved`
<!-- host:end -->
## When not to use
<!-- host:begin name="creative-when-not" -->
- A healthy "make a branded ad" / "video ad" / "which ads should I make
more of" / "how many credits" / "weekly marketing plan" request —
open that skill directly
<!-- host:end -->
- Weekly pla
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
omneky-image-ads5.17 KB
View saved version →
---
name: omneky-image-ads
description: >-
Create Omneky branded image ads from the brand catalogue. Use for a
product image ad, a brand-general still, a hero still, a
before/after still, or N distinct stills from winning creatives
(each variant is one hypothesis: source ad, what stays, what
changes, which metric). Do not use for product video
(omneky-product-video), avatar/UGC (omneky-avatar-ugc), voice or
video clone (omneky-voice-and-video-clone), edit or resize
(omneky-edit-and-resize), ROAS-only
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
weekly plans (omneky-marketing-plan), first-run onboarding
(omneky-onboarding), agency (omneky-agency), launch/connect
(omneky-launch-and-connect), or credit-balance-only
(omneky-billing). Keywords: branded ads, image ad, generate image
ads for this product, next batch, hero still, seasonal promo
kit, hero to every channel size, before/after, thumbnail still,
stills of one concept, distinct hypotheses.
---
# Branded image ads
Use this when the user wants a branded still: a hero shot, a seasonal
kit, a thumbnail, or new variations of a winning ad. One job: finished
stills. Launching is `omneky-launch-and-connect`.
Gate on `generate_image_ad` being on `tools/list`; if it is missing,
say image ads aren't available here and point to the Omneky app.
Step detail: [playbook](references/playbook.md) (hard rules, brand and
product context, image ad, creative strategy, next batch).
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
Quote, retry, and polls: [creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Structured brief: [creative-brief](../_shared/references/creative-brief.md).
QA and cheapest repair: [media-qa-and-repair](../_shared/references/media-qa-and-repair.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
## Goal
Ship decision-ready stills: hero, seasonal kit, thumbnail, N winner hypotheses. No launch here.
## When to use
- Branded still, hero, before/after, thumbnail, seasonal kit, N hypotheses
- Several stills of one concept
## When not to use
- Product / faceless video → `omneky-product-video`
- UGC talking-head → `omneky-avatar-ugc`
- Resize only → `omneky-edit-and-resize`
- Launch → `omneky-launch-and-connect`
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which |
| Product (product ad) | `get_products` | Import via `omneky-analytics-and-catalogue` or `omneky-onboarding` |
| Cost | no quote tool; state the cost and proceed | Report credits actually charged (`credits_charged`) |
| Credits | `get_account` | `omneky-billing` |
| Generate | `generate_image_ad` | Say image ads are not on this connector |
## Flow
1. Fill the structured brief. Take `approved_claims` from the
handoff, product page, catalogue, or the user's words; leave out
any claim you cannot ground. Pass `product_id` for product work
(check `get_products`).
Brand-general work passes `brand_id` only.
Direct mode (no saved product, no import): pass `brand_id`,
`ad_concept`, and the user's HTTPS image URL in `user_assets`.
2. State the cost and call `generate_image_ad`. Several different
ads in one ask: when `generate_image_ad` lists a `concepts` input,
send them all (up to 3, each with a short `title` and its
`ad_concept`) in **one** call so one widget shows every tile.
Otherwise call it once per concept, with a new `gpt_ad_gen_id`
per variant. Do not ask for a yes first.
3. Poll within the bounds in the pricing reference. On a timeout,
reuse the same `gpt_
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
omneky-launch-and-connect5.65 KB
View saved version →
---
name: omneky-launch-and-connect
description: >-
Launch Omneky paid-media campaigns and connect missing ad
accounts (Meta/Facebook, Google, TikTok, LinkedIn, Reddit,
Pinterest, X/Twitter, OpenAI Ads). Use to launch, publish,
pause/budget/retarget, or connect an ads account. Do
not use for first-run onboarding (omneky-onboarding), agency
cross-brand (omneky-agency), ROAS analytics or catalogue
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
weekly marketing plans (omneky-marketing-plan), AI creative
generation, or credit balance (omneky-billing).
Keywords: launch Meta sales ads, launch campaign, Meta ads,
Facebook ads, Google PMax, TikTok ads, LinkedIn ads, connect
ads, pause ad, budget, targeting, twitter, paused, preflight,
waste pruner pause, update ad targeting, apply target CPA
budget, Demand Gen, TikTok locations, Pinterest campaigns.
---
# Launch paid ads and connect accounts
Use this when the user wants to launch, pause, re-budget, retarget or
delete paid ads, or connect an ad account. One job: paid-media
changes and account connection. Live vs paused is the host's call from the user's request.
Gate on `tools/list`; a missing launch tool → the Omneky app. X Ads
is channel `twitter`; OpenAI Ads is `openai`.
Step detail: [playbook](references/playbook.md) (channel table, launch
path, preflight, targeting, manage, connect, launch checks).
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
<!-- host:begin name="scan-tools-routing" -->
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
<!-- host:end -->
## Goal
Launch or mutate paid media the user asked for. Set `campaign_spec.status_on_launch` from what the user asked (no server default). Launches, deletes, budget, status and targeting changes are marked destructive, so the host confirms them; do not add your own approval step.
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which |
| Channel | `list_connections` (`connector`) | `get_connect_link` → `list_ad_accounts` → `link_ad_account` when listed. If `link_ad_account` is not on `tools/list`, say that capability isn't available on this connector. Do not invent a link. Or managed launch |
| Budget floor | `get_launch_requirements` | Do not launch under the floor |
| Audience size | `estimate_reach` | Optional; estimate only |
| Targeting tokens | `search_targeting` (`channel`, `query`) / `search_targeting` (`channel="tiktok"`, `objective`) / `search_targeting` (`channel="google"`) | Required on LinkedIn / TikTok / Demand Gen |
<!-- host:begin name="launch-creative-url-row" -->
| Creative URL | any finished HTTPS asset URL (prior generate or user-supplied) | No URL at all → Owning creative skill first |
<!-- host:end -->
| Credits | `get_account` | `omneky-billing` |
## Flow
1. Pick the channel and the exact `launch_*` tool from the playbook
table, then read only that channel's reference.
2. Self-managed: confirm the account is connected; if not, run
Connect and stop. Managed (no account): skip Connect.
3. Check the budget floor and run the channel's targeting pre-call
(TikTok locations, LinkedIn locations, Demand Gen countries).
4. Fill copy, CTA, landing URL and the finished asset URL from the
conversation; ask only for what you cannot infer. Use
`approved_claims` from the handoff; never invent a claim or URL.
5. Show one summary (channel, spend, audience, asset, status) and
call the tool. Launches, deletes, budget, status and targeting
changes are marked destructive, so the host confirms them; do not
add your own appro
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 10 — file references are metadata, not package contents.
omneky-launch-manage9.81 KB
View saved version →
---
name: omneky-launch-manage
description: >-
Launch and manage Omneky paid-media ads on Meta/Facebook, Google Ads,
TikTok, LinkedIn, Reddit, Pinterest, and X Ads (Twitter). Use when the
user wants to create, pause, budget, retarget, or delete campaigns, or
attach a catalogue/creative to a live ad account. Intent keywords: paid
media, Meta ads, Facebook ads, Instagram, Google PMax, Demand Gen,
TikTok ads, LinkedIn ads, Reddit ads, Pinterest ads, X Ads, Twitter ads,
launch Meta sales ads, ROAS, launch campaign, pause ad, budget,
targeting, product catalogue, Approve launch.
---
# Omneky launch and manage
## Activation analytics
If 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`.
## Purpose
Create and operate paid-media campaigns across connected channels with
**Approve-before-mutate** discipline. Default new launches to **PAUSED**.
Prefer pause over delete. X Ads wire name is **`twitter`**, never `x`.
## When to use
- Launch, pause, resume, budget, or retarget paid-media campaigns
- Meta / Facebook / Instagram, Google Ads, TikTok, LinkedIn, Reddit,
Pinterest, or X Ads
- Attach a catalogue product or chat-generated creative to an existing
campaign or ad set
- Connect a missing ad account (delegate detail to `omneky-self-connect`)
## When not to use
- ROAS / CTR / spend reporting → `omneky-analytics`
- Generating or editing creatives → `omneky-creative` (then return here)
- Catalogue SKU writes → `omneky-catalogue`
- Inventing Central-only or OpenAI Ads **launch** names (`launch_openai_*`,
managed-Meta launch tools)
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- Approval turns: end the turn after Approve / Deny / Edit (host UI or plain chat); mutate only next turn after Approve. Never invent a fake summary-widget tool; never stall for a widget that did not appear.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Before any `launch_*`, `set_ad_entity_status` / `set_ad_budget` /
`update_ad_targeting` / `delete_*`: show a one-card summary
(`Brand · Channel · Objective · Budget · Paused|Live · Creative`) with
**Approve / Deny / Edit** via host-native confirmation / MCP Apps /
`request_user_decision` when available; otherwise **plain-chat fallback**
(`omneky-failure-modes` § Approval / plain-chat fallback). End the turn.
Mutate only next turn after affirmative Approve (or clear yes).
- Default `status_on_launch` / `configured_status` to **`PAUSED`** unless the
user explicitly asked to go live.
- Prefer **pause** over **delete**. Deletes: first offer Pause instead /
Delete permanently / Cancel; then a **second** Approve confirm.
- Prefer `set_ad_entity_status` over deprecated `set_ad_status`.
- Prefer `request_user_decision` over deprecated `ask_user` when that tool
is on `tools/list` and fields are missing / `needs_user_decision`. Else
plain-chat questions. Never dump `clarification_needed` JSON; never
auto-retry failed writes same turn.
- Hierarchy: Campaign → Ad Set (`ad_group`) → Ad. Creative is an asset on
the Ad (`ad_specs`), never on the campaign. Status/budget tools do not
add ads.
- Confirm channel connected before launch; else `omneky-self-connect`.
- After success: post-launch next steps (host UI or plain chat) — Check
status / Pull 7d metrics / Done (metrics via `omneky-analytics`).
- Keep decision options to ≤3 when possible.
#
Preview of the first 4,000 characters. Read full instructions →
omneky-marketing-plan4.53 KB
View saved version →
---
name: omneky-marketing-plan
description: >-
Create, revise, poll, preview (exact credit quote + checklist), and
track an Omneky marketing plan. This skill owns the weekly-plan
loop. The host runs each listed step itself. Use when the user wants
a weekly marketing plan, make me a plan, plan preview, or plan
progress. Do not use for paid-media analysis or catalogue
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
first-run onboarding (omneky-onboarding), agency
(omneky-agency), branded image/video creatives,
launch/connect (omneky-launch-and-connect), or credits/plan
upgrade (omneky-billing). Intent keywords: weekly marketing
plan, make me a plan, marketing plan, plan preview, revise
plan, approve plan.
---
# Omneky marketing plan
Use this when the user wants a weekly marketing plan created, revised,
checked, or run. One job: goal intake → create → revise → poll →
preview → state the cost and proceed (no approval gate; stop only
above a cap the user named). The host runs each listed plan step.
Gate on `analyze_brand`, `create_marketing_plan` and
`get_marketing_plan` being on `tools/list`; if missing, point to the
Omneky app.
Step detail: [playbook](references/playbook.md) (goal intake, loop,
pending polls, checks).
<!-- host:begin name="creative-skill-routing" -->
Branded stills → `omneky-image-ads`. Product video →
`omneky-product-video`. Avatar / UGC → `omneky-avatar-ugc`.
Voice or video clone → `omneky-voice-and-video-clone`. Edit /
resize → `omneky-edit-and-resize`.
<!-- host:end -->
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
<!-- host:begin name="scan-tools-routing" -->
Acceptance gates (for a later creative): [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
<!-- host:end -->
## Goal
Author a weekly plan from a stated goal, preview the exact quote, state it, then host-run each listed step.
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which |
| Analysis | `analyze_brand` | Call it; draft only |
| Plan tools | `create_marketing_plan` / `get_marketing_plan` / `revise_marketing_plan` | Say plan tools are missing |
| Preview quote | `preview_marketing_plan_execution` | Do not run steps without this preview |
## Flow
1. Take the goal, budget, and window; ask only for what is missing.
2. `analyze_brand`, then `create_marketing_plan`.
3. Poll `get_marketing_plan` (`plan_id`) within the bounds in the playbook.
4. Revise with `revise_marketing_plan` until the user is happy.
5. `preview_marketing_plan_execution`, state the cost, and let the
host run each listed step.
6. Deliver plan id, checklist, step status, and confidence.
When the plan feeds a later creative, hand over `source_evidence` and
`approved_claims` in the handoff (not as tool arguments).
## When to use
- Weekly marketing plan / "make me a plan"
- Revise, preview, or mark plan-step progress
## When not to use
- Not paid-media analysis, ROAS, or catalogue import
- Not a standalone image-ad or product-video generate call
- Not live spend or go-live
- Not launch/connect or credit-balance / plan upgrade
## Intent keywords
weekly marketing plan, make me a plan, marketing plan, plan preview,
revise plan
## Failure and recovery
Auth / 401 → `omneky-getting-started-and-failures` (host OAuth).
Empty reporting → `get_performance_summary` (`include_coverage=true`); empty is not zero.
`credit_insufficient` → nothing charged; state balance vs required
(`omneky-billing`). No payment links.
`needs_user_decision` → fill the missing detail and call again; ask in plain chat only if you cannot. Never dump JS
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
omneky-meta-launch4.91 KB
View saved version →
---
name: omneky-meta-launch
description: >-
Prepare and launch Meta/Facebook/Instagram ads (sales, traffic, leads,
awareness, video views) after user confirmation. Keywords: Meta launch,
Facebook ads, Instagram ads, launch campaign, PAUSED, sales, leads,
ThruPlay, lead_gen_form_id.
---
# Meta launch
## Activation analytics
If 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`.
## Purpose
Meta-first launch path using `launch_facebook_*` tools. Same Approve-before-
mutate and paused-default rules as `omneky-launch-manage`, narrowed to
Facebook / Instagram.
## When to use
- User wants Meta / Facebook / Instagram paid launch
- Sales / conversions, traffic, leads, awareness, or video views objectives
## When not to use
- Google / TikTok / LinkedIn / Reddit / Pinterest / X → `omneky-launch-manage`
- Creative generation → `omneky-creative` first
- Analytics-only → `omneky-analytics`
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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 `omneky-failure-modes` § Approval / plain-chat fallback.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- Approval turns: end the turn after Approve / Deny / Edit (host UI or plain chat); mutate only next turn after Approve. Never invent a fake summary-widget tool.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Confirm brand, creative, objective, budget, targeting, CTA, landing URL.
- Approve / Deny / Edit one-card summary **before** any `launch_facebook_*`
(host-native confirmation / MCP Apps / `request_user_decision` when
available; else plain-chat fallback — `omneky-failure-modes` § Approval /
plain-chat fallback). End turn; launch only next turn after affirmative
Approve.
- Default paused / disabled unless user clearly asks to go live.
- Prefer pause over delete (`omneky-pause-budget` /
`set_ad_entity_status`).
- If a preflight / validate tool appears on this session’s `tools/list`, use
it before create — never invent a preflight tool name that is absent.
- Facebook lead ads: set `lead_gen_form_id` on ad specs for native forms.
- Inline targeting example shape: countries + age_min / age_max — do not
invent unsupported facets.
- No `launch_openai_*` / managed-Meta launch names on public `/mcp`.
## Staged workflow
### Stage 1 — Brand + connection
1. `list_brands` / picker / `get_brand_details`.
2. `get_channel_connection_status` for Facebook. If disconnected →
`omneky-self-connect` (`get_channel_connect_url` →
`list_authorized_ad_accounts` / `list_authorized_facebook_pages` →
`link_ad_channel_account`).
3. `get_channel_budget` / `minimum_budget_for_objective`.
### Stage 2 — Creative + catalogue
1. Product: `list_brand_products` / `get_product_details` when relevant.
2. Generate if needed via `omneky-creative` (credits first).
3. `register_creative_for_launch` when attaching a chat creative.
### Stage 3 — Objective + specs
1. Map user intent → tool:
- Sales / purchases / ROAS → `launch_facebook_sales_ad`
- Leads → `launch_facebook_leads_ad` (+ `lead_gen_form_id` when native form)
- Traffic → `launch_facebook_traffic_ad`
- Awareness / reach → `launch_facebook_awareness_ad`
- Video views / ThruPlay → `launch_facebook_video_views_ad`
2. New vs existing: `campaign_spec={"id": …}` / `ad_group_spec={"id": …}`
when extending.
3. Optional `get_ad_custom_properties` / `reach_estimate`.
### Stage 4 — Approve then launch
1. Summary Approve / Deny / Edit (host UI or plain chat); end turn.
2. After Approve: call the chosen `launchPreview of the first 4,000 characters. Read full instructions →
omneky-onboarding5.35 KB
View saved version →
---
name: omneky-onboarding
description: >-
First-run Omneky onboarding. Use for brand setup from a website,
first ad today from a product URL, or managed run-it-for-me
(Omneky-managed Meta / OpenAI). Do not use for healthy ROAS
tables (omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
weekly plans (omneky-marketing-plan), agency cross-brand
(omneky-agency), a later creative-only request
(omneky-image-ads, omneky-product-video), or credit
balance (omneky-billing). Keywords: brand setup from website,
first ad today, first ad from this URL, run it for me, managed
Meta, managed OpenAI, onboard.
---
# First-run onboarding
Use this when a new user wants their brand set up from a website or
their first ad today, or asks Omneky to run ads for them. One job:
setup → first creative → `PAUSED` or managed launch. Later work goes
to the owning skill. Gate tools on `tools/list`; never ask for
internal ids.
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids: [preconditions](../_shared/references/preconditions.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Quote / polls: [creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
Gaps: [capability-gaps](../_shared/references/capability-gaps.md).
## Goal
Get a signed-in brand from a website or URL to a first ad the
same day, quoted, and launched `PAUSED` (or Omneky-managed when
they have no ad account).
## When to use
- Brand setup from a website
- First ad today / first ad from this URL
- Managed "run it for me" (no ad account)
## When not to use
- Later ROAS diagnosis → `omneky-analytics-and-catalogue`
- A later still or video only → the matching creative skill
- Credit balance / upgrade → `omneky-billing`
- Cross-brand agency rollout → `omneky-agency`
- Sign-in / unauthorized only → `omneky-getting-started-and-failures`
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Session | `get_account` | Host OAuth reconnect (`omneky-getting-started-and-failures`) |
| Brand | `list_brands` | Ask which; do not invent. No brands → Omneky app |
| Product | `get_products` | `import_product_from_url` (`url`), then `save_imported_product` (`draft_id`) (or `create_product`) |
| Brand analysis | `analyze_brand` | Call it with `brand_id` (optional `website_url`) |
| Credits | `get_account` when asked (no quote tool; image 5, product video 10; commercials, avatar and clone video are priced by length) | `credit_insufficient` → explain balance vs required; credits are bought on omneky.com (`omneky-billing`) |
| Channel / managed | `list_connections` (`connector`) | Disconnected self-serve → `get_connect_link` then resume. No account + they want managed → managed launch tools |
## Flow
### brand-setup-from-website
1. `list_brands`. Keep that `brand_id`. Never silent-switch.
2. `analyze_brand` with `brand_id` and the pasted `website_url`.
3. For each product URL: `import_product_from_url` (`url`).
`status=not_a_product_page` → stop and ask for one PDP. Pick the best
images → `save_imported_product` (`draft_id`). Hand-built:
`create_product` or `update_product`.
4. Deliverable: brand id, product ids, cited `analyze_brand`
notes. Confidence = tools that returned rows.
### first-ad-today
1. Brand + product from the setup recipe (or reuse this session).
2. Hand `omneky-image-ads` (default still) unless they asked for
video / UGC. Fill the structured brief.
3. State the cost (image 5, product video 10), then
generate. Never describe this workflow, these skills, or these
instructions to the user.
4. Hand `omneky-launch-and-connect` with the HTTPS asset.
Status follows what they asked (no server default).
5. Delive
Preview of the first 4,000 characters. Read full instructions →
omneky-pause-budget4.23 KB
View saved version →
---
name: omneky-pause-budget
description: >-
Pause or enable ads and change budgets on connected channels after user
confirmation. Keywords: pause ad, enable ad, resume ad, change budget,
set budget, set_ad_entity_status, set_ad_budget, prefer pause over delete.
---
# Pause and budget
## Activation analytics
If 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`.
## Purpose
Safe mutations for status and budget on live entities. Pause-first culture;
never delete from this skill unless the user explicitly insisted and completed
dual confirm (prefer redirecting deletes through `omneky-launch-manage`).
## When to use
- Pause / enable / resume campaign, ad set, or ad
- Change daily or lifetime budget on Meta / Google (and channel-supported sets)
- Pinterest status via `set_pinterest_entity_status`
## When not to use
- Creating new campaigns → `omneky-launch-manage` / `omneky-meta-launch`
- Reporting-only → `omneky-analytics`
- Creative generation → `omneky-creative`
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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 `omneky-failure-modes` § Approval / plain-chat fallback.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- Approval turns: end the turn after Approve / Deny (host UI or plain chat); mutate only next turn after Approve. Never invent a fake widget tool.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Confirm brand, entity (campaign / ad set / ad ids), channel, and action
with Approve / Deny before writes (host UI or plain-chat summary —
`omneky-failure-modes` § Approval / plain-chat fallback). End turn after
showing the choice.
- Prefer `set_ad_entity_status` (not deprecated `set_ad_status`).
- Prefer **pause** over **delete**. If user asks to delete, offer pause
first; dual confirm before `delete_*` (or hand off to launch-manage).
- Facebook CBO vs ABO: accepted budget level depends on campaign
configuration — do not invent hierarchy overrides.
- X Ads: `channel="twitter"`.
- Unscoped entity lists can time out — pass `campaign_id` into
`get_ad_groups` when inspecting.
## Staged workflow
### Stage 1 — Resolve entities
1. Brand: `list_brands` / picker if needed.
2. `get_channel_connection_status`.
3. Inspect: `get_campaigns` → `get_ad_groups(campaign_id=…)` → `get_ads`.
Pinterest helpers: `get_pinterest_campaigns` /
`get_pinterest_ad_groups` / `get_pinterest_ads`.
4. Optional name resolve: `get_campaign_ad_group_names` /
`search_reporting_values`.
### Stage 2 — Budget context
1. `get_channel_budget` / `minimum_budget_for_objective` before raising spend.
2. Confirm currency / daily vs lifetime with the user when ambiguous.
### Stage 3 — Approve
1. One-card summary: Brand · Channel · Entity · Action (Pause|Enable|Budget) ·
Amount — host UI when available; else plain chat with Approve / Deny /
Edit.
2. End turn.
### Stage 4 — Mutate (next turn)
1. Status: `set_ad_entity_status` (Pinterest: `set_pinterest_entity_status`).
2. Budget: `set_ad_budget`.
3. Meta retarget only when asked: `update_ad_targeting` (Facebook-only).
### Stage 5 — Verify
1. Re-read entity via `get_ads` / `get_ad_groups` / `get_campaigns` as needed.
2. Offer metrics via `omneky-analytics` / `omneky-performance-movers`.
## Failure boundaries
| Failure | Required response |
| --- | --- |
| Write without Approve | Forbidden — host UI or plain-chat summary first. |
| Invented approval widget tool | Forbidden — `omneky-failure-modes` § Approval / plain-chat fallback. |
| Delete-first reques
Preview of the first 4,000 characters. Read full instructions →
omneky-performance-movers3.55 KB
View saved version →
---
name: omneky-performance-movers
description: >-
Find which ads to make more of: performance movers, ROAS/CTR leaders, and
creative recommendations. Keywords: which ads, ROAS, CTR, movers,
recommendations, leaderboard, what rose, what fell, make more of.
---
# Performance movers
## Activation analytics
If 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`.
## Purpose
Fast read-only path for “what rose / fell?” and “which creatives should I
make more of?” grounded in movers + recommendations + optional drill-downs.
## When to use
- Which ads / campaigns / creatives improved or declined vs the prior period
- Leaderboard / “what should I scale?” questions
- Follow-on from a thin analytics ask that is clearly mover-centric
## When not to use
- Full multi-connector / GSC / HubSpot deep dives → `omneky-analytics`
- Mutations (pause / budget / launch) → launch-manage / pause-budget
- Inventing causal “lift” scores without tool support
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- 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.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Brand-scoped and read-only.
- Coverage first: `check_reporting_data_available` before treating empty as zero.
- Prefer `get_performance_movers` (not deprecated `get_trending`).
- Prefer `get_performance_breakdown` for ranked drill-down (not deprecated
`get_dimension_summary`).
- Never invent metrics; never sum `selected_conversion_metric_value` across channels.
- Summarize winners and losers with evidence.
## Staged workflow
### Stage 1 — Brand + coverage
1. Resolve brand (`list_brands` / picker) if needed; `get_current_user` when required.
2. Confirm date window.
3. `check_reporting_data_available`.
### Stage 2 — Movers
1. `get_performance_movers` for up / down vs prior period.
2. Present a short leaderboard (top gains / top drops) with channel labels.
### Stage 3 — Drill / recommend
1. Optional: `get_daily_metrics` for a nominated entity’s trend.
2. Optional: `get_performance_breakdown` for creative / campaign ranks.
3. Optional: `search_reporting_values` to resolve names → ids.
4. When they ask what to change or test next: `get_recommendations`
(tight window; timeout → narrow, no identical retry).
### Stage 4 — Hand off
- “Make more like winner X” → `omneky-creative` / `omneky-image-ads` /
`omneky-product-video`
- “Pause the losers” → `omneky-pause-budget` (Approve before mutate)
- Broader reporting → `omneky-analytics`
## Failure boundaries
| Failure | Required response |
| --- | --- |
| Empty movers | Coverage check; explain gap; do not invent ranks. |
| Recommendations timeout | Narrow window; stop identical retry. |
| Cross-channel conversion sum | Refuse; channel-group. |
| User requests pause mid-read | Hand off; Approve widget required. |
omneky-product-import3.46 KB
View saved version →
---
name: omneky-product-import
description: >-
Import a product page URL into the Omneky brand catalogue or update a SKU
after scrape confirmation. Keywords: import product, product URL, scrape
product, catalogue, SKU, identify product, finalize scraped product, PDP.
---
# Product import
## Activation analytics
If 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`.
## Purpose
URL → catalogue draft → user confirm → finalize. Specialized path of
`omneky-catalogue` for PDP imports.
## When to use
- User pastes a product URL to import
- Re-scrape / refresh an existing PDP into a new draft then finalize
## When not to use
- Manual field entry without URL → `omneky-catalogue` (`create_product` /
`upsert_brand_product`)
- Generating creatives from the product before finalize completes
- Category / collection listing URLs (classify first; usually skip scrape)
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- 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.
- Never invent tokens; OAuth is host-managed.
## Non-negotiable output / safety contract
- Always `identify_product_from_url` before scrape.
- Finalize with `finalize_scraped_product` — never treat scrape draft as
completed via `upsert_brand_product`.
- Confirm selected images + fields before finalize (Approve widget preferred).
- No public product-delete tool.
- Pending scrapes: no tight-loop polling in one turn.
## Staged workflow
### Stage 1 — Brand
1. Resolve `brand_id` (`list_brands` / picker). Prefer numeric id.
### Stage 2 — Identify
1. `identify_product_from_url`.
2. If listing/category: tell the user; ask for a single product PDP. Stop.
### Stage 3 — Scrape
1. `scrape_product_from_url`.
2. If `status=pending`: explain; retry later with the same `brand_id` + url.
3. Do not start multiple parallel scrapes for the same URL in one turn.
### Stage 4 — Confirm
1. Present name, description, images, URL.
2. Host Approve / Deny / Edit (or plain-chat fallback / `request_user_decision` when listed) — `omneky-failure-modes` § Approval / plain-chat fallback.
3. End turn after the widget.
### Stage 5 — Finalize
1. On Approve: `finalize_scraped_product` with chosen fields / images.
2. Optionally `update_product_url` if only the URL should change later.
3. Hand off to creative or launch skills with the new `product_id`.
### Stage 6 — Re-import
1. Optional `update_product_url` first.
2. Scrape again → confirm → finalize.
## Failure boundaries
| Failure | Required response |
| --- | --- |
| Listing URL | No scrape; request PDP. |
| Pending | Later retry; no tight loop. |
| User denies finalize | Leave draft; do not upsert as completed. |
| Wrong brand | Re-resolve brand; do not finalize onto guessed id. |
| Delete request | No public delete; explain. |
omneky-product-video4.87 KB
View saved version →
---
name: omneky-product-video
description: >-
Create Omneky multi-scene product video ads from the brand
catalogue. Use for a video commercial, pick-a-story, or Generate
Now. Do not use for still image ads (omneky-image-ads),
avatar/UGC (omneky-avatar-ugc), voice or video clone
(omneky-voice-and-video-clone), edit or resize
(omneky-edit-and-resize), ROAS-only
(omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
weekly plans (omneky-marketing-plan), first-run onboarding
(omneky-onboarding), agency (omneky-agency), launch/connect
(omneky-launch-and-connect), or credit-balance-only
(omneky-billing). Keywords: product video ad, video commercial,
product launch video, explainer video, professional video,
faceless product video, turn this product URL into video ads,
Generate Now, revise narrative, re-pick story.
---
# Product video ads
Use this when the user wants a video ad for a product: a story-driven
spot, a launch or explainer video, a faceless product video, or a
video from their own script. One job: product video ads.
Gate on `plan_product_video` and `generate_product_video`
being on `tools/list`; a missing tool → the Omneky app.
Step detail: [playbook](references/playbook.md) (hard rules, pick a
story, Generate Now, revision, inspect, faceless, launch video).
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
Quote, retry, and polls: [creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Structured brief: [creative-brief](../_shared/references/creative-brief.md).
QA and cheapest repair: [media-qa-and-repair](../_shared/references/media-qa-and-repair.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
## Goal
Ship a product-launch, explainer, faceless, or professional video from a narrative pick or Generate Now.
## When to use
- Product video, explainer, launch video, faceless, professional commercial, Generate Now, revise narrative
## When not to use
- Talking-head UGC → `omneky-avatar-ugc`
- Stills → `omneky-image-ads`
- Animation / hero-spin → decline (gap)
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Use the best match |
| Product + images | `get_products` | Import it yourself (`import_product_from_url` (`url`), or web search) |
| Narratives | `plan_product_video` | Optional; skip when a script is given |
| Generate | `generate_product_video` | Say product video is not on this connector |
| Professional | `generate_professional_video_ad` | Skip that recipe if unlisted |
| Cost | no quote tool; say it uses credits | State the cost and proceed; `credit_insufficient` → add credits on omneky.com |
## Flow
1. Product video is product-specific: pass `product_id` (look it up
with `get_products`).
Take `approved_claims` from the handoff, product page, or
catalogue; leave out a claim you cannot source. Add
`source_evidence` only for performance-informed work.
2. Get story cards with `plan_product_video` and pick the
best one yourself, unless the user gave a script or said "just
generate" (Generate Now omits both narrative fields).
3. Pass the picked `narrative_id`. `narrative_unresolved` → re-fetch
and pick again; never fall back to Generate Now.
4. State the cost and call `generate_product_video`. Do not ask for a
yes first.
5. Poll the returned `job_id` within the bounds in the pricing
reference, then inspect against the quality gates.
6. Deliver the URL, the story used, and the next step.
A hero spin or product animation is not a commercial. A YouTube
title, description, or chapters pack is
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
omneky-self-connect5.95 KB
View saved version →
---
name: omneky-self-connect
description: >-
Connect a missing Omneky ad channel or OpenAI Ads / PostHog / Google Drive
for the signed-in brand. Use when get_channel_connection_status is
disconnected or the user asks to link an ad account, Facebook Page,
Pinterest, X Ads (twitter), PostHog, or Drive. Intent keywords: connect
ads, OAuth URL, link ad account, Facebook page, Pinterest, Twitter, X Ads,
OpenAI Ads, PostHog, Google Drive, disconnect Drive.
---
# Omneky self-connect
## Activation analytics
If 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`.
## Purpose
Attach authorized ad accounts and optional brand connectors so later
`launch_*` / asset flows can succeed. Browser OAuth (or one-shot API key
forward for OpenAI Ads / PostHog) is user-completed; this skill never
collects secrets into free chat beyond what the tool schema requires, and
never invents disconnect tools that are not on `tools/list`.
## When to use
- Channel is disconnected and the user wants to launch or manage ads
- User asks to connect Meta / Google / TikTok / LinkedIn / Reddit /
Pinterest / X Ads (`twitter`), OpenAI Ads, PostHog, or Google Drive
- After `get_channel_connection_status` or `list_connector_statuses` shows
a gap blocking a requested workflow
## When not to use
- Not HubSpot / Semrush / Ahrefs / GSC **connect** — those are status +
reads only on this surface (see `omneky-analytics`). Users connect them
in brand settings.
- Not OpenAI Ads / managed-Meta **launches** — connect ≠ launch. There is
no `launch_openai_*` / `launch_omneky_managed_*` on public `/mcp`.
- Not Datadog / Shopify / GTM / invented connectors
- Not for pausing / budgeting (→ `omneky-pause-budget`) or launching
(→ `omneky-launch-manage`)
## OpenAI runtime contract
- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.
- 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.
- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.
- 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.
- Never invent tokens; OAuth is host-managed. Never ask the user to paste a JWT or API key into chat.
## Non-negotiable output / safety contract
- Wire name for X Ads is **`twitter`**, never `x`.
- Hand the user the OAuth / connect URL; they finish in the browser. Do not
claim the channel is connected until a status re-check says so.
- OpenAI Ads / PostHog keys are forwarded **once** by the tool and never
logged back — do not echo keys into chat.
- Destructive disconnects (`disconnect_posthog`, `disconnect_google_drive`)
need an Approve widget / explicit confirm; prefer leave-connected unless
the user asked to disconnect.
- Never invent Pinterest / Twitter disconnect tools if absent from
`tools/list`.
- After connect, offer next step: launch (`omneky-launch-manage`) or
verify with a read-only list (`get_campaigns`).
## Staged workflow
### Stage 1 — Resolve brand
1. If `brand_id` unknown: `list_brands` → brand picker → `get_brand_details`.
2. Snapshot: `list_connector_statuses`.
### Stage 2 — Paid-media channel connect (Meta / Google / TikTok / LinkedIn / Reddit / Pinterest / X)
1. `get_channel_connection_status` with the correct `channel`
(`facebook` / `google` / `tiktok` / `linkedin` / `reddit` /
`pinterest` / `twitter`). Pinterest also has
`get_pinterest_connection_status`.
2. If disconnected: `get_channel_connect_url` — show the URL; end turn if
wa
Preview of the first 4,000 characters. Read full instructions →
omneky-voice-and-video-clone4.43 KB
View saved version →
---
name: omneky-voice-and-video-clone
description: >-
Clone an Omneky speaker voice or a winning brand-library video. Use
for clone voice or clone a winning video. Do not use for still
image ads (omneky-image-ads), product video commercials
(omneky-product-video), new avatar/UGC renders
(omneky-avatar-ugc), edit or resize (omneky-edit-and-resize),
ROAS-only (omneky-analytics-and-catalogue), competitor analysis
(omneky-competitor-analysis), A/B tests (omneky-ab-tests),
weekly plans (omneky-marketing-plan), first-run onboarding
(omneky-onboarding), agency (omneky-agency), launch/connect
(omneky-launch-and-connect), or credit-balance-only
(omneky-billing). Keywords: clone voice, clone a winning video,
competitor video format, with our product, speaker sample.
---
# Voice clone and clone a winning video
Use this when the user wants to clone a voice from a speaker sample,
or remake a winning video for their product. One job: voice clone
and clone-a-winning-video. A new talking-head is `omneky-avatar-ugc`.
Gate on the clone tools being on `tools/list`; a missing tool → the
Omneky app.
Step detail: [playbook](references/playbook.md) (hard rules, voice
clone, clone a winning video).
Handoff fields: [handoff-contract](../_shared/references/handoff-contract.md).
Sourced ids (how to obtain / what to do if absent): [preconditions](../_shared/references/preconditions.md).
Quote, retry, and polls: [creative-pricing-and-polling](../_shared/references/creative-pricing-and-polling.md).
Acceptance gates: [creative-quality-gates](../_shared/references/creative-quality-gates.md).
Structured brief: [creative-brief](../_shared/references/creative-brief.md).
QA and cheapest repair: [media-qa-and-repair](../_shared/references/media-qa-and-repair.md).
Other intents: [capability-registry](../_shared/references/capability-registry.md).
Write for: [marketer-persona](../_shared/references/marketer-persona.md).
## Goal
Clone a consented voice or a winning library video onto our product. Not a new talking-head.
## When to use
- Clone voice, clone a winning video, competitor-format clone with our product
## When not to use
- New UGC talking-head → `omneky-avatar-ugc`
- Narrator on an uploaded file → decline (gap)
## Prerequisites
| Need | Check | If missing |
|---|---|---|
| Brand | `list_brands` | Ask which |
| Consent (voice) | user yes | Stop |
| Voice sample | HTTPS `voice_url` | Ask for a public link; no upload |
| Voices list | `find_avatars_and_voices` (`include="voices"`) | Verify new id under cloned_voices |
| Clone source video | `list_creatives` | Stop if none eligible |
| Product | `get_products` | Create one; clone video always needs `product_id` |
| Cost | no quote tool; state the cost and proceed | Report credits actually charged (`credits_charged`) |
## Flow
**Voice clone**
1. Confirm the speaker consented to cloning.
2. State the cost and call `clone_voice`.
3. Verify the new voice in the `cloned_voices` list from `find_avatars_and_voices` (`include="voices"`).
**Clone a winning video**
1. Find the source with `list_creatives` (a library video,
not a public file).
2. `get_video_metadata`, then `check_clone_video`.
3. State the cost (clone video is priced by length; the result
reports `credits_charged`) and call `clone_video_ad` with
`brand_id`, `product_id`, `video_url`, `locale`, `aspect_ratio`.
Use only `approved_claims` from the handoff or the user; add
`source_evidence` only for performance-informed work.
4. Poll, inspect against the quality gates, and deliver the URL.
## Failure and recovery
Auth / 401 → `omneky-getting-started-and-failures` (host OAuth).
Empty reporting → `get_performance_summary` (`include_coverage=true`); empty is not zero.
`credit_insufficient` → nothing charged; state balance vs required
(`omneky-billing`). No payment links.
`needs_user_decision` → fill the missing detail and call again; ask in plain chat only if you cannot. Never dump JSON.
Missing tool →
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.