64 Silverov

direct Skill

Yandex Direct(API v5)广告审计、管理和优化。提供完整账户审计、广告系列管理、关键词操作、报表、预算分析以及面向俄罗斯市场 PPC 的优化建议。触发词:"Яндекс Директ"、"Yandex Direct"、"директ"、"РСЯ"、"YAN"、"direct audit"、"direct campaigns"、"direct report"、"direct optimize"。

安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。

查看源码

技能指令原文(SKILL.md)

Yandex Direct — PPC Audit & Management (API v5 / v501)

Authors: Nick Serebrov & Kobe 🐍
Version: 2.0.2 — актуально на октябрь 2026

Full-cycle Yandex Direct management: account audits, campaign CRUD, keyword
management, reporting, optimization, and budget analysis.

Quick Reference

| Command | What it does |
|---------|-------------|
| /direct audit | Full account audit (all campaigns), scoring 0-100 |
| /direct campaigns | List campaigns with type, strategy, weekly budget and stats |
| /direct create | Create a Unified Performance Campaign with groups, keywords, combinatorial ads |
| /direct keywords | Keywords and autotargeting (list, add, bids, categories, pause) |
| /direct report | Performance stats by priority Metrika goals (CTR, CPC, CPA, spend) |
| /direct optimize | Optimization recommendations (pause losers, adjust bids and limits) |
| /direct budget | Weekly budget spend analysis and forecasting |
| /direct negative | Negative keywords (campaign, group, shared sets) from search queries |

What changed in Direct (know this before acting)

| Date | Change | Consequence for the agent |
|------|--------|---------------------------|
| 2023-11 → 2024 | Unified Performance Campaign (UNIFIED_CAMPAIGN, ЕПК) replaced text-image, dynamic and smart-banner campaigns | Read UnifiedCampaignFieldNames; search and YAN live in one campaign — split stats by AdNetworkType |
| 2024-07-01 | Manual bids in YAN disabled | Manual strategy (HIGHEST_POSITION) is search-only |
| 2025-06, 2025-09 | New strategies: AVERAGE_CPA_MULTIPLE_GOALS, PAY_FOR_CONVERSION_MULTIPLE_GOALS, MAX_PROFIT | See references/bidding-strategies.md |
| 2025-11-13 | bidmodifiers.toggle removed | Use set (100 = off) or delete |
| 2026-03-20 | Combinatorial ads (RESPONSIVE_AD): up to 7 titles, 3 texts, 5 images, 6 videos | Request ResponsiveAdFieldNames, otherwise the API returns them as TextAd with only the first title/text/image |
| 2026-06-30 / 07-14 | Text-image ads in ЕПК are edit-only; existing ones converted to combinatorial | ads.add with TextAd creates RESPONSIVE_AD; Title2 is merged into the title (≤ 56 chars) or lost |
| 2026-06-22 / 07-06 | Weekly budgets for manual-bid campaigns and shared account; up to 30% of unspent budget rolls over | Analyse WeeklySpendLimit, not a daily budget |
| 2026-03-01 | Russian language rules for consumer information | Flag foreign words without Russian equivalents in ads (references/compliance.md) |

API Configuration

Credentials: ~/.secrets/yandex-direct.json (chmod 600)

{ "client_id": "...", "client_secret": "...", "oauth_token": "...", "client_login": "optional-for-agency" }
  • Endpoint: https://api.direct.yandex.com/json/v5/; Unified-campaign structures

(UnifiedCampaign, UnifiedAdGroup, ShoppingAd, ListingAd) in add/update go to /json/v501/ —
scripts/yd-api.sh routes them automatically.

  • Read campaigns and ad groups from v501 too: v5 shows a Unified campaign as TEXT_CAMPAIGN (groups as

TEXT_AD_GROUP) without UnifiedCampaign settings such as search PlacementTypes. yd-api.sh routes get
requests with UnifiedCampaign/UnifiedAdGroup field names to v501; otherwise set YD_API_VERSION=v501.

  • Auth: Authorization: Bearer {oauth_token}; agency or representative access: Client-Login: {client_login}.
  • Sandbox: YD_SANDBOX=1. Env overrides: YD_TOKEN, YD_CLIENT_LOGIN, YD_API_VERSION, YD_SECRETS.
  • Money in API requests and responses is in micro-units (× 1 000 000). Reports use rubles

