skills-rag — RAG по базе скиллов

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

Любой вопрос «какой скилл это умеет / что делает скилл X / где в скиллах про Y / есть ли у нас инструмент для Z». Спрашивать индекс — ДО чтения SKILL.md и до грепа по репозиториям.

Правила (must follow)

1. Сначала RAG, потом текст. Первый шаг — запрос к индексу, а не Grep и не Read по корпуса контуров. Слепой поиск — только фолбэк, когда индекс недоступен, и об этом надо честно сказать в ответе.
2. Ответ RAG — наводка, не истина. Итог строй по реальному содержимому файлов из блока «ИСТОЧНИКИ»: прочитай процитированные места и отвечай по ним. Модель галлюцинирует и на свежем индексе.
3. Контур выбирается по вопросу, а не наугад: team — корп-знания (корп-проекте, SAP, Kafka, SQL Server, GitLab организации); shared — универсальное (git, cleaner, youtube, скиллы про скиллы); personal — личное. Не знаешь — спроси индекс shared, затем team.
4. Индекс должен быть свежим. Перед запросом сверь время индекса с последним коммитом репо (см. «Свежесть»). Устаревший индекс отвечает по старым скиллам так же уверенно, как по новым.
5. Корп-контур наружу не ходит. В team ответ формирует только внутренний шлюз организации; фолбэк на внешнюю модель запрещён в коде. Не пытайся «временно» прописать RAG_FALLBACK_* в rag.team.env — движок упадёт, и это правильно.

Процедура

1. Спроси индекс (интерпретатор — $env:SKILLS_PY, движок — $SKILLS_HOME/tools):

   cd $SKILLS_HOME/tools
   & $env:SKILLS_PY -m rag --contour team "как открыть MR в корпоративном гитлабе"

   Только фрагменты, без обращения к модели (быстро, работает офлайн):

   & $env:SKILLS_PY -m rag --contour shared --search -k 5 "чем чистить мусорные файлы"

2. Прочитай источники. Из блока «ИСТОЧНИКИ» возьми путь:строки и открой эти места через Read. Ответ пользователю строй по ним.
3. Фолбэк, если индекс недоступен (нет SKILLS_PY, не собран индекс): обычный Grep по $TEAM_SKILLS_HOME/skills, $SKILLS_HOME/skills, $PERSONAL_SKILLS_HOME/skills — и честно напиши в ответе, что искал без индекса, поэтому возможны пропуски.

Свежесть

Проверять перед использованием:

Get-ChildItem $SKILLS_RUNTIME/index\team -Recurse -File | Sort-Object LastWriteTime -Descending | Select-Object -First 1 LastWriteTime
git -C $TEAM_SKILLS_HOME log -1 --format="%h %ad %s" --date=iso-strict

Индекс старше последнего коммита → пересобрать (10-20 секунд, всё локально):

cd $SKILLS_HOME/tools
& $env:SKILLS_PY -m rag --contour team --ingest

Индексы обновляются git-хуками post-commit/post-merge в каждом скилл-репозитории; хуки ставятся $SKILLS_HOME/tools/rag\scripts\install_hooks.ps1.

Устройство (кратко)

Движок — $SKILLS_HOME/tools/rag. Эмбеддинги локальные (fastembed/ONNX, paraphrase-multilingual-MiniLM-L12-v2, 384): индексация целиком офлайн, тексты скиллов никуда не отправляются. Поиск гибридный — вектор + BM25 с RRF-фьюжном. Наружу уходит только вопрос с найденными фрагментами и только к провайдеру, который разрешён контуром: team — только внутренний шлюз, personal — DeepSeek, shared — корп с фолбэком на DeepSeek. Профили — %USERPROFILE%\.claude\rag.{team,personal,shared}.env, шаблоны рядом с движком в profiles/.

Индексы лежат в $SKILLS_RUNTIME/index\<контур>, окружение — $SKILLS_RUNTIME/.venv (переменные SKILLS_PY, FASTEMBED_CACHE_PATH).

Данные

Перед работой: git -C $SKILLS_HOME pull. При активации допиши строку <дата> skills-rag <проект> в data/usage.log, затем git add + commit + push в master.

Обратная связь

Если пользователь недоволен работой скилла — немедленно:

1. Прочитай последние ~20 строк CHANGELOG.md — нет ли уже такой жалобы
2. Спроси: что ожидал, что получил, что поправить
3. Исправь SKILL.md и допиши правку в конец CHANGELOG.md