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](references/PIPELINE.md)** — ad exists → `headline_1` = H1 → separate URL → `page_add`.

```text
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](references/PIPELINE.md)** (branch 2B).

---

## Start with user

No full brief → **[references/INTAKE.md](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](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](references/GOOGLE_ADS.md)**

---

## Fetching existing ads from account

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

Full cycle "account → landing → update URL": **[references/ADS.md §Sync](references/ADS.md)**.

---

## 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](references/PIPELINE.md) | **Full pipeline: branches 2A/2B, steps 0–8, checklist** |
| [INTAKE.md](references/INTAKE.md) | **Dialog start, questions, brief.json schema** |
| [ADS.md](references/ADS.md) | **Ads: CSV import, fetch from account, formats, URL sync** |
| [COPY.md](references/COPY.md) | **Ad and landing copy, message match** |
| [RESEARCH.md](references/RESEARCH.md) | **Wordstat API, SERP, competitors, WebSearch fallback** |
| [DIRECT_API.md](references/DIRECT_API.md) | Yandex Direct API (payload, OAuth, sandbox/prod) |
| [GOOGLE_ADS.md](references/GOOGLE_ADS.md) | Google Ads API (setup, push, errors) |
| [LANDING_PLAYBOOK.md](references/LANDING_PLAYBOOK.md) | **uCoz MCP: page_add, CSS/JS, forms, burger, favicon** |
| [OUTPUT.md](references/OUTPUT.md) | Final report and page deployment |
| [EXAMPLE.md](references/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.