Nexus-skills
Haaaiawd/Nexus-skillsДва скилла для AI-агентов: nexus-mapper строит персистентную базу знаний .nexus-map/ по репозиторию, nexus-query мгновенно отвечает на структурные вопросы — зависимости, граф импортов, радиус влияния изменений. Работает на чистом Python, без внешних зависимостей.
Установка
git clone https://github.com/Haaaiawd/Nexus-skills.gitREADME
Два скилла, одна философия
| Скилл | Что делает | Когда использовать |
|---|---|---|
| nexus-mapper | Анализирует весь репозиторий и записывает персистентную базу знаний .nexus-map/ для будущих AI-сессий | При первом знакомстве с незнакомым репо, онбординге команды или подготовке к крупным архитектурным изменениям |
| nexus-query | Запрашивает структуру файлов, обратные зависимости, радиус влияния изменений и горячие точки связанности напрямую из AST-данных | В процессе активной разработки — перед изменением интерфейсов, рефакторингом или навигацией по легаси-коду |
Оба скилла используют одни и те же базовые скрипты. nexus-query может переиспользовать .nexus-map/, созданную nexus-mapper, или по запросу сгенерировать собственный ast_nodes.json.
nexus-mapper
nexus-mapper — скилл для AI-агентов, создающий карту репозитория. Он анализирует локальную кодовую базу, записывает персистентную базу знаний .nexus-map/ и даёт следующей сессии конкретную точку входа — вместо того чтобы заново открывать архитектуру с нуля.
Это не обычный промпт «суммаризируй репо». Скилл запускает поэтапный PROBE-воркфлоу, проверяет собственные первоначальные предположения и только после этого записывает финальные артефакты. Такой подход важен: он снижает типичную ошибку AI — превращать первые впечатления в ложную уверенность.
Когда репозиторий содержит «шумные» папки — сторонние статические ресурсы, сгенерированные деревья или тулчейны языков — общий сканер extract_ast.py поддерживает явную фильтрацию:
--exclude-dirs django_static,.go_root,third_party/assets— исключает имена директорий или пути относительно корня репо--use-gitignore— применяет правила<repo_path>/.gitignoreи игнорирует объявленные там файлы и директории--no-gitignore— отключает только правила.gitignore; встроенные исключения шума и--exclude-dirsпо-прежнему работают
.nexus-map/
├── INDEX.md ← Загружать первым. Полный архитектурный контекст, менее 2000 токенов.
├── arch/
│ ├── systems.md ← Каждая подсистема: что ей принадлежит, где именно находится в репо.
│ ├── dependencies.md ← Как компоненты связаны. Отрисовано как граф зависимостей Mermaid.
│ └── test_coverage.md ← Статическое покрытие тестами: что тестируется, что нет, где доказательств мало.
├── concepts/
│ ├── concept_model.json ← Машиночитаемый граф знаний. Структурирован для программного использования.
│ └── domains.md ← Доменный язык этой кодовой базы, простыми словами.
├── hotspots/ ← Присутствует при наличии git-метаданных.
│ └── git_forensics.md ← Файлы, которые меняются постоянно, и пары, которые всегда меняются вместе.
└── raw/ ← Исходные данные: AST-узлы, git-статистика, отфильтрованное дерево файлов.
INDEX.md — точка входа и маршрутизатор. После его прочтения загрузите все пять сопутствующих файлов перед тем как предпринимать действия — они намеренно сделаны короткими (обычно менее 5000 токенов суммарно).
nexus-query
nexus-query даёт точные мгновенные ответы на структурные вопросы в процессе активной разработки — без чтения всей кодовой базы.
# Скелет файла: классы, методы, номера строк, импорты
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --file src/core/vision.py
# Обратная зависимость: кто импортирует этот модуль?
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --who-imports src.core.vision
# Радиус влияния: upstream-зависимости + downstream-зависимые
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --impact src/core/vision.py \
--git-stats git_stats.json
# Анализ архитектурных хабов: модули с наибольшим fan-in / fan-out
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --hub-analysis
# Структурная сводка по директориям
python skills/nexus-query/scripts/query_graph.py ast_nodes.json --summaryНоль дополнительных зависимостей. Чистая Python stdlib. ast_nodes.json может быть взят из существующего .nexus-map/raw/ или из свежего запуска extract_ast.py.
Когда это особенно важно:
- Перед любым изменением интерфейса:
--who-importsточно покажет, что сломается - Перед спринтом:
--impact --git-statsколичественно оценит риски и объём работ - В легаси-коде:
--fileдаст скелетную карту без чтения 3000 строк - На архитектурном ревью:
--hub-analysisнайдёт реальные точки связанности, а не только те, что называютсяcore/
Почему они разные
- Поэтапное выполнение: фазы PROFILE, REASON, OBJECT, BENCHMARK и EMIT в nexus-mapper не опциональны.
- Честное происхождение данных: оба скилла различают
implemented,plannedиinferred. Если парсинг частичный — об этом явно сообщается. - Компонуемость: nexus-query работает самостоятельно или поверх карты nexus-mapper.
- Оптимизация для будущих сессий: каждый артефакт спроектирован для загрузки в следующий раз, а не только в текущий.
Требования
| Требование | Проверка |
|---|---|
| Python 3.10+ | python --version |
| Выполнение команд в терминале | Ваш AI-клиент должен поддерживать запуск команд в оболочке |
Git-репозиторий рекомендован, но не обязателен. Без git-истории анализ горячих точек пропускается, остальное работает в штатном режиме.
Установка зависимостей скриптов:
# nexus-mapper
pip install -r skills/nexus-mapper/scripts/requirements.txt
# nexus-query (те же зависимости)
pip install -r skills/nexus-query/scripts/requirements.txtУстановка
# Полный набор
npx skills add haaaiawd/nexus-skills
# Или только нужный скилл
npx skills add haaaiawd/nexus-skills/skills/nexus-mapper
npx skills add haaaiawd/nexus-skills/skills/nexus-queryРаботает с Claude Code, GitHub Copilot, Cursor, Cline и любым клиентом, который читает SKILL.md.
Как использовать nexus-mapper
После установки скажите своему AI-агенту:
Map this repository using nexus-mapper.
Агент запустит скрипты, применит PROBE-воркфлоу и запишет .nexus-map/ в корень репозитория.
В следующей сессии скажите:
Load .nexus-map/INDEX.md and all companion files, then help me refactor the auth module.
Агент начнёт с полным архитектурным контекстом — без повторного сканирования.
Как использовать nexus-query
После установки скажите своему AI-агенту:
Before I change the signature of
UserService.authenticate(), use nexus-query to show me everything that imports it and estimate the blast radius.
Агент запустит query_graph.py с флагами --who-imports и --impact и вернёт точный список затронутых файлов.
Лицензия
MIT