Навыки Q.Palette для ИИ-агентов

Навыки (Agent Skills) — это пакет знаний о платформе Q.Palette, который ИИ-агент подгружает по требованию при разработке продукта: как устроены формы, таблицы, микрофронтенды, авторизация, локализация, дизайн-система и другие возможности платформы, с привязкой к актуальному API библиотек @diasoft/qpalette-*.

Навыки поставляются в открытом формате Agent Skills (opens in a new tab) (SKILL.md с метаданными и инструкциями). Один и тот же набор без адаптеров работает в Claude Code, opencode, Windsurf и Kilo Code — агент видит только релевантный навык и загружает его тело, когда задача этого требует.

Навыки — вспомогательный инструмент для разработки. Они не входят в рантайм продукта, не попадают в сборку и никак не влияют на поставку.

Установка CLI

Доставку навыков выполняет @diasoft/qpalette-cli. Установите его глобально:

npm install -g @diasoft/qpalette-cli@8 --@diasoft:registry=http://repolib-main.diasoft.ru:8081/repository/diasoft-npm-packages/

⚠️

Подкоманда skills sync доступна в CLI версии 8.x. На продукте Q.Palette 7 CLI всё равно ставьте восьмой версии — нужный набор навыков он определит по версии установленных библиотек продукта (см. ниже).

Подключение навыков в продукт

В корне продукта выполните:

qpalette skills sync

Команда загрузит из реестра пакет @diasoft/qpalette-skills и скопирует набор навыков, совпадающий по версии с установленными в продукте @diasoft/qpalette-* (правило «один продукт — одна версия»):

продукт на Q.Palette 8 (8.0.x) → навыки 8.x;
продукт на Q.Palette 7 (7.6.x) → навыки 7.x.

Версия определяется автоматически по node_modules и package.json продукта.

По умолчанию навыки копируются в два каталога, чтобы их подхватили разные ИИ-агенты без ручной настройки:

.agents/skills — открытый кросс-агентный стандарт; отсюда навыки берут многие агенты (opencode, Windsurf, Kilo Code и другие);
.claude/skills — отсюда навыки читает Claude Code (и opencode).

Так набор оказывается доступен и агентам, работающим по открытому стандарту, и Claude Code — без дополнительных настроек с вашей стороны.

Копирование, а не символические ссылки — ради кроссплатформенности (на Windows символические ссылки требуют прав администратора). Синхронизация трогает только каталоги с префиксом qpalette-: ваши собственные навыки в .claude/skills и .agents/skills команда не изменяет и не удаляет.

Помимо навыков конкретной версии команда всегда доставляет версионно-нейтральные навыки: написание юнит-тестов на фреймворке проекта (Jasmine или Vitest) и проверку локальной сборки на стенде.

Параметры

Флаг	Назначение	По умолчанию
`--project <path>`	Каталог продукта	текущая директория
`--version <X.x>`	Принудительная версия навыков	по версии `@diasoft/qpalette-*`
`--dest <dir>`	Каталог назначения (переопределяет дефолт — раскладку в оба каталога)	`.claude/skills` + `.agents/skills`
`--package-version <range>`	Версия пакета `@diasoft/qpalette-skills`	`latest`
`--registry <url>`	Реестр загрузки	корпоративный Nexus Diasoft

Пример — доставить навыки в явно указанную папку с принудительной версией:

qpalette skills sync --version 8.x --dest .claude/skills

Как агент использует навыки

После синхронизации навыки готовы к работе: при старте агент читает только их краткие описания и подгружает полное содержимое навыка, когда задача ему соответствует. Отдельных действий не требуется — достаточно, чтобы каталоги .claude/skills и .agents/skills были в корне продукта (команда создаёт их сама).

Набор навыков привязан к версии платформы в продукте, поэтому при любом изменении версии Q.Palette повторно запускайте qpalette skills sync — чтобы навыки снова совпали с установленными библиотеками. Это касается не только автоматического обновления: если вы поменяли версию @diasoft/qpalette-* в package.json вручную (например, перевели продукт на другую линию — с 7 на 8 или наоборот), навыки не обновятся сами — их нужно пересинхронизировать той же командой, иначе в продукте останется набор от прежней версии.