(returnMoneyInMicros: false).

API limits that break naive requests:

  • adgroups.get, keywords.get, ads.get, bidmodifiers.get: CampaignIds ≤ 10 per request, AdGroupIds ≤ 1000.
  • Every get returns ≤ 10 000 objects; continue with Page.Offset = LimitedBy.
  • negativekeywordsharedsets.get: Ids ≤ 30; omit SelectionCriteria to get all sets. Same for sitelinks.get.
  • sitelinks.get: FieldNames: ["Id"] plus SitelinkFieldNames — "Sitelinks" in FieldNames together with

SitelinkFieldNames is error 4004.

  • ads.get: TextAdFieldNames has AdExtensions, not AdExtensionIds (that is a filter / an add field).
  • Reports: Goals ≤ 10; AttributionModels only AUTO, LSCCD, FCCD, LC; ≤ 5 offline reports in queue;

one request per 10 s (error 56, HTTP 400) — yd-report.sh polls every ≥ 10 s and retries error 56.
The CampaignType report column shows a Unified campaign as TEXT_CAMPAIGN — take the type from campaigns.get v501.

  • ads.get: AutogeneratedErirAdDescription exists only in TextAdFieldNames; combinatorial ads have no such field

(error 8000) — check the auto description in the web interface.

  • keywords.get: Productivity is always null; AutotargetingCategories is deprecated — use

AutotargetingSettings (AutotargetingSettingsCategoriesFieldNames, AutotargetingSettingsBrandOptionsFieldNames).

Troubleshooting:

  • Empty HTTP 204 to every request, even with a wrong token → the Direct API is turned off on Yandex's side

