{"id":"bf701d8b-b5fc-4cc0-83e8-5fbb5479a118","shortId":"rSR7au","kind":"skill","title":"bitrix24-agent","tagline":"Design, implement, debug, and harden integrations between AI agents and Bitrix24 REST API (webhooks, OAuth 2.0, scopes, events, batch, limits, and REST 3.0). Use when asked to connect AI assistants/agents to Bitrix24, automate CRM/tasks/chats, process Bitrix24 events, choose an a","description":"# Bitrix24 Agent (Lean + Reliable)\n\nUse this skill to deliver correct Bitrix24 integrations with low token usage and production-safe defaults.\n\n## Quick Start\n\nUse this flow unless the user asks for a different one:\n\n1. Pick intent + one minimal pack (`core` by default).\n2. Run a read probe first.\n3. For writes, use plan then execute with confirmation.\n\nRead probe:\n\n```bash\npython3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}'\n```\n\nSafer write flow:\n\n```bash\npython3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \\\n  --params '{\"fields\":{\"TITLE\":\"Plan demo\"}}' \\\n  --packs core \\\n  --plan-only\n\npython3 skills/bitrix24-agent/scripts/bitrix24_client.py \\\n  --execute-plan <plan_id> \\\n  --confirm-write\n```\n\n## Runtime Prerequisites\n\nRequired environment:\n\n- `B24_DOMAIN`\n- `B24_AUTH_MODE` = `webhook` or `oauth`\n\nWebhook mode:\n\n- `B24_WEBHOOK_USER_ID`\n- `B24_WEBHOOK_CODE`\n\nOAuth mode:\n\n- `B24_ACCESS_TOKEN`\n- `B24_REFRESH_TOKEN`\n- `B24_CLIENT_ID` and `B24_CLIENT_SECRET` (for `--auto-refresh`)\n\nUseful safety/reliability flags:\n\n- `B24_REQUIRE_PLAN=1` for mandatory plan->execute on write/destructive calls\n- `B24_PACKS=core,...` for default pack set\n- `B24_RATE_LIMITER=file` with `B24_RATE_LIMITER_RATE` and `B24_RATE_LIMITER_BURST`\n\n## Default Mode: Lean\n\nApply these limits unless the user asks for deep detail:\n\n- Load at most 2 reference files before first actionable step.\n- Start from `references/packs.md`.\n- Then open only one target file: `references/catalog-<pack>.md`.\n- Open `references/chains-<pack>.md` only if the user needs workflow steps.\n- Open `references/bitrix24.md` only for auth architecture, limits, event reliability, or unknown errors.\n\nResponse limits:\n\n- Use concise output (goal + next action + one command).\n- Do not retell documentation.\n- Do not dump large JSON unless requested.\n- Return only delta if guidance was already given.\n\n## Routing Workflow\n\n1. Determine intent:\n- method call\n- troubleshooting\n- architecture decision\n- event/reliability setup\n\n2. Normalize product vocabulary:\n\n- \"collabs\", \"workgroups\", \"projects\", \"social network groups\" -> `collab` (and `boards` for scrum).\n- \"Copilot\", \"CoPilot\", \"BitrixGPT\", \"AI prompts\" -> `platform` (`ai.*`).\n- \"open lines\", \"contact center connectors\", \"line connectors\" -> `comms` (`imopenlines.*`, `imconnector.*`).\n- \"feed\", \"live feed\", \"news feed\" -> `collab` (`log.*`).\n- \"sites\", \"landing pages\", \"landing\" -> `sites` (`landing.*`).\n- \"booking\", \"calendar\", \"work time\", \"time tracking\" -> `services` (`booking.*`, `calendar.*`, `timeman.*`).\n- \"orders\", \"payments\", \"catalog\", \"products\" -> `commerce` (`sale.*`, `catalog.*`).\n- \"consents\", \"consent\", \"e-signature\", \"sign\" -> `compliance` (`userconsent.*`, `sign.*`).\n\n3. Choose auth quickly:\n\n- one portal/internal integration: webhook\n- app or multi-portal lifecycle: OAuth\n\n4. Select minimal packs:\n\n- default `core`\n- add only required packs: `comms`, `automation`, `collab`, `content`, `boards`, `commerce`, `services`, `platform`, `sites`, `compliance`, `diagnostics`\n\n## Execution Flow (Safe by Default)\n\nCommand template:\n\n```bash\npython3 skills/bitrix24-agent/scripts/bitrix24_client.py <method> \\\n  --params '<json>' \\\n  --packs core\n```\n\nGuardrails to enforce:\n\n- allowlist via packs and `--method-allowlist`\n- write gate with `--confirm-write`\n- destructive gate with `--confirm-destructive`\n- optional two-phase write with `--plan-only` and `--execute-plan`\n- idempotency for writes (auto or `--idempotency-key`)\n- audit trail unless `--no-audit` is explicitly needed\n\n## Reliability and Performance\n\nPagination and sync safety:\n\n- Never stop after first `*.list` page.\n- Keep deterministic ordering and persist checkpoints after successful page persistence.\n\nBatch rules:\n\n- Maximum 50 commands per `batch`.\n- No nested `batch`.\n- Split oversized batches and parse per-command errors.\n\nLimits and retries:\n\n- Treat `QUERY_LIMIT_EXCEEDED` and `5xx` as transient.\n- Use exponential backoff with jitter (client default).\n- Use shared rate limiter keyed by portal in multi-worker setups.\n\nEvents:\n\n- Online events are not guaranteed delivery.\n- For no-loss pipelines, use offline flow:\n  - `event.offline.get(clear=0)`\n  - process idempotently with retry budget\n  - `event.offline.error` for failed items\n  - `event.offline.clear` only for successful/DLQ'ed items\n- Use `scripts/offline_sync_worker.py` as baseline.\n\n## Error Handling\n\nFast mapping:\n\n| Error code | Typical cause | Immediate action |\n|---|---|---|\n| `WRONG_AUTH_TYPE` | method called with wrong auth model | switch webhook/OAuth model for this method |\n| `insufficient_scope` | missing scope | add scope and reinstall/reissue auth |\n| `expired_token` | OAuth token expired | refresh token (`--auto-refresh` or external refresh flow) |\n| `QUERY_LIMIT_EXCEEDED` | burst above portal budget | backoff, queue, tune limiter, reduce concurrency |\n| `ERROR_BATCH_LENGTH_EXCEEDED` | batch payload too large | split batch |\n| `ERROR_BATCH_METHOD_NOT_ALLOWED` | unsupported method in batch | call directly |\n\nEscalate to deep reference (`references/bitrix24.md`) on:\n\n- unknown auth/permission behavior\n- recurring limit failures\n- offline event loss concerns\n- OAuth refresh race or tenant isolation issues\n\n## Quality Guardrails\n\n- Never expose webhook/OAuth secrets.\n- Enforce least-privilege scopes and tenant isolation.\n- Keep writes idempotent where possible.\n- Validate `application_token` in event handlers.\n- Prefer REST v3 where compatible; fallback to v2 where needed.\n\n## Reference Loading Map\n\n1. `references/packs.md` for pack and loading strategy.\n2. `references/catalog-<pack>.md` for method shortlist.\n3. `references/chains-<pack>.md` for implementation chains.\n4. `references/bitrix24.md` for protocol-level troubleshooting and architecture decisions.\n\nUseful search shortcuts:\n\n```bash\nrg -n \"^# Catalog|^# Chains\" references/catalog-*.md references/chains-*.md\nrg -n \"WRONG_AUTH_TYPE|insufficient_scope|QUERY_LIMIT_EXCEEDED|expired_token\" references/bitrix24.md\nrg -n \"offline|event\\\\.bind|event\\\\.offline|application_token\" references/bitrix24.md\n```\n\n## Scripts\n\n- `scripts/bitrix24_client.py`: method calls, packs, allowlist, confirmations, plans, idempotency, audit, rate limiting, retries.\n- `scripts/offline_sync_worker.py`: offline queue polling, bounded retries, DLQ handling, safe clear flow, graceful shutdown.","tags":["bitrix24","agent","skill","vrtalex","agent-skill","agent-skills","ai-agents","bitrix24-api","crm","skills","task-manager"],"capabilities":["skill","source-vrtalex","skill-bitrix24-agent","topic-agent-skill","topic-agent-skills","topic-ai-agents","topic-bitrix24","topic-bitrix24-api","topic-crm","topic-skill","topic-skills","topic-task-manager"],"categories":["bitrix24-skill"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/vrtalex/bitrix24-skill/bitrix24-agent","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add vrtalex/bitrix24-skill","source_repo":"https://github.com/vrtalex/bitrix24-skill","install_from":"skills.sh"}},"qualityScore":"0.456","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 12 github stars · SKILL.md body (6,408 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-24T01:03:02.202Z","embedding":null,"createdAt":"2026-04-23T13:03:46.590Z","updatedAt":"2026-04-24T01:03:02.202Z","lastSeenAt":"2026-04-24T01:03:02.202Z","tsv":"'0':567 '1':78,180,296,730 '2':87,225,306,737 '2.0':19 '3':93,377,743 '3.0':26 '4':392,749 '50':504 '5xx':528 'access':158 'action':230,272,596 'add':398,616 'agent':3,12,45 'ai':11,32,324,327 'allow':662 'allowlist':429,435,799 'alreadi':292 'api':16 'app':385 'appli':212 'applic':712,791 'architectur':258,302,757 'ask':29,73,218 'assistants/agents':33 'audit':469,474,803 'auth':141,257,379,598,604,620,774 'auth/permission':676 'auto':172,464,629 'auto-refresh':171,628 'autom':36,403 'b24':138,140,148,152,157,160,163,167,177,188,195,200,205 'backoff':533,642 'baselin':586 'bash':104,112,420,762 'batch':22,501,507,510,513,649,652,657,659,666 'behavior':677 'bind':788 'bitrix24':2,14,35,39,44,54 'bitrix24-agent':1 'bitrixgpt':323 'board':318,406 'book':351,358 'bound':811 'budget':572,641 'burst':208,638 'calendar':352,359 'call':187,300,601,667,797 'catalog':363,367,765 'caus':594 'center':331 'chain':748,766 'checkpoint':496 'choos':41,378 'clear':566,816 'client':164,168,536 'code':154,592 'collab':310,316,343,404 'comm':335,402 'command':274,418,505,518 'commerc':365,407 'compat':721 'complianc':374,411 'concern':684 'concis':268 'concurr':647 'confirm':101,132,440,446,800 'confirm-destruct':445 'confirm-writ':131,439 'connect':31 'connector':332,334 'consent':368,369 'contact':330 'content':405 'copilot':321,322 'core':84,122,190,397,425 'correct':53 'crm.lead.add':115 'crm/tasks/chats':37 'debug':6 'decis':303,758 'deep':220,671 'default':64,86,192,209,396,417,537 'deliv':52 'deliveri':556 'delta':288 'demo':120 'design':4 'destruct':442,447 'detail':221 'determin':297 'determinist':492 'diagnost':412 'differ':76 'direct':668 'dlq':813 'document':278 'domain':139 'dump':281 'e':371 'e-signatur':370 'ed':581 'enforc':428,698 'environ':137 'error':264,519,587,591,648,658 'escal':669 'event':21,40,260,550,552,682,715,787,789 'event.offline.clear':577 'event.offline.error':573 'event.offline.get':565 'event/reliability':304 'exceed':526,637,651,780 'execut':99,129,184,413,459 'execute-plan':128,458 'expir':621,625,781 'explicit':476 'exponenti':532 'expos':695 'extern':632 'fail':575 'failur':680 'fallback':722 'fast':589 'feed':338,340,342 'field':117 'file':198,227,240 'first':92,229,488 'flag':176 'flow':69,111,414,564,634,817 'gate':437,443 'given':293 'goal':270 'grace':818 'group':315 'guarante':555 'guardrail':426,693 'guidanc':290 'handl':588,814 'handler':716 'harden':8 'id':151,165 'idempot':461,467,569,708,802 'idempotency-key':466 'imconnector':337 'immedi':595 'imopenlin':336 'implement':5,747 'insuffici':612,776 'integr':9,55,383 'intent':80,298 'isol':690,705 'issu':691 'item':576,582 'jitter':535 'json':283 'keep':491,706 'key':468,542 'land':346,348,350 'larg':282,655 'lean':46,211 'least':700 'least-privileg':699 'length':650 'level':754 'lifecycl':390 'limit':23,197,202,207,214,259,266,520,525,541,636,645,679,779,805 'line':329,333 'list':489 'live':339 'load':222,728,735 'log':344 'loss':560,683 'low':57 'mandatori':182 'map':590,729 'maximum':503 'md':242,245,739,745,768,770 'method':299,434,600,611,660,664,741,796 'method-allowlist':433 'minim':82,394 'miss':614 'mode':142,147,156,210 'model':605,608 'multi':388,547 'multi-port':387 'multi-work':546 'n':764,772,785 'need':250,477,726 'nest':509 'network':314 'never':485,694 'news':341 'next':271 'no-audit':472 'no-loss':558 'normal':307 'oauth':18,145,155,391,623,685 'offlin':563,681,786,790,808 'one':77,81,238,273,381 'onlin':551 'open':236,243,253,328 'option':448 'order':361,493 'output':269 'overs':512 'pack':83,121,189,193,395,401,424,431,733,798 'page':347,490,499 'pagin':481 'param':108,116,423 'pars':515 'payload':653 'payment':362 'per':506,517 'per-command':516 'perform':480 'persist':495,500 'phase':451 'pick':79 'pipelin':561 'plan':97,119,124,130,179,183,455,460,801 'plan-on':123,454 'platform':326,409 'poll':810 'portal':389,544,640 'portal/internal':382 'possibl':710 'prefer':717 'prerequisit':135 'privileg':701 'probe':91,103 'process':38,568 'product':62,308,364 'production-saf':61 'project':312 'prompt':325 'protocol':753 'protocol-level':752 'python3':105,113,126,421 'qualiti':692 'queri':524,635,778 'queue':643,809 'quick':65,380 'race':687 'rate':196,201,203,206,540,804 'read':90,102 'recur':678 'reduc':646 'refer':226,672,727 'references/bitrix24.md':254,673,750,783,793 'references/catalog-':241,738,767 'references/chains-':244,744,769 'references/packs.md':234,731 'refresh':161,173,626,630,633,686 'reinstall/reissue':619 'reliabl':47,261,478 'request':285 'requir':136,178,400 'respons':265 'rest':15,25,718 'retel':277 'retri':522,571,806,812 'return':286 'rg':763,771,784 'rout':294 'rule':502 'run':88 'runtim':134 'safe':63,415,815 'safer':109 'safeti':484 'safety/reliability':175 'sale':366 'scope':20,613,615,617,702,777 'script':794 'scripts/bitrix24_client.py':795 'scripts/offline_sync_worker.py':584,807 'scrum':320 'search':760 'secret':169,697 'select':393 'servic':357,408 'set':194 'setup':305,549 'share':539 'shortcut':761 'shortlist':742 'shutdown':819 'sign':373,376 'signatur':372 'site':345,349,410 'skill':50 'skill-bitrix24-agent' 'skills/bitrix24-agent/scripts/bitrix24_client.py':106,114,127,422 'social':313 'source-vrtalex' 'split':511,656 'start':66,232 'step':231,252 'stop':486 'strategi':736 'success':498 'successful/dlq':580 'switch':606 'sync':483 'target':239 'templat':419 'tenant':689,704 'time':354,355 'timeman':360 'titl':118 'token':58,159,162,622,624,627,713,782,792 'topic-agent-skill' 'topic-agent-skills' 'topic-ai-agents' 'topic-bitrix24' 'topic-bitrix24-api' 'topic-crm' 'topic-skill' 'topic-skills' 'topic-task-manager' 'track':356 'trail':470 'transient':530 'treat':523 'troubleshoot':301,755 'tune':644 'two':450 'two-phas':449 'type':599,775 'typic':593 'unknown':263,675 'unless':70,215,284,471 'unsupport':663 'usag':59 'use':27,48,67,96,174,267,531,538,562,583,759 'user':72,150,217,249 'user.current':107 'usercons':375 'v2':724 'v3':719 'valid':711 'via':430 'vocabulari':309 'webhook':17,143,146,149,153,384 'webhook/oauth':607,696 'work':353 'worker':548 'workflow':251,295 'workgroup':311 'write':95,110,133,436,441,452,463,707 'write/destructive':186 'wrong':597,603,773","prices":[{"id":"c0a592f9-5066-4c88-b659-df719eda02dc","listingId":"bf701d8b-b5fc-4cc0-83e8-5fbb5479a118","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"vrtalex","category":"bitrix24-skill","install_from":"skills.sh"},"createdAt":"2026-04-23T13:03:46.590Z"}],"sources":[{"listingId":"bf701d8b-b5fc-4cc0-83e8-5fbb5479a118","source":"github","sourceId":"vrtalex/bitrix24-skill/bitrix24-agent","sourceUrl":"https://github.com/vrtalex/bitrix24-skill/tree/main/skills/bitrix24-agent","isPrimary":false,"firstSeenAt":"2026-04-23T13:03:46.590Z","lastSeenAt":"2026-04-24T01:03:02.202Z"}],"details":{"listingId":"bf701d8b-b5fc-4cc0-83e8-5fbb5479a118","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"vrtalex","slug":"bitrix24-agent","github":{"repo":"vrtalex/bitrix24-skill","stars":12,"topics":["agent-skill","agent-skills","ai-agents","bitrix24","bitrix24-api","crm","skill","skills","task-manager"],"license":"unlicense","html_url":"https://github.com/vrtalex/bitrix24-skill","pushed_at":"2026-02-15T20:46:17Z","description":"Bitrix24 AI Agent skill: webhook/OAuth, events, retries, safety guardrails, and ops patterns","skill_md_sha":"63f55d1154dfbd8594e323a530b00e5560678ec4","skill_md_path":"skills/bitrix24-agent/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/vrtalex/bitrix24-skill/tree/main/skills/bitrix24-agent"},"layout":"multi","source":"github","category":"bitrix24-skill","frontmatter":{"name":"bitrix24-agent","description":"Design, implement, debug, and harden integrations between AI agents and Bitrix24 REST API (webhooks, OAuth 2.0, scopes, events, batch, limits, and REST 3.0). Use when asked to connect AI assistants/agents to Bitrix24, automate CRM/tasks/chats, process Bitrix24 events, choose an auth model, or resolve Bitrix24 API errors and performance issues."},"skills_sh_url":"https://skills.sh/vrtalex/bitrix24-skill/bitrix24-agent"},"updatedAt":"2026-04-24T01:03:02.202Z"}}