---
name: bslfmt
description: >-
  Форматирование локального BSL-файла или полного текста отдельной процедуры/функции
  утилитой bslfmt по просьбе пользователя. Использовать при правке и форматировании
  BSL; показывать diff и сохранять комментарии, если их удаление не запрошено явно.
---

# Форматирование BSL через bslfmt

Версия skill: `0.2.0`. Последний релиз утилиты: `bslfmt 0.24.0`.
MCP не требуется.

## Когда применять

Используй локальную утилиту, если пользователь просит отформатировать BSL-файл
или полный текст отдельной процедуры/функции, в том числе после правки кода.
Вход — локальный путь либо доступный агенту текст. Результат — изменённый файл
в разрешённой области либо форматированный текст, если запись не запрошена.

Не используй skill как доказательство компиляции, корректности API или поведения
кода. Не запрашивай целый модуль у удалённого MCP-сервера только ради
форматирования и не передавай ему локальный путь или исходный текст. Если нет
локального файла или текста, сообщи, какой вход отсутствует.

## Подготовка утилиты

Утилите нужен Python 3.10+. Проверь установленную версию: `bslfmt --version`.
На 2026-10-01 последний [релиз GitHub](https://github.com/AzeevAN/bslfmt/releases/tag/v0.24.0)
— `0.24.0`; [PyPI](https://pypi.org/project/bslfmt/) предлагает `0.23.0`.
Для последнего релиза устанавливай конкретный тег GitHub:

```bash
uv tool install --from 'git+https://github.com/AzeevAN/bslfmt@v0.24.0' bslfmt
bslfmt --version
```

Для обновления уже установленного инструмента повтори команду с `--force`:

```bash
uv tool install --force --from 'git+https://github.com/AzeevAN/bslfmt@v0.24.0' bslfmt
```

Разовый запуск без постоянной установки:

```bash
uvx --from 'git+https://github.com/AzeevAN/bslfmt@v0.24.0' bslfmt --version
```

Альтернатива — `pipx install 'git+https://github.com/AzeevAN/bslfmt.git@v0.24.0'`
(при переустановке добавь `--force`). Установка из Git требует доступного `git`.
Для версии из PyPI доступны `uv tool install bslfmt`, `uv tool upgrade bslfmt`
и `pipx install bslfmt` / `pipx upgrade bslfmt`: они используют последний
опубликованный пакет этого индекса.

В `0.24.0` добавлен перенос длинных инструкций при ширине 120 символов и
изменены отступы строк продолжения. Поэтому перед применением обновлённого
форматтера просмотри diff: результат может отличаться от прежних версий.

Загрузка и установка выполняются средствами локального агента в пределах
разрешений пользователя. Если утилита недоступна и установить её нельзя,
остановись со статусом `blocked`; не выдавай ручное форматирование за результат
`bslfmt`.

## Файл целиком

Для файла, который пользователь разрешил менять:

```bash
bslfmt --check --diff Module.bsl
bslfmt -i Module.bsl
bslfmt --check Module.bsl
```

Если используешь разовый запуск, замени `bslfmt` на
`uvx --from 'git+https://github.com/AzeevAN/bslfmt@v0.24.0' bslfmt` во всех командах.
Первый `--check` не меняет файл: код выхода `0` означает, что изменений нет,
`1` — форматирование требуется. Коды `2` и `3` означают отказ или внутреннюю
ошибку; не продолжай запись после них. При `0` пропусти `-i`. Просмотри diff
до записи и итоговый diff после неё. Если пользователь просил только показать
изменения, достаточно `--check --diff` без записи. Полный форматированный файл
в stdout через `bslfmt Module.bsl` выводи лишь когда нужен именно его текст.

## Отдельная процедура или функция

Передай в `stdin` **полный** текст метода: от объявления `Процедура` или
`Функция` до соответствующего `КонецПроцедуры` или `КонецФункции`. Команда
`bslfmt -` выводит форматированный текст в stdout. Не форматируй таким способом
произвольный обрывок тела метода.

Если нужно вставить результат обратно, замени только исходный блок метода в
разрешённом файле и проверь итоговый diff. Не применяй `-i` к `stdin` и не
форматируй весь файл, когда пользователь ограничил изменение одним методом.

## Комментарии и проверка результата

Обычное форматирование сохраняет комментарии. Флаг `-sbc` удаляет отдельные
строки комментариев внутри процедур и функций, поэтому добавляй его **только
при явной просьбе пользователя удалить такие комментарии**. Просьба
«отформатируй» такого разрешения не даёт. Перед применением `-sbc` покажи diff
через `bslfmt -sbc --check --diff Module.bsl` и убедись, что затронут нужный
файл или метод. Для отдельного метода используй `bslfmt -sbc -` и просмотри
результат до вставки.

После записи проверь область изменений, сохранность не подлежащих удалению
комментариев и результат `--check`. Сообщи, что отформатировано, какие файлы
изменены, и отдели проверенное от `not_checked` и `unknown`. Ошибку утилиты или
неоднозначную границу метода обозначь `blocked` и сохрани исходный текст.

## Подключение skill

Для Codex установи весь каталог `skills/bslfmt/` в
`$CODEX_HOME/skills/bslfmt/` (при стандартном расположении —
`~/.codex/skills/bslfmt/`). В другом клиенте используй его механизм установки
skills. При обновлении замени каталог целиком; для удаления удали установленный
каталог. Сам skill не устанавливает `bslfmt` и не добавляет MCP-инструментов.

Команды и поведение утилиты: [README релиза 0.24.0](https://github.com/AzeevAN/bslfmt/blob/v0.24.0/README.md).
Установка из Git: [документация uv](https://docs.astral.sh/uv/guides/tools/).