Как создать навык Open WebUI с инструкцией и файлом

Допустим, Анна ведёт книжный клуб и регулярно готовит короткие объявления о встречах. Книга, дата, время и место меняются, а порядок подготовки остаётся прежним: проверить, хватает ли сведений, и при необходимости сначала уточнить недостающее.

Когда одинаковый порядок проверки нужен в разных диалогах, в Open WebUI используют навыки (Skills). Согласно официальной документации Skills и серверной модели хранения навыков, навык (Skill) в Open WebUI — сохранённая переиспользуемая Markdown-инструкция с метаданными и вспомогательными файлами. Сохранение навыка не обучает модель, не меняет её веса и само по себе не запускает скрипты: модель получает переданные правила, а выполнение этих правил затем нужно проверить по её ответу.

Ниже описана документальная процедура по официальной документации и закреплённому коду стабильного релиза Open WebUI v0.12.3. Мы не выполняли эти шаги в живом интерфейсе и не получали ответы модели: вы сохраните навык в своей установке, выберете его в чате и сами зафиксируете, прочитала ли модель вспомогательный файл и выполнила ли правила на двух проверочных запросах.

Подготовьте инструкцию навыка и отдельную памятку

Если факты каждой встречи новые, один раз стоит сохранить сам порядок их обработки. Чтобы наглядно разделить общую инструкцию и отдельно запрашиваемый справочный материал, подготовим для навыка два коротких текстовых файла: корневой SKILL.md и вспомогательный checklist.md. Для столь короткого правила на практике хватило бы и одного файла, но пара файлов позволит увидеть и проверить механизм отдельного чтения через встроенный инструмент. Оба приведённых ниже текста — предлагаемые входные данные для вашей проверки, а не отчёт о ранее проведённом запуске.

В этой задаче у навыка своя роль, отличная от соседних инструментов рабочей области (сравнение возможностей в документации Skills):

• Обычное сообщение и сохранённые Prompts передают входную реплику пользователя (описание Prompts). В уроке про шаблоны запросов и переменные человек подставлял факты в заготовку до отправки, тогда как Skill хранит правила обработки и подключается к разным диалогам без повторной вставки шаблона.
• System Prompt задаёт постоянную базовую установку внутри конкретного пресета (настройки Models; устройство пресета разобрано в уроке про модель и пресет ассистента), а навык создаётся один раз и выбирается по мере необходимости.
• Knowledge хранит коллекции документов для поиска фактов и контекста (описание Knowledge), тогда как наш навык не заменяет источник фактов о встрече — их по-прежнему сообщает человек.
• Tools предоставляют исполняемые операции (например, вычисление или обращение к внешнему API), а Skill содержит текстовые правила подхода к задаче.

Подготовьте текст основного файла SKILL.md:

# Правила объявления клуба

Применяй эти правила, когда просят составить объявление о встрече книжного клуба.

1. Перед ответом прочитай файл `checklist.md` этого навыка через `read_skill_file`, используя ID `klub-anons-rules` и путь `checklist.md`. Если прочитать файл не удалось, сообщи об этом; не утверждай, что проверка выполнена.
2. Сверь входные сведения с памяткой. Если не хватает обязательного сведения, задай уточняющий вопрос и пока не составляй объявление.
3. Если сведения полные, напиши по-русски черновик из трёх коротких предложений. Сохрани все переданные факты; не придумывай адрес, цену, контакты или условия участия.
4. Не выполняй команды и не меняй файлы: задача навыка — подготовить и проверить текст.

Подготовьте текст вспомогательной памятки checklist.md:

# Проверка объявления

Обязательные сведения: название книги, дата и время встречи, место встречи.
Если хотя бы одного обязательного сведения нет, спроси его у пользователя.

Сверь черновик с исходным сообщением: книга, дата, время и место сохранены; нет добавленных адреса, цены, контактов или условий участия.

Между этими текстами и устройством Open WebUI есть три практические связи:

