ucoz-ad-campaign-landing-skill

name	ucoz-ad-campaign-landing-skill
version	1.0
description	From ad creative to segment landing pages on uCoz: hyper-segmentation (one URL and H1 per ad), UTM packages, Yandex Direct and Google Ads API push with explicit approval, publishing via ucoz-mcp.
author	uCoz
license	MIT
requires	["official ucoz-mcp for page publishing (templates_tool, ftp_tool)",{"optional":"Yandex Direct / Google Ads / Yandex Search API credentials in .env.local for API push and Wordstat"}]
metadata	{"hermes":{"tags":["ucoz","mcp","landing-page","yandex-direct","google-ads","ad-campaign","utm","hyper-segmentation"]},"compatible_agents":["Hermes","Claude Desktop","Cursor","Codex","OpenAI Agents","OpenWebUI","generic MCP clients"],"required_mcp_servers":["ucoz-mcp"]}

Ad Campaign Landing Skill (agent-native)

One skill = from ad creative → segment landing (hyper-segmentation) + UTM package + push to Yandex Direct / Google Ads via API.

Version 1: agent performs all operations natively — without Python scripts. Publishing via MCP (templates_tool, ftp_tool), API requests via Shell (curl), HTML and JSON generated by the agent.

---

Main scenario (creative → landing)

references/PIPELINE.md §2A — ad exists → headline_1 = H1 → separate URL → page_add.

ad (CSV or text)
  → agent builds segments.json (headline_1 = H1, page_ownurl = transliteration)
  → agent checks message match (COPY.md §Message Match)
  → agent generates HTML per LANDING_PLAYBOOK.md rules
  → LANDING_PLAYBOOK.md (page_add, §0.1)
  → agent builds UTM strings
  → (optional) push to Yandex Direct/Google Ads — only with user permission
  → OUTPUT.md

No creative → Wordstat/WebSearch: references/PIPELINE.md §2B (branch 2B).

---

Start with user

No full brief → references/INTAKE.md → brief.json → pipeline.

Must clarify with user (if not stated), before API push and large-scale deployment:

Question	Brief field	Impact
Test or full Yandex Direct API access?	yandex_direct_access	sandbox vs prod host
One landing or separate URL per ad/segment?	landing_scale, max_segments	number of page_add, message match

Branching and checklist: INTAKE.md (§ API access, § Landing scale).

---

What the agent does natively (no scripts)

Task	How agent does it
CSV → segments.json	Reads CSV in context, builds JSON per templates/segments.manifest.example.json
Slug transliteration	Converts headline_1 → latin, 2–4 words, hyphenated
Message match check	Rules from COPY.md §Message Match (overlap_ratio in agent's context)
Landing HTML generation	Per LANDING_PLAYBOOK.md + COPY.md rules
UTM URL building	Per formula from PIPELINE.md §6, URL-encode via Shell if needed
Publishing pages on uCoz	LANDING_PLAYBOOK.md → MCP page_add
Final report	Per OUTPUT.md template, data from segments.json

---

API modes — Yandex Direct and Google Ads

Rule: push only with explicit permission

Before any real API call to Yandex Direct or Google Ads the agent must:

1. Show the user the payload (what exactly will be sent).
2. Ask for permission: "Shall we submit to [sandbox / prod]?"
3. Receive explicit confirmation → execute curl via Shell.

Without confirmation — dry-run description only.

Yandex Direct

Mode	Host	When to use
Sandbox (test)	api-sandbox.direct.yandex.com	Debugging, no live token
Production	api.direct.yandex.com	Real campaigns (created as SUSPENDED)

API structure, payload, authorization: references/DIRECT_API.md

Get OAuth token (manual step for user):

1. Open: https://oauth.yandex.ru/authorize?response_type=code&client_id=<CLIENT_ID>
2. Get code → POST https://oauth.yandex.ru/token → bearer token
3. Save to env: YANDEX_DIRECT_TOKEN=<token>

Google Ads

Mode	How to activate	When to use
Dry-run	Agent describes payload, doesn't call API	Debugging
Test Account	GOOGLE_ADS_CUSTOMER_ID=<test ID>	Test account
Production	GOOGLE_ADS_CUSTOMER_ID=<live ID>	Real campaigns (created as PAUSED)

API structure, payload, authorization: references/GOOGLE_ADS.md

---

Fetching existing ads from account

Agent calls API directly via Shell (curl). Request and response format: references/ADS.md §Fetch.

Full cycle "account → landing → update URL": references/ADS.md §Sync.

---

Rules

Rule	Meaning
Yandex Direct: access mode	Ask test / full; host per INTAKE.md; do not push to prod with test application
Landing scale	Ask single / multi / match_ads; default multi
API push	Only after explicit user permission; show payload before sending
Yandex Direct: no token	DIRECT_API.md → OAuth instructions
Google: no credentials	GOOGLE_ADS.md → developer token, OAuth
Message match	H1 = headline (COPY.md §Message Match)
Ad copy	COPY.md — required before package
URL / segment	page_ownurl + page_add before delivering link
Wordstat	3–5 seeds per brief (RESEARCH.md); fallback — WebSearch
Competitors	research.competitors → competitor_insights (RESEARCH.md §Competitors)
API errors	Billing → key → folder → roles

---

Documentation

File	Content
PIPELINE.md	Full pipeline: branches 2A/2B, steps 0–8, checklist
INTAKE.md	Dialog start, questions, brief.json schema
ADS.md	Ads: CSV import, fetch from account, formats, URL sync
COPY.md	Ad and landing copy, message match
RESEARCH.md	Wordstat API, SERP, competitors, WebSearch fallback
DIRECT_API.md	Yandex Direct API (payload, OAuth, sandbox/prod)
GOOGLE_ADS.md	Google Ads API (setup, push, errors)
LANDING_PLAYBOOK.md	uCoz MCP: page_add, CSS/JS, forms, burger, favicon
OUTPUT.md	Final report and page deployment
EXAMPLE.md	End-to-end examples (3 cases)

---

Prohibitions

• Do not connect separate ucoz-landing-agent — everything is in LANDING_PLAYBOOK.md.
• Do not output final_url before successful page_add.
• Do not use one landing for all ads.
• Do not use page_id=1 for all segments without request.
• Do not push to prod Yandex Direct when yandex_direct_access=test.
• Do not call Yandex Direct / Google Ads API without explicit user permission — show payload first.
• Do not run Python scripts — agent does everything natively.