(e.g. the special mode after the October 2026 data-center incident: only the web interface and the mobile app
work, see https://yandex.ru/support/direct/ru/special-mode). Not a token, IP or script problem — wait, and
meanwhile use the web interface for read-only checks.

  • yd-audit.sh says «no campaigns found» → all campaigns may be archived; rerun with --include-archived

(the script prints the archived count when it can).

  • The campaigns grid labels strategies «Оптимизация кликов» / «Оптимизация конверсий»; the API type is in

BiddingStrategyType (see references/bidding-strategies.md).

Safety rule for changes

Every write call (add, update, delete, suspend, resume, archive, moderate, bids, set)
is made only after the user approved that exact change: show the request JSON (or a readable diff of
what changes) and wait for an explicit yes. Audit, report and optimize are read-only.

Orchestration Logic

/direct audit

  1. Run scripts/yd-audit.sh — collects all objects (chunked by 10 campaigns, paginated) and 4 reports

for the last 30 days using the campaigns' priority goals (--goals to override).

  1. Read /summary.json: errors, campaign and ad types, goals used.
  2. Hand the directory to agents/audit-yandex.md (or run its steps): 55 checks from

references/yandex-audit.md, scoring from references/scoring-system.md.

  1. Report in Russian: grade (A–F), findings, Quick Wins, prioritized action plan.

/direct campaigns

  1. campaigns.get (v501): FieldNames Id, Name, Type, State, Status, StatusClarification, Statistics;

UnifiedCampaignFieldNames and TextCampaignFieldNames: BiddingStrategy, PriorityGoals, CounterIds.

  1. Table: type, state, search/network strategy, weekly limit (WeeklySpendLimit / 1 000 000), goals.
  2. Spend and conversions — from scripts/yd-report.sh campaign --by-network --goals .

/direct create

  1. Gather: name, geo, weekly budget, strategy and goal, landing URL, keywords, 3–7 titles, 2–3 texts, images.
  2. adimages.add (base64, Type: AUTO) → image hashes; see references/image-specs.md.
  3. campaigns.add with UnifiedCampaign (v501): BiddingStrategy.Search/Network, CounterIds,

PriorityGoals, Settings (ADD_METRICA_TAG, ENABLE_SITE_MONITORING), TrackingParams with UTM.

  1. adgroups.add with UnifiedAdGroup (v501): RegionIds, negatives.
  2. keywords.add: phrases and/or ---autotargeting with AutotargetingSettings (categories, brand options).
  3. sitelinks.add (up to 8 per set) and adextensions.add (CALLOUT).
  4. ads.add with ResponsiveAd: Titles, Texts, Href, AdImageHashes, SitelinkSetId, AdExtensionIds,

BusinessId if there is a Yandex Business profile. Do not use TextImageAd for this — it is an image-only banner.

  1. ads.moderate — only after the user reviewed the drafts.

/direct keywords

  1. keywords.get by AdGroupIds or ≤ 10 CampaignIds; include ServingStatus and autotargeting settings.
  2. Operations: add, suspend, resume, delete, bids (keywordbids.set with manual strategy), autotargeting categories.
  3. Performance — scripts/yd-report.sh criteria (Criterion, CriterionType), not the deprecated Productivity.

/direct report

  1. scripts/yd-report.sh : account, campaign, adgroup, ad, criteria, search_query, placement, custom.
  2. Always pass --goals with priority goals (from campaigns.get → PriorityGoals): without it conversions

are summed over ALL Metrika goals, including micro-goals.

  1. For Unified campaigns add --by-network to separate search and YAN.
  2. Dates: --from/--to (default: 30 days ending yesterday) or --period LAST_7_DAYS. Offline reports are polled

automatically (retryIn header).

/direct optimize

  1. Reports for 30 days with goals: criteria, search_query, placement, campaign --by-network.
  2. Find: conditions and queries with spend > 2× target CPA and no conversions; YAN placements to exclude;

network vs search CPA gap inside one campaign; groups with RARELY_SERVED; rejected ad elements.

  1. Compare with the account's own medians first, then references/benchmarks.md.
  2. Recommendations sorted by impact; 3× Kill Rule: flag anything with CPA > 3× target.
  3. Do not touch strategy, its spend-limit type or payment model during learning (references/bidding-strategies.md).

/direct budget

  1. Weekly limits from BiddingStrategy.*.WeeklySpendLimit (or CustomPeriodBudget for flights).
  2. Spend by day — yd-report.sh campaign --daily --from ; run rate and weekly forecast.
  3. Flag: limit hit before the end of the week; spend < 70% of the limit; pay-per-conversion budget < 10 × CPA;

weekly budget < 300 ₽. Unspent budget of CPC campaigns rolls over (up to 30%) since 06.07.2026.

/direct negative

  1. Campaign and group negatives (NegativeKeywords) and shared sets (negativekeywordsharedsets.get, all sets).
  2. yd-report.sh search_query --goals … → irrelevant queries with spend and no conversions.
  3. Propose negatives (campaign level or shared set); apply via campaigns.update / negativekeywordsharedsets.update

after approval.

Quality Gates

  • Write operations only after explicit approval of the exact change.
  • Conversion analysis only on priority goals; never on the all-goals sum.
  • 3× Kill Rule: flag keywords/groups/placements with CPA > 3× target for pause.
  • Strategy learning: goal ≥ 10 conversions a week; don't change strategy, spend-limit type or payment model

in the first 2–3 weeks; a pause > 7 days restarts learning.

  • Budget: weekly budget ≥ 300 ₽; pay-per-conversion ≥ 10 × CPA.
  • Moderation: check Status/StatusClarification of ads and of each combinatorial element before optimizing.
  • Tracking: ADD_METRICA_TAG on, UTM via TrackingParams (campaign or group) or in Href.

Reference Files

Load on-demand, NOT at startup:

  • references/yandex-audit.md — 55 audit checks (YD01-YD55) with data sources
  • references/scoring-system.md — Weighted scoring (0-100, grades A-F)
  • references/benchmarks.md — How to compare metrics; rough Russian market references
  • references/bidding-strategies.md — ЕПК strategies ↔ API, weekly budgets, learning, bid modifiers
  • references/compliance.md — Yandex moderation rules, ad marking, Russian language rules
  • references/image-specs.md — Images and video for combinatorial ads

Scripts

  • scripts/yd-api.sh — Generic API call wrapper (v5/v501 routing, Client-Login, item-level error detection)
  • scripts/yd-report.sh — Reports wrapper (presets, goals, attribution, offline polling)
  • scripts/yd-audit.sh — Automated audit data collection (all objects + 4 reports)

Requirements: bash, curl, jq.

Subagents

  • agents/audit-yandex.md — Audit subagent for parallel campaign analysis

配合站内内容