AI-навыки (Skills) - Bitrix24 JS SDK

Обзор

AI-агенты для разработки (Claude Code, Cursor, GitHub Copilot) могут загружать узкоспециализированные skill-файлы из директории skills/ вместо чтения всего репозитория. Каждый skill покрывает одну тему — берите только то, что нужно для текущей задачи.

Доступные skill'ы

Skill	Когда использовать
`b24jssdk-core`	Первый skill для загрузки — выбор точки входа (B24Hook / B24Frame / B24OAuth), запуск/завершение, классификация ошибок, настройка hardErrorCodes / softErrorCodes / retryOnNetworkError
`b24jssdk-rest`	actions.v{2,3}.*.make() — call / batch / callList / fetchList / callTail / fetchTail / batchByChunk; форма AjaxResult; v2/v3-роутинг (без v3-allowlist)
`b24jssdk-filtering`	Фильтры v2 (ключи с префиксом) vs v3 (массивы триплетов); операторы; даты через Text.toB24Format; правило обрезки order в callList
`b24jssdk-frame-ui`	Менеджеры только для iframe: slider / dialog (selectUser/Users/CRM/Access) / parent / placement (с setValue) / options / auth
`b24jssdk-helpers`	useB24Helper, B24HelperManager, Pull-клиент, форматирование валюты, опции приложения/пользователя
`b24jssdk-recipes`	12 готовых end-to-end TypeScript мини-приложений, типизация проверяется в CI через pnpm run skills:typecheck
`b24jssdk-vibecode`	Когда комбинировать SDK с HTTP API VibeCode

Использование

Каждый skill — это обычный Markdown-файл по пути skills/<name>/SKILL.md, следующий открытому стандарту Agent Skills, поэтому его может использовать любой агент, умеющий читать файлы. Есть два пути добраться до skill'ов: загрузить inline для быстрой сессии или установить их в свой проект, чтобы они были всегда доступны.

Загрузка inline (этот репозиторий)

Если ваша рабочая директория — чекаут этого репозитория, ссылайтесь на skill по пути:

@skills/b24jssdk-core/SKILL.md

Ссылайтесь на сам файл SKILL.md, а не на директорию skills/b24jssdk-core — ссылка на директорию лишь перечислит файлы папки, но не подтянет содержимое skill'а. Путь резолвится относительно текущей директории, поэтому это работает только когда рабочая директория — сам b24jssdk. Чтобы использовать skill'ы из своего приложения, установите их одним из способов ниже.

Claude Code — установка в проект

Скопируйте директории skill'ов в .claude/skills/ вашего проекта. Раскладка уже совпадает с ожидаемой Claude Code .claude/skills/<name>/SKILL.md, конвертация не нужна:

mkdir -p .claude/skills
cp -R path/to/b24jssdk/skills/b24jssdk-* .claude/skills/

Закоммитьте .claude/skills/ в систему контроля версий, чтобы поделиться skill'ами со всеми участниками проекта. Claude загружает skill, когда он релевантен, или его можно вызвать напрямую через /b24jssdk-core.

Claude Code — личная установка

Чтобы те же skill'ы были доступны во всех ваших проектах, скопируйте их в личную папку skill'ов:

mkdir -p ~/.claude/skills
cp -R path/to/b24jssdk/skills/b24jssdk-* ~/.claude/skills/

Личные skill'ы (~/.claude/skills/<name>/SKILL.md) доступны в каждом проекте без коммита чего-либо.

Claude Code — плагин / маркетплейс

Пока недоступно. В этом репозитории сейчас нет .claude-plugin/marketplace.json, поэтому /plugin marketplace add bitrix24/b24jssdk сегодня не работает. Пока манифест маркетплейса не вышел, используйте установку в проект или личную выше.

Cursor / Windsurf / GitHub Copilot — сначала вендорьте файлы

У этих инструментов нет папки личных skill'ов, поэтому сначала вендорьте skill-файлы в свой проект, а затем укажите на них инструмент:

# склонируйте весь репозиторий…
git clone https://github.com/bitrix24/b24jssdk

# …или подтяните только skills через sparse checkout
git clone --depth 1 --filter=blob:none --sparse https://github.com/bitrix24/b24jssdk
cd b24jssdk && git sparse-checkout set skills

# …или добавьте как сабмодуль внутрь своего проекта
git submodule add https://github.com/bitrix24/b24jssdk vendor/b24jssdk

Затем ссылайтесь на skills/<name>/SKILL.md: в Cursor / Windsurf перетащите его в чат или используйте @-ссылки на файлы (или @docs); в GitHub Copilot прикрепите как workspace-документ или вставьте путь в чат.

Загрузка с опубликованного URL (без клонирования)

Директория skills/ также отдаётся с docs-сайта по пути /.well-known/skills/, поэтому skill можно получить, не клонируя репозиторий:

curl -O https://bitrix24.github.io/b24jssdk/.well-known/skills/b24jssdk-core/SKILL.md

Каждый skill — по пути /.well-known/skills/b24jssdk-<name>/SKILL.md. Ответы кэшируются на 24 часа. Удобно для быстрого вендоринга (положить файл в .claude/skills/<name>/ или прикрепить в другом инструменте) или для тулинга, обнаруживающего skill'ы по HTTP.

Порядок загрузки

Всегда начинайте с b24jssdk-core — он покрывает выбор точки входа и жизненный цикл SDK, что предполагают все остальные skill'ы. Затем добавляйте темо-специфичные skill'ы в зависимости от задачи:

b24jssdk-core (всегда первый)
b24jssdk-rest — если делаете REST-вызовы
b24jssdk-filtering — если строите фильтры или list-запросы
b24jssdk-frame-ui — если работаете внутри iframe-приложения
b24jssdk-helpers — если используете helper-утилиты или Pull
b24jssdk-recipes — для готовых end-to-end примеров

Не загружайте все skill'ы сразу — описания спроектированы для выборочного использования, чтобы контекст оставался сфокусированным.

Дополнительно

См. AGENTS.md — полная документация для контрибьюторов и агентов, включая команды, тестирование и ключевые конвенции.

v2 → v3

Как уйти с устаревшей REST-поверхности, которая удаляется в Bitrix24 JS SDK 3.0.0.

LLMs.txt

Как сделать, чтобы AI-инструменты вроде Cursor, Windsurf, GitHub Copilot, ChatGPT и Claude понимали методы, инструменты и лучшие практики Bitrix24 JS SDK.