GitX — переносимый скилл для чистых Git-коммитов в AI-агентах

AI-агенты быстро пишут код, но редко следят за историей Git. За одну сессию они трогают десятки файлов: новая фича смешивается со случайным рефакторингом, правкой зависимостей и подчищенными логами. Одна команда «закоммить всё» — и в истории появляется гигантский коммит, который невозможно нормально прочитать или откатить. GitX — это скилл формата SKILL.md, который встраивается в AI-агента и наводит здесь порядок: группирует правки в логичные Conventional Commits, создаёт ветки с осмысленными префиксами, безопасно обновляет ветку и отправляет изменения, открывает pull request'ы с готовым описанием и ищет секреты до того, как они попадут в историю.

Скилл переносимый: он работает в Claude Code, OpenAI Codex, Cursor и любых других агентах с поддержкой Agent Skills. Настройки одни и те же, поведение — тоже.

Установка

npx skills add musoyangrigor/gitx-skill --skill gitx

Skills CLI сам настраивает скилл для выбранного агента. После установки нужно начать новую сессию агента.

Дальше всё просто: команда $gitx без аргументов не показывает справку и не задаёт вопросов. Она сразу осматривает репозиторий и делает умный коммит. Список команд появляется только по явной просьбе о помощи.

Как устроен умный коммит

Основной сценарий GitX — команда $gitx. Работает она так:

1. Агент читает git status и все диффы: и то, что уже добавлено в индекс (staged), и то, что ещё не добавлено.
2. Группирует правки по смыслу. Умеет делить даже один файл между несколькими коммитами: например, если в нём и новая функция, и правка старой, они попадут в разные группы.
3. Если нашлась одна логическая группа — создаёт один аккуратный Conventional Commit.
4. Если групп несколько — показывает каждое предполагаемое сообщение и спрашивает: «Сделать N коммитов или один?» N здесь — реальное число групп, а не заглушка.
5. Не отправляет изменения сам. Push происходит только по явной команде $gitx push или прямой просьбе.

Название коммита собирается по правилам Conventional Commits: тип вроде fix или feat, при возможности — scope из словаря проекта. Если подходящий scope не придумывается, агент его не выдумывает, а оставляет коммит без scope.

Команды

Проверки агент находит сам: npm test, pnpm test, pytest, cargo test, go test ./..., make test — либо берёт список из конфигурации. При обычном коммите провалившаяся проверка не блокирует работу: агент спросит, коммитить ли всё равно. А вот $gitx ship строже — при падении проверок он останавливается.

Ветки и pull request'ы

$gitx branch подбирает префикс по смыслу работы: feat/ для новых функций, fix/ для багов, docs/ для документации, refactor/ для перестройки кода. Префикс hotfix/ по умолчанию не ставится никогда — только для срочных исправлений в проде и только по явной команде. Если ветка уже существует, агент не молча перезапишет её, а спросит, что делать.

$gitx pr открывает pull request в базовую ветку — указанную, настроенную или дефолтную в origin. Заголовок и описание агент генерирует сам.

$gitx ship — самый полный сценарий. Он создаёт ветку, если её нет, прогоняет проверки, коммитит, отправляет изменения и открывает pull request. Важно: merge этот PR не делает. Форс-пуш тоже.

Задачи из GitHub

Команда $gitx issue работает в двух режимах, и различает их GitX по форме аргумента, а не по смыслу текста. Число — значит «внедрить существующую issue»: агент прочитает её и начнёт делать исправление. Любой другой текст — значит «создать новую issue» в GitHub, даже если в описании есть слова «fix» или «update».

Ещё одна деталь: issues всегда создаются в GitHub, даже если в проекте есть локальный трекер. Если создание не удалось, агент сообщит об ошибке, а не подменит результат локальным файлом.

Настройки проекта

Команда $gitx setup осматривает конвенции репозитория, показывает предполагаемый конфиг и сохраняет его в .gitx.json в корне. Коммитить файл агент не станет — это решаете вы, если хотите поделиться настройками с командой.

{
  "prBase": "dev",
  "branchPrefix": ["feat/", "fix/", "chore/", "docs/", "refactor/", "test/"],
  "commitScopes": ["auth", "api", "ui", "docs"],
  "checks": ["npm run lint", "npm test"],
  "draftPR": false
}

Все поля необязательные. prBase задаёт базовую ветку для $gitx pr и $gitx ship, branchPrefix — словарь префиксов для новых веток, commitScopes — словарь scope'ов для коммитов, checks — команды проверок в порядке выполнения, draftPR — создавать ли pull request черновиком.

Порядок приоритетов такой: явная просьба в команде важнее сохранённых настроек, настройки важнее значений по умолчанию. Без .gitx.json скилл работает как раньше.

Безопасность и «только чтение»

GitX предупреждает, прежде чем включить в коммит что-то рискованное: .env, *.pem, *.key, файлы с token, secret или api_key в имени, логи, каталоги dist/, build/ и node_modules/.

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

• $gitx plan — покажет группы коммитов и сообщения, не трогая ни файлы, ни индекс.
• $gitx status — краткая сводка по изменённым файлам.
• $gitx tree — история, ветки, отставание от upstream и текущий pull request.
• $gitx scan — ищет секреты в изменениях и истории и выдаёт оценку утечки, ничего не исправляя.
• $gitx doctor — ставит диагноз проблемам Git и подсказывает наименьший разумный следующий шаг, но сам ничего не ремонтирует.

Команда $gitx resolve помогает с конфликтами при merge и rebase. Агент прослеживает обе стороны конфликта до исходных коммитов, понимает замысел каждого изменения и сохраняет оба намерения, где это возможно. Если намерения противоречат, выбирается то, что лучше отвечает цели слияния, — с явной пометкой о компромиссе. После разрешения прогоняются проверки, форс-пуш не делается.

Даже $gitx amend спрашивает подтверждение и показывает новое сообщение. Если дополненный коммит уже запушен, агент предупредит, что обычный push будет отклонён, и спросит, как поступить.

Где подробности

Детальное поведение каждого сценария описано в справочниках репозитория: настройки проекта и JSON Schema для типов полей, pull request'ы, GitHub issues, поиск секретов, сценарий ship, диагностика и разделение правок внутри одного файла.

Проект распространяется по лицензии MIT. Тесты написаны на Python и запускаются через python3 -m unittest discover -s tests -v.