Work through a single POSIX script scripts/zoomkit.sh. Determine the skill directory from the path of the uploaded SKILL.md and run commands from it:
sh scripts/zoomkit.sh <команда> [параметры]
Dependencies: curl for all network commands; jq for checking request bodies and brief JSON parsing. Read commands without jq still save the full response to a file.
First introduction and connection
If the user is not yet registered, does not know whether they need ZoomKit, or does not have a key, first read GETTING_STARTED.md and execute:
sh scripts/zoomkit.sh getting-started
The command works without a key and network. Explain to the user in simple terms:
- Which manual tasks ZoomKit removes.
- How much the capabilities suitable for them cost.
- Why the service may be beneficial specifically for their volume of work, without promising guaranteed savings.
- The connection procedure: registration, an initial top-up of approximately 500 rubles, issuing a key, saving it to
config/.envand verification.
Prices change. For a question about the cost “right now,” check the built-in pricing block on the official page https://zoomkit.ru/help; use the related external document only if it opens. If the network cannot be checked, explicitly state the date of the reference snapshot from GETTING_STARTED.md. Do not claim that the public list covers all charges. Do not promise a free period, a discount, or any other promotion without confirmation on the official website.
config/.env inside the skill directory — the standard persistent key storage. The script reads it on every run, and the file persists between sessions. Always offer this method for normal operation; the environment variable is needed only as a temporary override. Do not claim that the container will delete the file, that it will have to be created in every session, or that the skill can be used only from Claude Code or a local shell.
Do not start an introduction with a request for a key and do not ask to paste it into the chat. If the user has decided to connect, walk them through the steps from config/README.md: registration or sign-in → top up balance → issue a key → record in config/.env → command token. For a first introduction, suggest 500 rubles as a small starting amount, not as a documented minimum; remind them to check the total with the 6% added at payment.
Before requesting profile data, check the key:
sh scripts/zoomkit.sh token
If there is no key, the scenario will end before the network request and will show the benefit of the service and the entire connection procedure. Do not limit yourself to the answer "I can't": give the user the steps, wait for the key to be saved to a persistent config/.env, then repeat token and the original request.
If a saved key exists but token returns HTTP 401, do not repeat the initial registration and do not offer to top up the balance again. Ask them to sign in to the existing account, issue a replacement for the invalid key, update ZOOMKIT_API_TOKEN in the same config/.env and repeat token. If the key is temporarily overridden by an environment variable of the same name, it must also be updated or removed.
If the user asks only about invoicing or payment capabilities, a key is not needed: start with billing-capabilities and the next section. Offer key setup only if you need to read the balance or existing invoices.
Checks of accounts and campaigns
For reports with waiting, checks across multiple accounts, bid rules, autotargeting, and link checking, first read AUDIT_WORKFLOWS.md. It notes which of the checks are complete, partial, or unavailable via the API.
If the user calls connected entities "projects" or "accounts", perform clients: it is "List of projects/accounts" that is the official name of the method /stats/clients. Show integrations and nested projects/accounts — ad cabinets, without correcting the user's terminology unnecessarily.
If a specific Yandex.Direct cabinet cannot be found by name or comment, check the full saved response clients, not just the abbreviated table. Do not claim that the cabinet is not connected while among the results yandex.direct there are accounts with an empty comment and an unclear technical name, especially porg-*. If the user knows that the cabinet exists, give the manual instruction from the section "If the cabinet cannot be recognized": https://zoomkit.ru/yandex/direct → "Clients and daily spend" → fill in the "Comment" field for all unclear accounts → repeat clients. Do not guess the match by technical name or identifier.
For the list of campaigns, first run clients, take id of the nested cabinet yandex.direct, then call campaigns --client ID. Do not confuse this ClientId with the integration identifier. Use the obtained campaign IDs for bidrules, url-check-settings and other campaign checks.
API 1.9.0 returns a list from ZoomKit data, so take into account updated_at and show hints. Archived campaigns are included in the response, and can_set_bids shows suitability for bid management. The campaign wizard and product campaigns are not passed by Yandex.Direct to ZoomKit; a recently created EPC or another campaign may appear after the cabinet is updated. Do not run a modifying client-update for a diagnostic request without the user's explicit permission.
A diagnostic request does not permit modification. In particular, do not run autotargeting for a "check" request: this command immediately creates the missing rules in suitable non-archived campaigns of the key's active cabinets. Execute it only after a separate explicit request for correction and showing the user the Yandex key identifier.
Important limitation on accounts
The official API 1.9.0 can only read the balance and the list of already issued invoices. It does not allow creating an invoice, passing arbitrary details, or getting a printable form or payment link.
When requesting a new invoice or link:
- Explain the API limitation and give a link
https://zoomkit.ru/profile. - If the key is already configured or the user separately asks to check their invoices, execute
invoices --status wait. - Do not guess private addresses and do not send invented fields. Details: BILLING.md.
To check capabilities without a key:
sh scripts/zoomkit.sh billing-capabilities
Read commands
| Command | Purpose | Parameters |
|---|---|---|
token |
State of the current key | — |
balance |
Balance, daily rate, days remaining | — |
invoices |
Already issued invoices | --status wait|paid|cancelled, --limit N |
clients |
Integrations and nested projects/accounts (advertising accounts) | — |
campaigns |
Campaigns of the Yandex.Direct account according to ZoomKit data | --client ID, optional --limit N |
reports |
List of reports | — |
report |
State and result of the report | --id ID |
report-wait |
Wait for READY or FAILED, no more than 55 seconds per run |
--id ID, optional --interval, --timeout |
bidrules |
Campaign bid rules | --campaign ID |
url-check-settings |
Link check settings | --campaign ID |
url-check-tasks |
Latest link checks | --campaign ID |
url-check-task |
Report of one check | --campaign ID --task ID |
The full response is saved to cache/latest-<команда>.json; the exception is report-wait, which by default writes cache/report-<ID>.json, so that parallel waits do not mix. Standard output remains short. --output ПУТЬ changes the destination file. --raw prints the entire JSON and is suitable only for small responses.
Modification commands
| Command | Method | Required parameters |
|---|---|---|
report-create |
Create report | --body ФАЙЛ --confirm |
report-delete |
Delete report | --id ID --confirm |
client-update |
Queue an account update | --client ID --confirm |
autotargeting |
Add missing autotargeting rules in suitable non-archived campaigns of the key's active accounts | --token-id ID --confirm |
bidrule-common-update |
Change the general bid rule | --campaign ID --body ФАЙЛ --confirm |
bidrule-keywords-create |
Create a rule for phrases | --campaign ID --body ФАЙЛ --confirm |
bidrule-keywords-update |
Change the rule for phrases | --campaign ID --bidrule ID --body ФАЙЛ --confirm |
bidrule-keywords-delete |
Delete the rule for phrases | --campaign ID --bidrule ID --confirm |
url-check-settings-update |
Change the link check toggles | --campaign ID --body ФАЙЛ --confirm |
Before making a change, show the user the target IDs and the request body content. Pass --confirm only after an explicit request for this change. To preview the command, use --dry-run: no network or key is required.
Request body templates are located in assets/. Copy the needed file to a temporary or working directory and modify the copy; do not edit the original template. To protect the item from a 404 and the control string disappearing, you can take assets/url-check-product-protection.example.json, but set the string itself manually according to settings_url. The template explicitly sets the entire set of auto-pause conditions: before confirming, compare it with the current settings and show the user which conditions will be enabled and disabled.
For change commands with --body the script does not send the body until jq confirms that the file contains a valid JSON object.
References
- Benefits, plans, and the onboarding scenario: GETTING_STARTED.md.
- Seven verification scenarios and API boundaries: AUDIT_WORKFLOWS.md.
- All paths, response codes, and limits: API_REFERENCE.md.
- Invoices, balance, and payment methods: BILLING.md.
- Creating and retrieving reports: REPORTS.md.
- Bid rules and link checks: YANDEX_DIRECT.md.