vk-ads-operator - SKILL.md Agent Skill

name: vk-ads-operator description: "Use when Codex should operate the central VK Ads control plane: resolve project, inspect campaign data, validate plans, generate manual execution packs, and only then consider guarded writes."

VK Ads Operator

Purpose

Use the central control plane instead of hand-building VK Ads payloads inside the conversation. For manual cabinet handoff, use the manual execution pack and launch-session chain.

Offline Official Docs

Local official VK API snapshot: docs/reference/vk-api-official-snapshot/.
Auditor single-file copy: audit/VK_API_OFFICIAL_DOCS_FOR_AUDITOR.md.
Use this snapshot when dev.vk.com or VK Ads docs are unreachable without Russian VPN.
If a required VK API method, field, enum, or payload shape is missing from the local snapshot and existing repo evidence, ask Vitaly to retrieve the official page through VPN before designing or executing the payload.

Workflow

Resolve project_key from explicit input or .vkads-project.yaml.
Read project context and capabilities.
For planning, launch handoff, or hybrid launch rehearsal, run:
- vkads_validate_campaign_plan
- vkads_generate_manual_execution_pack
- vkads_validate_manual_execution_pack
- vkads_create_launch_workspace
- vkads_validate_hybrid_launch_readiness
- vkads_estimate_guardrails
When the operator has moved the plan into the cabinet, record the launch with vkads_record_manual_launch_session.
For Stage 5A/5B hybrid launch readiness, keep the sidecar honest:
- vkads_capture_cabinet_snapshot
- vkads_resolve_launch_workspace_against_cabinet
- vkads_generate_api_payload_draft
- vkads_generate_real_cabinet_operator_runbook
- vkads_record_readback_after_manual_launch
- if you are promoting live-read evidence, run pnpm smoke:live-read with explicit VKADS_SMOKE_PROJECT_KEY, VKADS_SMOKE_WORKSPACE_PATH, and scoped reads before treating registry runtime status as current truth
For Stage 6A battle rehearsal, stay manual-first and use:
- vkads_create_battle_run_candidate
- vkads_run_real_cabinet_preflight
- vkads_generate_battle_run_operator_packet
- vkads_record_operator_checkpoint
- vkads_capture_battle_run_snapshot
- vkads_reconcile_battle_run_readback
- vkads_generate_battle_run_closeout
For Stage 6B controlled launch overlays, only continue after explicit user approval:
- vkads_record_controlled_launch_approval
- vkads_ingest_manual_results with analysisPoint=day0|day1 and linked battleRunId
- vkads_run_day1_controlled_review
- vkads_generate_stage6b_controlled_launch_closeout
For Stage 7A controlled hybrid live create, stay on the guarded path:
- vkads_validate_live_create_candidate
- vkads_create_campaign with executionMode=controlled_live_create
- vkads_record_operator_checkpoint with live_create_approved, campaign_created_via_api, manual_fields_completed, and manual_submit_completed as needed
- vkads_capture_live_create_readback
- vkads_generate_stage7a_live_create_closeout
If moderation rejects the launch or the cabinet UI diverges from the verified field map, record that with:
- vkads_ingest_moderation_feedback
- vkads_record_manual_ui_observation
After launch, keep the manual loop consistent:

vkads_ingest_manual_results
vkads_generate_optimization_recommendations
vkads_revise_campaign_plan when the revision note is ready

For Stage 9A-9K user-visible micro-pilots, use guided-production-pilot-dev; prefer create-primary automation when live-write gates and existing lead-form evidence are available:

vkads_start_pilot_run
vkads_generate_pilot_launch_pack
vkads_validate_pilot_go_no_go
vkads_resolve_pilot_api_create_inputs to resolve lead form, geo, package, package banner pattern, and approved creative refs before a retry
vkads_prepare_pilot_api_create_preview to review the planned campaign + ad group + ad entity tree
vkads_execute_pilot_api_create only after exact approval, project lock, budget caps, and redacted readback gates pass
vkads_record_pilot_manual_launch
vkads_readback_pilot
vkads_record_pilot_observation
vkads_recommend_pilot_next_action
vkads_close_pilot_run

