skills-i18n-sync

---
name: skills-i18n-sync
description: >
  Управление синхронизацией русскоязычных навыков (framework/) с
  англоязычным зеркалом (framework_eng/). Используй когда нужно
  проверить статус синхронизации, вручную запустить перевод,
  или понять почему заблокирован коммит.
---

# skills-i18n-sync — синхронизация RU→EN навыков

`framework/` (RU, источник правды) → `framework_eng/` (EN, автоматическое зеркало). Симлинки IDE указывают на `framework_eng/`. **Никогда не редактируй `framework_eng/` напрямую.**

---

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

| Триггер | Действие |
|---------|----------|
| Ты изменил любой файл в `framework/` (кроме `README.md`) | Немедленно синхронизировать изменённый файл через `/sync-skills <path>` |
| Видишь статус `dirty` или `pending` в реестре | Запустить `/sync-skills` перед использованием навыка |
| Коммит заблокирован хуком с ошибкой перевода | Запустить `python3 tools/sync-skill.py --all`, затем повторить коммит |
| Добавлен новый файл в `framework/` | Запустить `/sync-skills <path>` для создания EN-версии |
| Нужно проверить состояние всех навыков | Запустить `/sync-skills check` |

---

## Команды

### `/sync-skills check`
Показывает таблицу статусов всех файлов:
- `✓ synced` — RU и EN синхронизированы
- `○ pending` — EN-версия ещё не создавалась
- `✗ dirty` — RU изменён, EN устарел
- `! error` — последний перевод завершился ошибкой

```bash
python3 tools/sync-skill.py --check
```

### `/sync-skills`
Синхронизировать все `pending` и `dirty` файлы:

```bash
python3 tools/sync-skill.py --all
```

### `/sync-skills <path>`
Синхронизировать конкретный файл:

```bash
python3 tools/sync-skill.py framework/skills/bsl-practices/coding-standards/SKILL.md
```

### `/sync-skills init-all`
Первичная синхронизация — перевести всё что ещё не имеет EN-зеркала.
Запускается один раз при инициализации или после добавления большого блока файлов:

```bash
python3 tools/sync-skill.py --init-all
```

---

## Правила для агентов

1. **После любого изменения файла в `framework/`** — сразу запускай синхронизацию.
   Не откладывай до коммита: хук заблокирует его если EN отсутствует.

2. **Исключение:** `README.md` файлы не переводятся и не синхронизируются.

3. **Перед использованием навыка** — проверь что его статус `synced`.
   Если `dirty` — данные в `.claude/skills/` устаревшие.

4. **`framework_eng/` только читай**, никогда не пиши напрямую.

5. **При конфликте содержимого** RU и EN — RU всегда победитель (источник правды).

---

## Как работает pre-commit хук

```
git commit
    ↓
.git/hooks/pre-commit запускается
    ↓
Находит staged файлы в framework/ (кроме README.md)
    ↓
Вызывает: python3 tools/sync-skill.py <список файлов>
    ↓
sync-skill.py вызывает Codex CLI (gpt-5.1-codex-mini) для перевода каждого файла
    ↓
Записывает результат в framework_eng/ (зеркальный путь)
Обновляет .skills-sync-state.json
    ↓
Хук добавляет framework_eng/ файлы и state в коммит (git add)
    ↓
Коммит продолжается (RU + EN всегда в одном коммите)
    ↓
При ошибке: БЛОКИРОВКА коммита с инструкцией по исправлению
```

---

## Реестр синхронизации

Файл `.skills-sync-state.json` в корне репо — статусы и хэши каждого файла.

---

## Установка хука на новой машине

```bash
cp tools/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

---
depends_on: []
---