1. Новые факты остаются в сообщении чата. В файлах навыка нет ни «Капитанской дочки», ни даты встречи — там описан только порядок проверки и требования к черновику.
2. Вспомогательный файл читается по ID навыка и относительному пути. Корневой SKILL.md обязателен и должен быть текстом в кодировке UTF-8 (правила валидации файлов навыка). Памятка checklist.md хранится внутри записи самого навыка с относительным POSIX-путём без начального / и без ..: это не обычное файловое вложение в чат, не коллекция Knowledge и не чтение произвольной папки на вашем компьютере.
3. Упоминание имени файла в инструкции не доказывает его чтение. То, что в SKILL.md написана строка checklist.md, — лишь текстовое указание для модели. Чтобы получить содержимое памятки, модель должна реально вызвать встроенный инструмент read_skill_file с аргументами id и path (работа инструмента read_skill_file), а само наличие текстовой инструкции не гарантирует, что модель ей подчинится.

Для этой практики не нужны ни Python, ни shell, ни терминал, ни изменение файлов моделью. Даже если бы внутри навыка лежал текст скрипта, само хранение или чтение текста через read_skill_file код не исполняет (ограничения текстовых навыков, системные стандарты создания навыков). Тем не менее не помещайте в навыки секретные данные и не считайте сторонний навык безопасным только потому, что он написан в Markdown: перед подключением чужого навыка всегда прочитывайте все его инструкции и файлы, так как выбранные тексты попадают в контекст запроса к подключённой модели, а при включённых исполняемых инструментах (Tools) инструкция может направлять их вызовы. Политики маршрутизации и хранения данных на стороне конкретного внешнего провайдера (provider routing и retention) в рамках этого материала не исследовались и остаются неизвестными.

Сохраните навык в Workspace Skills

Теперь превратим оба подготовленных текста в сохранённую запись с собственным идентификатором. Мы приводим точные английские названия элементов из кода стабильного релиза v0.12.3; в вашей установке русская локализация или версия интерфейса могут отличаться.

Откройте Workspace → Skills. Для раздела и кнопки Create достаточно права workspace.skills; роль администратора не обязательна (проверка доступа к разделу Workspace, условие отображения кнопки Create). Право workspace.skills_import само по себе раздел не открывает (маршрутизатор создания навыка). Если раздела или кнопки нет, обратитесь к администратору своей установки.

Нажмите Create и заполните три верхних поля редактора (поля и кнопки SkillEditor.svelte):

• Skill Name: Правила объявления клуба
• Skill Description: Помогает подготовить короткое объявление о встрече книжного клуба по известным фактам и проверить недостающие сведения.
• Skill ID: klub-anons-rules

При заполнении этих полей учитывайте порядок работы редактора:

1. Сначала введите имя, а затем вручную укажите латинский Skill ID. В интерфейсе обязательными помечены Skill Name и Skill ID, а описание (Skill Description) не помечено как обязательное, но помогает ориентироваться в списке и используется при обнаружении навыка. Когда вы печатаете имя в режиме создания, редактор автоматически формирует Skill ID (автогенерация ID в редакторе) через функцию slugify, которая удаляет кириллицу, а не транслитерирует её. Поэтому после ввода русского названия обязательно впишите klub-anons-rules вручную (сервер допускает только символы [a-z0-9_-]+). Если вы поправите Skill Name позже, до сохранения ещё раз проверьте поле Skill ID.
2. Не перезаписывайте чужие записи при совпадении имени или ID. Имя и идентификатор должны быть свободны в вашей установке (проверка уникальности на бэкенде). Если Правила объявления клуба или klub-anons-rules уже заняты, выберите свободные значения (например, Правила объявления клуба 2 и klub-anons-rules-2, если они свободны) и одинаково замените ID в шаге 1 текста SKILL.md, в проверочных критериях обоих тестов и в своём листе наблюдений.

После заполнения шапки добавьте оба файла в файловой панели редактора:

1. В открытом по умолчанию корневом файле SKILL.md (поле Skill Instructions) вставьте полный текст инструкции из предыдущего раздела. Добавлять в начало файла блок YAML frontmatter при заполненных полях интерфейса не требуется, а функции импорта или команду /skills:create для этой практики мы не используем.
2. В файловой панели нажмите кнопку меню ... (Actions), выберите New File, введите в корне имя checklist.md и нажмите Enter (поле инструкций и меню действий).
3. В открывшемся пустом черновике checklist.md вставьте подготовленный текст памятки. Создание черновика файла в списке ещё не сохраняет сам навык на сервере (работа с файлами в SkillFiles.svelte).
4. Нажмите Save & Create, чтобы сохранить всю запись вместе с обоими файлами. Настройки доступа (Access) не меняйте.