For Stage 10R/10S stopped method drafts, use fast-create-dev; do not reuse Stage 9 REST v2 banner payload assumptions:

vkads_prepare_fast_create_run to pick vk_api_methods_classic_ad_draft_v1, run redacted method preflight, and generate approval.txt
vkads_method_targeting_preflight when link/audience checks are needed without creating artifacts
vkads_method_readback to inspect method-visible campaign/ad state
vkads_execute_fast_create_run only after the exact APPROVE VKADS METHOD CREATE ... status=stopped ... text, project lock, and live-write gates pass

For Stage 11A daily operations, stay read-only and use the existing CLIs:

pnpm hermes:daily-report for daily spend/click/lead/CPL decisions
pnpm darky:lead-alerts -- --env-check before enabling notifications
pnpm darky:lead-alerts -- --dry-run or --initialize-baseline before any live Telegram delivery

For Stage 11B and later local operator runs, prefer the canonical ignored .env.local / VKADS_ENV_FILE env bootstrap. Never print env values; env-check output must stay <set>/<missing>.
Only use live write tools after explicit user confirmation and only if the control plane allows the requested execution mode.

Hard Rules

Do not bypass registry or guardrails.
Do not invent raw VK Ads payloads when the control plane has a normalized request schema or manual execution pack.
Do not invent VK API method details from memory. Check docs/reference/vk-api-official-snapshot/ first; if the official method details are missing, ask Vitaly for the source page instead of guessing.
Do not treat ApiPayloadDraft as executable; it remains a non-executable sidecar in Stage 5/6/7.
Do not expose raw vkads_create_campaign through guided-production-pilot-dev; Stage 9 create goes only through vkads_execute_pilot_api_create.
Do not claim full Stage 9 entity-tree success unless redacted readback confirms campaign + ad group + ad.
Stage 9H may accept campaign + ad group as a minimum shell result only with truthful outcome campaign_ad_group_created_banner_manual_required and a manual banner completion packet.
Stage 9J child banner create sends a single content object and must not send patterns or textblocks; its live rejection showed scalar content.* values are invalid.
Stage 9K child banner create keeps content but wraps text fields as { text: ... } and media fields as { id: ... }; it must not send patterns, textblocks, or scalar content.*.
Do not reuse rejected Stage 9C/9D/9E/9F/9G/9H/9J approval text for Stage 9K; generate a fresh executable preview and wait for a fresh exact approval.
Stage 9G may use VK validation-error pattern candidates only as bounded runtime evidence: max three attempts, raw IDs runtime-only, no submit/moderation/paid launch.
Stage 10R/10S treats vk_api_methods, vk_ads_rest_v2, and manual_cabinet as separate families. Do not port patterns, textblocks, or content.* assumptions from REST v2 into ads.createAds.
Stage 10S requires VKADS_METHOD_ACCESS_TOKEN for vk_api_methods; method calls must not fall back to VK Ads REST client-credentials tokens.
Stage 10R/10S method creates must stay stopped: status=0, one campaign/ad maximum per approval, no moderation submit, no paid launch.
Do not expose raw ads.createCampaigns or ads.createAds; use only vkads_execute_fast_create_run in fast-create-dev.
Stage 11A/11B are read-only. Do not add banner-create retries, lifecycle writes, new write profiles, or new MCP tools for the daily operations baseline.
Lead-alert repo artifacts and state files must not contain lead phone numbers, names, raw answers, tokens, headers, or raw VK IDs. Telegram may contain lead PII only in the live notification path after the operator intentionally runs non-dry-run alerts.
Do not treat read-only annotations as a substitute for artifact review.
Treat vkads_create_campaign as a guarded live-write tool and never use it outside controlled-live-create-dev.

References

references/tool-contracts.md
docs/reference/vk-api-official-snapshot/
audit/VK_API_OFFICIAL_DOCS_FOR_AUDITOR.md
The manual execution artifact contract and UI evidence docs in the repo.