# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17
# Ресурсы: [таблица навыков,kill_sources.json]

СИСТЕМА НАВЫКОВ BACH (Архитектура v2.0)
-------------------------------------

По состоянию на 08 февраля 2026 г.

Навыки — это специализированные навыки, расширяющие возможности LLM.
Они организованы по модульному принципу на уровне 3 (логика и навыки).

ПРИНЦИП ПРОВЕРКИ ВЕРСИЙ (НОВЫЙ)
----------------------------
ВСЕГДА используйте последнюю версию - локальную или центральную:

  bach --skills version <name>  # Проверьте версии
  bach --tools version <name>   # Проверьте версии инструмента

СТРУКТУРА НАВЫКОВ: ОДИН НАВЫК = ОДНА ПАПКА (НОВАЯ)
--------------------------------------------
Каждый навык, агент, эксперт полностью самодостаточны в своей собственной папке:

  ПЛОСКИЙ (стандартный, < 5 файлов):
  ----------------------------
  агенты/разработчики/
  +-- SKILL.md # Определение со стандартным заголовком
  +--tool_xyz.py # Конкретный инструмент (непосредственно в корне)
  +-- workflow_abc.md # Конкретный рабочий процесс (непосредственно в корне)
  +-- config.json # Необязательно

  КОМПЛЕКС (>= 5 файлов):
  ----------------------
  агенты/_эксперты/налоги/
  +-- SKILL.md
  +-- инструменты/ # Подпапки для многих инструментов
  +-- рабочие процессы/ # Подпапки для многих рабочих процессов
  +-- данные/ # Конкретные данные

ИЕРАРХИЯ И КАТЕГОРИИ
-----------------------
навыки/
+-- _agents/агенты (оркестрация, собственная папка)
+-- _experts/ Эксперты (знания предметной области, собственная папка)
+-- _services/ Services (обработчик-рядом, собственная папка)
+-- _connectors/Адаптеры (Telegram, Discord, HA, собственная папка)
+-- партнеры/интеграции партнеров (собственная папка)
+-- _os/ Навыки, специфичные для ОС (собственная папка)
+-- _workflows/ Рабочие процессы (НЕТ папки, 1 файл = 1 рабочий процесс)
+-- _templates/ Стандартные шаблоны (ШАБЛОН_*.md)

ТИПЫ КОМПОНЕНТОВ
-----------------

  Тип характеристики папки
  -------- ----------------- ---------------------------------
  Агент _agents/<имя>/ Управляет экспертами, собственная папка
  Эксперт _experts/<имя>/ Глубокие знания предметной области, собственная папка
  Сервис _services/<имя>/Общий, связанный с обработчиком, собственная папка
  Коннектор _connectors/<имя>/Адаптер для внешних сервисов
  Партнеры-партнеры/<имя>/ Интеграции партнеров (объединенные)
  Навык ОС _os/<имя>/ Функциональность, специфичная для ОС
  Рабочий процесс _workflows/ папка НЕТ (1 файл = 1 рабочий процесс)
  Инструментальная (общая) система/инструменты/ Многоразовые, не связанные с навыками
  Инструмент (конкретный) В папке навыков Только для этого навыка

ДУБЛИКАЦИЯ ИНСТРУМЕНТА
-----------------
ПРАВИЛО: Если сомневаетесь, оставляйте его вдвое!

  system/tools/c_ocr_engine.py # Общая версия
  агенты/_experts/steuer/steuer_ocr.py # Версия для конкретных навыков

Преимущества:
- Можно разработать самостоятельно
- Навыки остаются самодостаточными
- Отсутствие конфликтов зависимостей

ВАЖНО: инструменты/ расположены в папке system/tools/ (НЕ в разделе навыки/инструменты/)

CONNECTORS (НОВОЕ 2026-02)
------------------------
_connectors/ содержит адаптеры для внешних сервисов:
- telegram_connector.py - интеграция Telegram Bot API
- discord_connector.py - интеграция бота Discord
- homeassistant_connector.py - интеграция Home Assistant
— base.py — базовый класс соединителя
- SKILL.md - Документация по коннекторам

Коннекторы — это специализированные сервисы, соединяющие внешние платформы.
В основном они используют асинхронную связь и очереди событий.