Сохранение обращается к серверу и базе данных, но ещё не запускает генерацию (обработчик страницы создания). Права чтения и изменения проверяются отдельно (проверки прав доступа, проверка прав при обновлении); привязка приватного навыка к общей модели не выдаёт другим пользователям право read (раздел Access Control в документации). Настройки Access не меняйте. Отсутствие выданных разрешений не означает полной приватности от администратора или оператора сервера.

Сразу после сохранения вернитесь в список Workspace → Skills, заново откройте созданный навык и сверьте три поля шапки и полный текст обоих файлов (SKILL.md и checklist.md). Если позже понадобится исправить опечатку в существующем навыке, откройте его, внесите правку и нажмите Save, а изменённую редакцию проверяйте в новом независимом чате (привязка skill_versions в middleware).

Выберите навык для чата и проверьте режим инструментов

Сохранённая запись в рабочей области ещё не передана в конкретный разговор. Чтобы модель получила текст SKILL.md и смогла прочитать отдельный файл checklist.md, в обычном веб-чате Open WebUI после входа в учётную запись должны одновременно выполняться четыре условия:

1. Выбранная модель и её подключение поддерживают нативный вызов инструментов (Native function calling / tool calling; требования к function calling в документации). При нативном вызове инструментов модель может сформировать запрос к встроенной операции; Open WebUI выполняет полученный вызов и возвращает его результат в разговор.
2. Для модели включена возможность системных встроенных инструментов (Builtin Tools; проверка use_builtin_tools и сборка навыков в middleware).
3. Внутри встроенных инструментов остаётся включённой категория Skills (подключение встроенных инструментов навыков).
4. Вы работаете в обычном сеансе веб-интерфейса Open WebUI с одной моделью (внутренние чаты заметок, прямые вызовы API без сессии, внешние пайплайны и сторонние клиенты не являются эквивалентными путями).

Где именно в вашей установке переключаются эти настройки и поддерживает ли их конкретный провайдер, заранее неизвестно — не угадывайте скрытые пути конфигурации и не настраивайте терминал. Если хотя бы одно из условий для чтения файлов недоступно или неизвестно, зафиксируйте это ограничение в листе наблюдений и остановите проверку чтения checklist.md: без активных инструментов навыков двухфайловая проверка невыполнима.

Если условия соблюдены, подготовьте чат по основному маршруту:

1. Откройте новый независимый чат с одной подходящей моделью.
2. Нажмите кнопку + (Integrations) рядом с полем ввода, перейдите в Skills и включите переключатель напротив Правила объявления клуба (меню интеграций в поле ввода).
3. Проверьте появившийся под полем ввода индикатор Available Skills и нажмите на него, чтобы увидеть название и описание выбранного навыка в модальном окне выбранных навыков.
4. До отправки сообщения запишите для себя версию Open WebUI, выбранную модель и подключение, режим вызова инструментов и проверенный в редакторе идентификатор навыка (klub-anons-rules или ваш свободный заменитель).

В качестве краткой альтернативы навык можно выбрать прямо из поля ввода: наберите символ $ и выберите Правила объявления клуба во всплывающем списке (выбор через $ в Commands/Skills.svelte). Применять оба способа одновременно не нужно; просто напечатанная вручную строка $Правила объявления клуба без выбора объекта из списка не доказывает подключение навыка.

Разберём, что происходит после явного выбора и чем эта ветка отличается от соседних режимов:

