VibeOS Skill Authoring

Создание SKILL.md в репозитории: frontmatter, валидатор, структура и принципы качества написания.

Метаданные навыка


Источник	Встроенный (устанавливается по умолчанию)
Путь	`skills/software-development/vibeos-agent-skill-authoring`
Версия	`1.1.0`
Автор	VibeOS
Лицензия	MIT
Платформы	linux, macos, windows
Теги	`skills`, `authoring`, `vibeos-agent`, `conventions`, `skill-md`
Связанные навыки	`plan`, `requesting-code-review`

Справочник: полный SKILL.md

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при его активации. Это инструкции, которые видит агент, когда навык активен.

Создание навыков VibeOS (в репозитории)

Обзор

SKILL.md может находиться в двух местах:

Локально у пользователя: ~/.vibeos/skills/<возможно-категория>/<имя>/SKILL.md — личное, не публикуется. Создаётся через skill_manage(action='create').
В репозитории (этот навык описывает этот случай): /home/bb/vibeos-agent/skills/<категория>/<имя>/SKILL.md — фиксируется в коммитах, поставляется с пакетом. Используйте write_file + git add. skill_manage(action='create') НЕ работает с этим деревом.

Когда использовать

Пользователь просит добавить навык «в эту ветку / репозиторий / коммит»
Вы фиксируете переиспользуемый рабочий процесс, который должен поставляться с vibeos-agent
Вы редактируете существующий навык в /home/bb/vibeos-agent/skills/ (используйте patch для небольших правок, write_file для перезаписи; skill_manage всё ещё работает для patch для навыков в репозитории, но не для create)

Обязательный Frontmatter

Источник истины: tools/skill_manager_tool.py::_validate_frontmatter. Жёсткие требования:

Начинается с --- как первые байты (без ведущей пустой строки).
Заканчивается \n---\n перед телом.
Парсится как YAML-отображение.
Присутствует поле name.
Присутствует поле description, ≤ 1024 символов (MAX_DESCRIPTION_LENGTH).
Непустое тело после закрывающего ---.

Форма, используемая всеми навыками в skills/software-development/:

---
name: my-skill-name               # строчные буквы, дефисы, ≤64 символа (MAX_NAME_LENGTH)
description: Используйте, когда <триггер>. <однострочное описание поведения>.
version: 1.1.0
author: VibeOS
license: MIT
metadata:
  vibeos:
    tags: [короткие, описательные, теги]
    related_skills: [другой-навык, ещё-один-навык]
---

version / author / license / metadata НЕ проверяются валидатором, но есть у всех остальных навыков — если их опустить, ваш навык будет выглядеть чужеродно.

Ограничения по размеру