СТАНДАРТНЫЙ ЗАГОЛОВОК (обязательный)
-------------------------
Каждому компоненту необходим заголовок YAML-Frontmatter:

  ---
  имя: [имя]
  версия: XYZ
  тип: умение | агент | эксперт | сервис | разъем | партнеры | ОС | рабочий процесс
  автор: [автор]
  создано: ГГГГ-ММ-ДД
  обновлено: ГГГГ-ММ-ДД
  антропный_совместимый: правда
  зависимости:
    инструменты: []
    услуги: []
    рабочие процессы: []
  описание: >
    [Описание]
  ---

Шаблоны: навыки/_templates/TEMPLATE_*.md

ЭКСПОРТНАЯ СИСТЕМА
-------------
Экспортируемые навыки должны работать БЕЗ BACH:

  bach --skills export <name>  # Создает самодостаточный пакет

Экспорт содержит:
- SKILL.md с заголовком
- манифест.json (зависимости, версии)
- Все специальные инструменты
- Все специфические рабочие процессы
- README.md (автономное руководство)
- Все необходимые общие ресурсы Баха

 ИСТОЧНИКИ НАВЫКОВ И БЕЗОПАСНОСТЬ
--------------------------

  Подход к источникам классов
  ---------- ---------------------------------- ----------------------
  Золотой стандарт Самостоятельная разработка Лучшая интеграция
  Доверенные антропология/навыки, кулинарные книги После тестирования 1:1 ОК
  Ненадежные Перезапись ТОЛЬКО других репозиториев GitHub
  Черный список данных/skill_blacklist.json ЗАПРЕЩЕНО

Проверьте: data/skill_sources.json

СИНХРОНИЗАЦИЯ БД
------------------
Все навыки синхронизируются двунаправленно между файловой системой и БД:
- Таблица: навыки (на данный момент 876 записей)
- Поля: имя, тип, путь, content_hash, is_active, версия.
- Расширенные поля: категория, приоритет, триггерные фразы, dist_type, template_content, контент.
- Статистика: bach --skills list

КОМАНДЫ CLI
-----------
  bach skills list               Перечислить все навыки
  bach skills show <name>        Содержимое и метаданные
  bach skills search <term>      Поиск функциональности
  bach skills version <name>     Проверка версий (локальная или центральная)
  bach skills export <name>      Создать самодостаточный пакет (v2.0)
  bach skills install <path>     Импортировать навык из ZIP/каталога
  bach skills export-agent <n>   Экспортировать навык как Claude Code Agent
  bach skills hierarchy          Показать иерархию из БД
  bach skills hierarchy <typ>    Показать только тип (агент/эксперт/навык/сервис/рабочий процесс)

САМОРАСШИРЕНИЕ (НОВАЯ версия 2.5)
-----------------------------
  bach skills create <name> --type <typ>   Новая возможность Scaffold
  bach skills reload                        Горячая перезагрузка без перезагрузки

  Поддерживаемые типы для «создания»:

    --type инструмент Создан: system/tools/<имя>.py
                       Скрипт Python со стандартным шаблоном
                       Можно использовать сразу после внедрения

    --type агент Создан: system/agents/<имя>/SKILL.md
                       Собственная папка, управляет другими компонентами.
                       Шаблон со стандартным заголовком

    --type expert Создано: system/agents/_experts/<имя>/SKILL.md
                       Своя папка, глубокие знания предметной области
                       Шаблон со стандартным заголовком

    --type обработчик Создано: system/hub/<имя>.py
                       Доступно сразу же как команда CLI!
                       Подкласс BaseHandler с get_operations()
                       Доступно через bach <name> после «перезагрузки»

    --type Созданная служба: system/skills/_services/<имя>/
                       Папка с __init__.py и service.py
                       Закрытие обработчика, обычно можно использовать

  Рабочий процесс:
    1. Навыки Баха создают обработчик my-tool --type
    2. отредактируйте Hub/my_tool.py (реализуйте логику)
    3. Перезарядка навыков Баха
    4. Справка по bach mein-tool (доступна немедленно!)

  Хуки после создания/перезагрузки:
    after_skill_create → генерируется после каждого создания
    after_skill_reload → генерируется после каждой «перезагрузки»

GUI (доска навыков)
------------------
Интерактивная доска навыков показывает всю иерархию,
статус синхронизации и позволяет прямое редактирование.

  http://127.0.0.1:8000/skills

СМОТРИТЕ ТАКЖЕ
----------
  bach help agents             Обзор агента
  bach help tools              Управление инструментами
  bach help workflow           Система рабочих процессов
  bach help naming             Соглашения об именах
  bach help hooks              Hook Framework (14 событий)
  bach help self-extension     Система саморасширения
  SKILL.md Центральное определение навыков
  data/skill_sources.json Источники и версии навыков