• Инструкция и памятка передаются по-разному. Для явно выбранного короткого навыка текст SKILL.md сразу добавляется в системное сообщение вместе со списком сопутствующих файлов, поэтому предварительный вызов view_skill модели не обязателен (обработка выбранных и доступных навыков в middleware). При этом сам текст checklist.md автоматически в промпт не вставляется — чтобы прочитать его из сохранённого слепка (snapshot), модель должна вызвать read_skill_file(id, path). Для текста инструкции действуют символьные лимиты и предварительный фрагмент для длинных инструкций; список вспомогательных файлов тоже ограничен отдельно (ограничения обзора файлов в skill_files.py). Лимиты хранения навыка не определяют, сколько текста одновременно получит модель. Текст читается страницами, а для бинарных файлов read_skill_file возвращает размер и ссылку на редактор, а не автоматически распознанный PDF или рисунок.
• Выключение переключателя в чате не запрещает доступ к навыку, а привязка к модели и Legacy работают иначе. В новом чате с одной моделью привязанный к её пресету навык предвыбирается, если он активен и доступен пользователю на чтение. При выборе нескольких моделей эта предвыборка пропускается (логика инициализации чата). В нативном режиме с Builtin Tools и категорией Skills остальные активные доступные навыки остаются в списке обнаружения manifest с id, name и description; модель может загрузить их через view_skill по своему решению. Поэтому выключение переключателя не запрещает доступ и не создаёт проверку без навыка. В Legacy, при выключенных Builtin Tools или категории Skills такого обнаружения и чтения вспомогательных файлов нет: текст выбранных, упомянутых и привязанных доступных активных навыков всё равно может вставляться в системную инструкцию; привязанный навык — даже после выключения переключателя.

Значок Available Skills подтверждает только выбор навыка в интерфейсе, а доступность инструмента read_skill_file не гарантирует, что модель его вызовет. При отправке сообщения выбранные инструкции, manifest и возвращённый инструментами текст входят в контекст запроса к вашему подключению модели: это расходует контекстное окно и токены и может тарифицироваться провайдером, при этом конкретная цена, экономия токенов и политика обработки данных провайдером заранее не установлены.

Проверьте чтение памятки и объявление с полными данными

В первом проверочном чате (назовём его чатом A), где навык Правила объявления клуба уже выбран и проверены условия нативного режима, передадим модели полный набор сведений о встрече. Не вызывайте здесь старый slash-шаблон из предыдущего урока и не используйте переменные в фигурных скобках — отправьте обычным сообщением следующий точный текст:

Подготовь объявление о встрече книжного клуба: обсуждаем «Капитанскую дочку», 12 ноября в 19:00, читальный зал.

Отправка запроса — ваше отдельное действие в вашей установке; мы не приводим вымышленный «образцовый» ответ модели или синтетический снимок экрана. Когда модель завершит генерацию, проверьте результат по трём независимым слоям. В штатном интерфейсе Open WebUI реальные вызовы инструментов отображаются в раскрывающемся блоке (ToolCallDisplay; отображение вызовов инструментов в сообщении), где видны имя функции, переданные аргументы (Input) и возвращённый результат (Output; структура полей Input и Output в ToolCallDisplay.svelte).

Используйте следующую таблицу, чтобы разделить выбор навыка, фактическое чтение файла и качество самого текста:

Если Output показан как объект, сверяйте текст в поле content с полным checklist.md; служебные поля вокруг текста не являются частью памятки.

При оценке второго слоя опирайтесь только на фактическую запись вызова инструмента (возврат содержимого и ошибок в read_skill_file):

• Поскольку короткий выбранный SKILL.md уже передан в системном сообщении, отсутствие вызова view_skill в этом чате ошибкой не является — нас интересует именно read_skill_file.
• Если в ответе вообще нет блока вызова read_skill_file, чтение файла считается неподтверждённым, даже если модель в самом тексте ответа уверяет, что «сверилась с памяткой» или «проверила чек-лист», и даже если сам черновик из трёх предложений выглядит аккуратно.
• Если инструмент вызван, но в Output вернулась ошибка (например, из-за неверного id или path) либо неполный текст, запишите это фактическое наблюдение в лист проверки — чтение не подтверждено. При этом один пропуск вызова у конкретной модели не означает, что механизм файлов навыков не работает в Open WebUI в целом.

Требование «три коротких предложения без выдуманных деталей» — это правило вашей инструкции в SKILL.md, а не встроенный автоматический фильтр платформы.

Проверьте запрос без места в новом чате