Проверка, что навыки видны агенту

1. Файлы на месте. После синхронизации в корне продукта появляются два каталога навыков; в каждом — подкаталоги qpalette-*, а внутри каждого — файл SKILL.md:

<корень продукта>/
├── .agents/
│   └── skills/
│       ├── qpalette-forms/
│       │   └── SKILL.md
│       ├── qpalette-data-tables/
│       │   └── SKILL.md
│       ├── … (остальные навыки версии продукта)
│       ├── qpalette-unit-tests/
│       │   └── SKILL.md
│       └── qpalette-stand-local-proxy/
│           └── SKILL.md
└── .claude/
    └── skills/
        └── … (тот же набор qpalette-*)

Если оба каталога есть и заполнены навыками qpalette-* — доставка прошла успешно.

2. Агент запущен там, где лежат навыки. Навыки читаются при старте агента, поэтому агент — будь то CLI в терминале, расширение в редакторе или десктопное приложение — должен работать с тем продуктом, в который вы синхронизировали навыки (открыт как рабочая папка/проект). Если агент уже был запущен — перезапустите его или переоткройте продукт, чтобы он перечитал каталоги навыков.

3. Агент видит навыки. Спросите у агента, какие навыки Q.Palette ему сейчас доступны — в ответе он должен перечислить навыки qpalette-* с их описаниями. Многие агенты также показывают доступные навыки в своём интерфейсе (список навыков, автодополнение по имени и т.п.) — конкретный способ зависит от агента.

4. Навык активируется по задаче. Сформулируйте запрос, попадающий под назначение навыка (например, «помоги сделать форму на Q.Palette»), и убедитесь, что агент подтягивает соответствующий навык (qpalette-forms). Это и есть штатная работа: тело навыка загружается, когда задача совпала с его описанием.

Если навыки не видны — убедитесь, что агент работает именно с тем продуктом, куда вы их синхронизировали, а каталоги .agents/skills и .claude/skills существуют и содержат qpalette-*/SKILL.md. Если ваш ИИ-агент не из перечисленных выше и подключить навыки не удаётся — обратитесь в команду Q.Palette.

Частые вопросы

В каких ИИ-агентах работают навыки? В любых, поддерживающих открытый формат Agent Skills (opens in a new tab), — в том числе Claude Code, opencode, Windsurf и Kilo Code. Один и тот же набор работает без адаптеров. Если ваш агент не из перечисленных и подключить навыки не удаётся — обратитесь в команду Q.Palette.

Куда команда кладёт навыки? В два каталога в корне продукта: .agents/skills (открытый стандарт, отсюда берут многие агенты) и .claude/skills (Claude Code). Файлы копируются, а не связываются символическими ссылками, — чтобы одинаково работать на любой ОС, включая Windows.

Как определяется версия навыков? Автоматически по установленным в продукте библиотекам @diasoft/qpalette-*: 8.0.x → навыки 8.x, 7.6.x → навыки 7.x. Действует правило «один продукт — одна версия».

Я поменял версию Q.Palette — что делать? Повторно запустить qpalette skills sync. Навыки привязаны к версии платформы и сами не обновляются, в том числе при ручной правке версии в package.json — иначе останется набор от прежней версии.

Затрёт ли синхронизация мои собственные навыки? Нет. Команда управляет только каталогами с префиксом qpalette-; ваши собственные навыки в .agents/skills и .claude/skills она не изменяет и не удаляет.

Влияют ли навыки на сборку или работу продукта? Нет. Навыки — вспомогательный инструмент для разработки: они не входят в рантайм, не попадают в сборку и не влияют на поставку.

Как понять, что навыки подключились? Проверьте, что в корне продукта есть каталоги .agents/skills и .claude/skills с навыками qpalette-*, запустите агента с этим продуктом и спросите, какие навыки Q.Palette ему доступны (подробнее — раздел «Проверка, что навыки видны агенту»).

Чеклист по оптимизации Выпуски Q.Palette