Полная документация ниже — автоматически из репозитория poliklot/bitrix-agent-skill (ветка master). Оригинальные материалы проекта распространяются на условиях его лицензии.

Bitrix Agent Skill

Эксперт по 1C-Bitrix для Claude Code и Codex с принципом «сначала ядро».
Навык содержит проверенную базу знаний по ядру Bitrix и правила работы с проектом: если агенту доступна рабочая копия проекта, он должен сверять ответ с `www/bitrix`, стандартными компонентами, шаблонами и `local/*`-оверрайдами.

Последний релиз
· Установка
· Что покрывает
· Лицензия MIT
· Папка для MCP Market

Оглавление

• Зачем это нужно
• Что значит «сначала ядро»
• Аудит проекта и файл контекста
• Установка
  • macOS / Linux
  • Windows PowerShell
  • MCP Market
• Что покрывает
• Статус runtime-проверок
• Примеры запросов
• Как устроено
• Правила безопасности
• Обновление и сопровождение
• Требования
• Обратная связь
• Лицензия

Зачем это нужно

Bitrix-проекты нельзя нормально вести “по памяти”. В каждом проекте отличаются состав модулей, скопированные шаблоны компонентов, wizard-ассеты, старые пути записи, настройки и local/*-оверрайды.

Этот навык помогает агенту работать как опытный Bitrix-разработчик:

• не применять справочник вслепую к проекту с другим набором модулей;
• при доступе к файлам проекта проверять наличие модулей, version.php, стандартные компоненты и шаблоны;
• читать стандартные компоненты и шаблоны перед тем, как советовать правку;
• разделять D7, старый C* API и пути записи с важными побочными эффектами;
• считать catalog, sale, currency, bizproc, pull, 1С и магазинные интеграции условными, пока они не подтверждены в конкретном проекте;
• не путать аудит по коду ядра с проверкой в живом окружении.

Что значит «сначала ядро»

Навык не сканирует Bitrix сам по себе. Это набор инструкций и справочных файлов для агента. Поведение зависит от контекста:

Версии в справочниках нужны не для магического выбора поведения по всем релизам Bitrix. Они фиксируют, по какому ядру проверен конкретный контракт: например, shop-core содержит catalog 25.550.0, sale 26.0.0, currency 26.0.0. Если в клиентском проекте версия другая, агент должен не угадывать совместимость, а читать локальные файлы модуля.

Аудит проекта и файл контекста

Для реального проекта навык должен работать не только как справочник, но и как память по уже изученному коду.

[!NOTE]
Чтобы запустить первичный аудит, откройте агент в корне Bitrix-проекта и отправьте команду:

/bitrix Сделай аудит проекта и обнови BITRIX_PROJECT_CONTEXT.md

Это не shell-команда, а запрос агенту. Лучше запускать его из корня клиентского репозитория, где доступны www/bitrix, local/, bitrix/templates, urlrewrite.php и проектные конфиги.

После полного аудита проекта агент должен создать или обновить в корне клиентского репозитория файл:

BITRIX_PROJECT_CONTEXT.md

Этот файл хранит безопасный снимок проекта: public root, состав модулей и версии, шаблоны, компоненты, local/*, события, агенты, tooling, shop/1С endpoints, REST/webservice, component/tagged/composite cache, SEO/routing, риски и открытые вопросы. Следующий агент сначала читает AGENTS.md, затем BITRIX_PROJECT_CONTEXT.md, а потом сверяет рискованные факты с текущим кодом.

Шаблон лежит в bitrix/assets/BITRIX_PROJECT_CONTEXT.template.md. В файл нельзя записывать secrets, cookies, tokens, пароли, license keys, production XML/дампы, персональные данные и приватные payloads.

Установка

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.ps1 | iex

Если навык не появился сразу, один раз перезапустите Claude Code или Codex.

В Bitrix-проекте вызывайте:

/bitrix почему товар есть в админке, но не виден на сайте?

MCP Market

В MCP Market есть лимит 50 файлов на импортируемую папку. Используйте компактную версию только для чтения:

https://github.com/Poliklot/bitrix-agent-skill/tree/master/mcpmarket/bitrix

Полная папка bitrix/ содержит скрипты установки/обновления/удаления и 80+ отдельных справочных файлов. Версия mcpmarket/bitrix/ содержит тот же справочный слой, но сгруппированный в компактные пакеты.

curl -fsSL https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.sh | bash -s -- --claude
curl -fsSL https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.sh | bash -s -- --codex
curl -fsSL https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.sh | bash -s -- --both

curl -fsSL https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.sh | bash -s -- --version 1.48.0 --claude

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.ps1))) -Claude
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.ps1))) -Codex
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.ps1))) -Both
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poliklot/bitrix-agent-skill/master/install.ps1))) -Version 1.48.0 -Claude

Что покрывает

Магазинный маршрут включается в каждом проекте отдельно — только после проверки нужных модулей в www/bitrix/modules, если рабочая копия доступна агенту. Отдельная база shop-core описывает 49 модулей, но это не отменяет локальную проверку клиентского проекта.

Статус runtime-проверок

Справочный слой даёт code-first покрытие: агент знает, какие файлы ядра читать и какие маршруты применять. Это не равно runtime pass в конкретном проекте.

Для живой проверки используются smoke-пакеты P1–P4 из bitrix/references/runtime-smoke-verification.md: каталог/SKU/корзина/заказ, CommerceML, REST/webservice, marketing/automation/realtime. Evidence оформляется по шаблонам из bitrix/assets/runtime-smoke/:

python3 scripts/bitrix_runtime_preflight.py --public-root www --base-url http://localhost
python3 scripts/init_runtime_evidence.py --package P1 --output evidence/YYYY-MM-DD-p1-shop-path
python3 scripts/init_runtime_evidence.py --all --output evidence/YYYY-MM-DD-runtime-smoke-all
python3 scripts/validate_runtime_evidence.py evidence/YYYY-MM-DD-p1-shop-path --package P1

Короткие команды для сопровождения репозитория:

make validate
make evidence-p1
make evidence-all
make preflight PUBLIC_ROOT=www BASE_URL=http://localhost
make release-check
make optimization-audit PROJECT_ROOT=/path/to/bitrix-project OPTIMIZATION_AUDIT_OUTPUT=/tmp/bitrix-optimization-audit.md
make optimization-evidence OPTIMIZATION_EVIDENCE_DIR=evidence/YYYY-MM-DD-optimization-audit
make validate-optimization-evidence OPTIMIZATION_EVIDENCE_DIR=evidence/YYYY-MM-DD-optimization-audit

Пример честного blocked без runtime pass лежит в examples/runtime-smoke/blocked-p1/.

Если безопасного sandbox, fixtures или stub-интеграций нет, сценарий отмечается как blocked, а не как “проверено”.

Примеры запросов

/bitrix Проверь по core, почему вторая страница каталога пустая после фильтра
/bitrix Разбери, почему 1С выгрузила товар, но на сайте нет цены и остатка
/bitrix Найди слой стандартного шаблона для form и объясни intranet-вариант
/bitrix Проверь, куда в этом проекте положить общий редактируемый блок и не сломать composite
/bitrix Разбери, как здесь хранить IBLOCK_ID между dev/stage/prod без magic numbers
/bitrix Сформируй безопасный для продакшена план доработки оформление заказа и перечисли грабли
/bitrix Проверь, можно ли в этом проекте идти в sale/catalog, или магазинный маршрут пока отложен
/bitrix Почему REST событие заказа не прилетело во внешний вебхук?

Как устроено

Навык использует постепенную загрузку контекста:

bitrix-agent-skill/
├── bitrix/SKILL.md              # точка входа, маршрутизация, правила безопасности
├── bitrix/references/*.md       # 80+ узких справочников, загружаются только по необходимости
├── bitrix/assets/               # шаблоны для артефактов агента, включая BITRIX_PROJECT_CONTEXT.md
├── mcpmarket/bitrix/            # компактная версия для MCP Market, только для чтения
├── scripts/                     # локальные validation/evidence/preflight helpers
├── examples/runtime-smoke/      # безопасные примеры evidence pack
├── Makefile                     # короткие команды validate/evidence/release-check
├── install.sh / install.ps1     # установщики для Claude Code и Codex
└── CHANGELOG.md / PLAN.md       # история релизов и план аудита

Агент начинает с bitrix/SKILL.md, определяет домен задачи и загружает только нужные справочные файлы. Он не должен тащить всю Bitrix-базу знаний в контекст на каждый запрос.

Правила безопасности

Навык намеренно консервативный:

• не выдумывает API, события, классы и параметры компонентов;
• не включает магазинный маршрут без локального подтверждения catalog / sale / currency;
• не правит прямым SQL заказы, корзины, оплаты, отгрузки, цены и остатки, если важны побочные эффекты API;
• не использует продакшен-1С, реальные платежи, доставку, кассы, SMS или клиентские данные для проверки без явного подтверждения;
• не заявляет, что проверка в живом окружении пройдена, без песочницы, тестовых данных и зафиксированных доказательств.

Обновление и сопровождение

Установленный навык умеет проверять GitHub-релизы и обновляться.

bash ~/.claude/skills/bitrix/update.sh --check
bash ~/.claude/skills/bitrix/update.sh

bash "${CODEX_HOME:-$HOME/.codex}/skills/bitrix/update.sh" --check
bash "${CODEX_HOME:-$HOME/.codex}/skills/bitrix/update.sh"

powershell -ExecutionPolicy Bypass -File "$HOME\.claude\skills\bitrix\update.ps1" -Check
powershell -ExecutionPolicy Bypass -File "$HOME\.claude\skills\bitrix\update.ps1"

$CodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
powershell -ExecutionPolicy Bypass -File (Join-Path (Join-Path $CodexHome 'skills') 'bitrix\update.ps1') -Check
powershell -ExecutionPolicy Bypass -File (Join-Path (Join-Path $CodexHome 'skills') 'bitrix\update.ps1')

При первом содержательном запросе /bitrix навык должен молча выполнить --check. Если есть новая версия, он должен сказать строго так:

Обновилась версия скилла с X до Y. Давай обновим?

bash ~/.claude/skills/bitrix/versions.sh
bash "${CODEX_HOME:-$HOME/.codex}/skills/bitrix/versions.sh"

bash ~/.claude/skills/bitrix/uninstall.sh
bash "${CODEX_HOME:-$HOME/.codex}/skills/bitrix/uninstall.sh"

powershell -ExecutionPolicy Bypass -File "$HOME\.claude\skills\bitrix\versions.ps1"
powershell -ExecutionPolicy Bypass -File "$HOME\.claude\skills\bitrix\uninstall.ps1"

$CodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
powershell -ExecutionPolicy Bypass -File (Join-Path (Join-Path $CodexHome 'skills') 'bitrix\versions.ps1')
powershell -ExecutionPolicy Bypass -File (Join-Path (Join-Path $CodexHome 'skills') 'bitrix\uninstall.ps1')

Требования

• Claude Code или Codex
• проект на 1C-Bitrix CMS или коробочном ядре Bitrix24

Обратная связь

Issues и PR приветствуются, особенно если вы приносите новый кейс из реального Bitrix-проекта, проверенный по ядру.

Если навык сэкономил вам время, поставьте звезду репозиторию — это самый понятный сигнал, что Bitrix заслуживает нормального инструмента для агентов.

Лицензия

MIT. Подробности в LICENSE.

Надёжность диагностических отчётов

make test выполняет поведенческую регрессию, а make validate включает её перед публикацией. Диагностические helpers запускаются из checkout этого репозитория, не из установленной папки навыка.

Preflight — только файловое обследование (candidate/blocked, не runtime pass). Отчёты не копируют исходный код и приватные части URL. Evidence-валидаторы проверяют локальные ссылки, согласованность ID/вердиктов и явные утечки; они не заменяют выполнение сценария и ручную проверку приватности. Полный контракт и изменения совместимости, аудит 10 пробелов.