Описание: ≤ 1024 символов (проверяется).
Полный SKILL.md: ≤ 100 000 символов (проверяется как MAX_SKILL_CONTENT_CHARS, ~36k токенов).
Остальные навыки в software-development/ имеют размер 8-14k символов. Стремитесь к этому диапазону. Если превышаете 20k, разбейте на references/*.md и ссылайтесь на них из SKILL.md.

Принципы качества написания

Навык существует, чтобы сделать процесс работы агента более предсказуемым. Предсказуемость НЕ означает одинаковый результат при каждом запуске; это означает, что агент надёжно следует одной и той же полезной дисциплине.

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

Оптимизируйте для предсказуемости процесса. Спросите: какое поведение должно измениться при загрузке этого навыка? Если строка не меняет поведение, удалите её.
Выбирайте правильную нагрузку на контекст. Описание навыка, вызываемого моделью, оплачивается каждый ход. Держите описания сфокусированными на классах триггеров и отличительном поведении навыка. Детали помещайте в тело или связанные ссылки.
Используйте иерархию информации. Всегда необходимые шаги помещайте в SKILL.md; специфичные для веток или объёмные справочные материалы — в references/, templates/ или scripts/ и ссылайтесь на них только при необходимости.
Завершайте шаги критериями завершения. Каждый упорядоченный шаг должен указывать, как агент узнаёт, что он выполнен. Хорошие критерии проверяемы и, когда это важно, исчерпывающи: «каждый изменённый файл учтён» лучше, чем «обобщить изменения».
Размещайте правила рядом с концепцией, которую они регулируют. Избегайте разбрасывания одной идеи по всему файлу. Держите определение, оговорки, примеры и проверку рядом друг с другом.
Используйте сильные ведущие слова. Предпочитайте компактные концепции, которые модель уже знает — например, «тесный цикл», «трассерная пуля», «коренная причина», «регрессионный тест» — длинным повторяющимся объяснениям. Хорошее ведущее слово экономит токены и закрепляет поведение.
Удаляйте дублирование и холостые операции. Держите каждое значение в одном источнике истины. Предложение за предложением спрашивайте, меняет ли предложение поведение агента по сравнению с поведением по умолчанию. Если нет, удалите его, а не шлифуйте.
Следите за преждевременным завершением. Если агенты склонны спешить с шагом, сначала уточните критерий завершения этого шага. Разделяйте последовательность только тогда, когда последующие шаги отвлекают от качественного выполнения текущего.

Распространённые проблемы качества:

Преждевременное завершение — навык позволяет агенту перейти дальше до того, как работа действительно сделана.
Дублирование — одно и то же правило появляется в нескольких местах и расходится.
Осадок — устаревшие строки остаются, потому что добавление казалось безопаснее удаления.
Расползание — слишком много всегда видимого материала; выносите специфичные для веток ссылки за указатели.
Холостой текст — общие советы, которым агент следовал бы и без навыка.

Структура, используемая другими навыками

Каждый навык в репозитории примерно следует такой структуре:

# <Название>

## Обзор
Один-два абзаца: что и зачем.

## Когда использовать
- Маркированные триггеры
- «Не использовать для:» контр-триггеры

## <Разделы по теме, специфичные для навыка>
- Часто встречаются таблицы быстрого доступа
- Блоки кода с точными командами
- Рецепты, специфичные для VibeOS (тесты через scripts/run_tests.sh, пути ui-tui и т.д.)

## Распространённые ошибки
Нумерованный список ошибок и их исправлений.

## Контрольный список проверки
- [ ] Список флажков для проверки после действий

## Одноразовые рецепты (опционально)
Именованные сценарии → конкретные последовательности команд.

Не каждый раздел обязателен, но Обзор + Когда использовать + практическое тело + ошибки — это минимум, чтобы навык ощущался как равный.

Размещение в каталогах

skills/<категория>/<имя-навыка>/SKILL.md

Категории, существующие в репозитории (подтвердите через ls skills/): autonomous-ai-agents, creative, data-science, devops, dogfood, email, gaming, github, leisure, mcp, media, mlops/*, note-taking, productivity, red-teaming, research, smart-home, social-media, software-development.

Выбирайте ближайшую существующую категорию. Не создавайте новые категории верхнего уровня без необходимости.

Рабочий процесс

Изучите аналоги в целевой категории:
```
ls skills/<категория>/
```
Прочитайте 2-3 файла SKILL.md аналогов, чтобы соответствовать тону и структуре.
Проверьте ограничения валидатора в tools/skill_manager_tool.py, если не уверены.
Напишите черновик с помощью write_file в skills/<категория>/<имя>/SKILL.md.

Проверьте локально:

import yaml, re, pathlib
content = pathlib.Path("skills/<категория>/<имя>/SKILL.md").read_text()
assert content.startswith("---")
m = re.search(r'\n---\s*\n', content[3:])
fm = yaml.safe_load(content[3:m.start()+3])
assert "name" in fm and "description" in fm
assert len(fm["description"]) <= 1024
assert len(content) <= 100_000

Выполните git add + commit в активной ветке.
Примечание: загрузчик навыков текущей сессии кэшируется — skill_view / skills_list не увидят новый навык до новой сессии. Это ожидаемо, а не ошибка.

Перекрёстные ссылки на другие навыки

metadata.vibeos.related_skills объединяет оба дерева (skills/ в репозитории и ~/.vibeos/skills/) во время загрузки. Вы МОЖЕТЕ ссылаться на локальный навык пользователя из навыка в репозитории, но он не будет разрешён для других пользователей, которые клонируют репозиторий заново. Предпочитайте ссылаться только на навыки из репозитория. Если часто используемый навык живёт только в ~/.vibeos/skills/, рассмотрите возможность его переноса в репозиторий.

Редактирование существующих навыков в репозитории

Небольшое исправление (опечатка, добавленная ошибка, уточнённый триггер): skill_manage(action='patch', name=..., old_string=..., new_string=...) отлично работает с навыками в репозитории.
Серьёзная переработка: write_file для всего SKILL.md. skill_manage(action='edit') также работает, но требует указания полного нового содержимого.
Добавление вспомогательных файлов: write_file в skills/<категория>/<имя>/references/<файл>.md, templates/<файл> или scripts/<файл>. skill_manage(action='write_file') также работает и проверяет разрешённый список подкаталогов references/templates/scripts/assets.
Всегда фиксируйте правку — навыки в репозитории — это исходный код, а не состояние выполнения.

Распространённые ошибки

Использование skill_manage(action='create') для навыка в репозитории. Он записывает в ~/.vibeos/skills/, а не в дерево репозитория. Используйте write_file для создания в репозитории.
Пробелы в начале перед ---. Валидатор проверяет content.startswith("---"); любая ведущая пустая строка или BOM приводит к ошибке валидации.
Слишком общее описание. Описания аналогов начинаются с «Используйте, когда ...» и описывают класс триггера, а не одну задачу. «Используйте при отладке X» лучше, чем «Отладка X».
Забытый блок author/license/metadata. Не проверяется валидатором, но есть у всех аналогов; его отсутствие делает навык наполовину готовым.
Написание навыка, дублирующего аналог. Перед созданием выполните ls skills/<категория>/ и откройте 2-3 аналога. Предпочитайте расширение существующего навыка созданию узкого собрата.
Ожидание, что текущая сессия увидит новый навык. Она не увидит. Загрузчик навыков инициализируется при запуске сессии. Проверяйте в новой сессии или через skill_view, используя точный путь.
Накопление осадка в навыках. Навык должен становиться короче или точнее со временем. При добавлении правила удаляйте старую формулировку, которую оно заменяет; не наслаивайте советы бесконечно.
Написание холостого текста. «Будьте осторожны», «будьте тщательны» и «используйте лучшие практики» редко меняют поведение модели. Замените на проверяемый критерий завершения или более сильное ведущее слово.
Ссылки на навыки, которых нет в репозитории. related_skills: [some-user-local-skill] работает для вас, но ломается для других клонов. Предпочитайте ссылки только на навыки из репозитория.

Метаданные навыка​

Справочник: полный SKILL.md​

Создание навыков VibeOS (в репозитории)

Обзор​

Когда использовать​

Обязательный Frontmatter​

Ограничения по размеру​

Принципы качества написания​

Структура, используемая другими навыками​

Размещение в каталогах​

Рабочий процесс​

Перекрёстные ссылки на другие навыки​

Редактирование существующих навыков в репозитории​

Распространённые ошибки​

Контрольный список проверки​