Первый тест проверял подготовку черновика при полных данных, но не показывал, остановится ли модель при содержательном пробеле во входном сообщении. Если отправить второй запрос в том же чате A, в истории диалога уже останется словосочетание «читальный зал», и модель сможет подставить его из предыдущих реплик.

Поэтому откройте новый независимый чат B с той же моделью, тем же подключением и тем же нативным режимом инструментов и заново явно выберите в нём навык Правила объявления клуба, проверив индикатор Available Skills. Используйте ту же сохранённую версию навыка с теми же двумя файлами; между проверками A и B правила не меняйте. (Если правила всё же изменили, для сопоставимого сравнения выполните обе проверки заново в двух новых независимых чатах.) Не переносите сюда место из первого чата, не подставляйте значения по умолчанию из урока про шаблоны и не вызывайте slash-команду прежнего промпта. Отправьте запрос, в котором указаны только книга, дата и время:

Подготовь объявление о встрече книжного клуба: обсуждаем «Маленького принца», 19 ноября в 18:00.

Оцените результат чата B раздельно по двум критериям:

1. Фактическое чтение файла. Как и в первом тесте, раскройте блок вызова инструмента и проверьте, вызвала ли модель read_skill_file с id вашего навыка (klub-anons-rules или выбранной заменой) и path: checklist.md и вернулся ли в Output полный текст памятки без ошибки. Отсутствие наблюдаемого вызова — отдельное неподтверждённое чтение.
2. Реакция на отсутствие места встречи. По правилам SKILL.md и checklist.md модель должна заметить отсутствие обязательного сведения и задать уточняющий вопрос о месте встречи до составления объявления. Если модель вместо вопроса сразу выдала готовый анонс, придумала помещение от себя или перенесла «читальный зал», правило навыка в этом запуске не соблюдено.

Такое поведение конкретной модели заранее не гарантировано. Здесь сравнивается полный и неполный ввод при одном выбранном навыке, а не работа с навыком и без него; эти два ответа не доказывают общего улучшения качества благодаря Skills.

По итогам двух проверок составьте собственный лист фактических наблюдений (записывайте только то, что реально увидели в своём интерфейсе):

• Дата, версия Open WebUI, модель и подключение: какие именно использовались при проверке.
• Условия режима инструментов: подтверждены ли Native tool calling, Builtin Tools и категория Skills, либо какое условие оказалось недоступным или неизвестным.
• Выбор и сохранение навыка: способ выбора и имя навыка в Available Skills; Skill Name, Skill ID и описание при повторном открытии редактора; совпали ли полные тексты SKILL.md и checklist.md. Версию записывайте, если она доступна в вашей установке; иначе отметьте, что она неизвестна.
• Фактический вызов инструмента в чатах A и B: имя вызванного инструмента (read_skill_file), точные значения Input (id и path), наличие полного текста памятки в Output либо текст ошибки или факт отсутствия вызова (no-call).
• Проверка ответа в чате A (полные данные): сохранены ли книга «Капитанская дочка», 12 ноября, 19:00 и читальный зал, соблюдено ли условие из трёх коротких предложений и нет ли добавленных от себя адреса, цены, контактов или условий участия.
• Проверка ответа в чате B (без места): задала ли модель уточняющий вопрос о месте встречи до написания объявления, или же выдала готовый анонс / выдумала место.
• Открытые вопросы: что осталось неизвестным после двух запусков в вашей установке.

После изменения правил нажмите Save и проверяйте новую редакцию в новом чате: прежняя беседа может использовать сохранённую версию (хранение версии слепка в чате, чтение слепка в builtin.py). Файлы и версии остаются на сервере Open WebUI, а инструкции и прочитанный текст входят в запрос к выбранному подключению. Маршрутизация, хранение данных и цена у провайдера этой процедурой не измеряются.

По записям из чатов A и B видно отдельно, что сохранилось, какой навык был выбран, прочитан ли checklist.md и соблюдены ли правила ответа. Неподтверждённое чтение или ошибка в ответе так и остаются в листе наблюдений.

Если эти проверки прошли, при желании перенесите тот же порядок на одну свою несекретную повторяемую задачу и проверьте её в новом чате.

Чтобы сохранить постоянную инструкцию в пресете и отдельно передавать новые факты, перейдите к уроку об ассистенте для рабочей задачи.