Навыки OpenCode позволяют оформить повторяемую процедуру команды в файле SKILL.md внутри папки навыка: OpenCode обнаруживает описание, а затем загружает инструкцию по запросу. Для первого навыка выберите узкую задачу, укажите входные данные и ожидаемый результат, проверьте разрешения и прогоните пример на безопасном материале. Файл полезен там, где процедуру можно проверить по явным критериям, а решение о принятии результата остаётся за человеком.
Поиск в репозитории
Для навыка проекта OpenCode ищет SKILL.md в папке .opencode/skills/<имя>/; документация также перечисляет совместимые папки .claude/skills/ и .agents/skills/. Имя папки совпадает с именем навыка в файле.
Начните с процедуры, которая повторяется в одном репозитории и имеет понятный результат. Подойдёт проверка отчёта о дефекте перед передачей разработчику: исходное сообщение, шаги воспроизведения, ожидаемое поведение и обнаруженные пробелы. Сохраните инструкцию рядом с проектом, чтобы изменение проходило обычное ревью кода. Глобальная папка подходит для навыка, который нужен в разных проектах; правило конкретной команды лучше хранить в её репозитории.
Официальная документация OpenCode описывает поиск файлов навыков вверх от текущего каталога до рабочего дерева Git. Поэтому при проверке важны текущая папка запуска и положение SKILL.md относительно репозитория. Для обнаружения файл должен лежать на пути из перечня OpenCode; качество описания проверяют уже после этого. В проекте полезно закрепить один ожидаемый путь и добавить его в ревью изменений.
Навык загружается через встроенный инструмент skill, когда доступен и выбран для задачи. Описание в списке доступных навыков помогает агенту понять назначение, поэтому формулировка должна называть конкретный вход и результат. Фраза «помогает с разработкой» слишком широка: она мешает отличить проверку отчёта о дефекте от анализа кода. Для другой роли OpenCode, связанной с вызовом внешних инструментов, есть материал про MCP в OpenCode; здесь речь только о файле повторяемой инструкции.
Контракт файла
Файл начинается с YAML-шапки. По документации OpenCode обязательны поля name и description; имя должно совпадать с именем папки и состоять из строчных латинских букв, цифр и одиночных дефисов. Для примера подойдёт bug-report-review в файле .opencode/skills/bug-report-review/SKILL.md. В описании укажите, когда проверять отчёт и какой результат нужен: перечень пропущенных сведений и проект уточнённой формулировки. Слишком общее имя навыка вроде helper оставит агенту мало опоры.
| Часть SKILL.md | Что записать | Как проверить |
|---|---|---|
| name | bug-report-review | Совпадает с папкой навыка |
| description | Проверка отчёта о дефекте: пропущенные сведения и черновик карточки | По фразе понятны вход и результат |
| Основная инструкция | Проверить шаги, ожидание, фактический результат и окружение | Каждый пункт виден в ответе |
| Граница | При отсутствии факта запросить уточнение | Агент сохраняет пробел как вопрос |
После шапки опишите процедуру человеческим языком: какие материалы открыть, какие признаки проверить, в каком формате вернуть вывод. Для отчёта о дефекте попросите отдельно перечислить подтверждённые факты и недостающие данные. Если отсутствуют шаги воспроизведения, итогом станет вопрос автору отчёта; выдуманная последовательность сделает карточку опасной для работы. Неявные договорённости команды лучше превратить в явные пункты проверки и пример ожидаемого ответа.
Общие правила репозитория продолжают действовать вместе с инструкцией. В ней хранится именно повторяемый рабочий приём: вход, действия, выход и граница ответственности. Примеры формулировок запросов к агенту разобраны в статье о промптах для агентов; в SKILL.md эти формулировки становятся частью проверяемой процедуры, доступной команде через репозиторий.
Разрешения загрузки
Права на загрузку навыка задаются отдельно от его текста. В официальном описании OpenCode для permission.skill предусмотрены режимы allow, deny и ask, а правила можно задавать по имени или шаблону. Для командной процедуры это даёт понятный выбор: обычные проверенные навыки доступны, экспериментальные требуют подтверждения, закрытые скрыты от вызова. Проверяйте действующую конфигурацию вместе с владельцем репозитория.
Чтение SKILL.md и право изменять файлы, запускать команды или публиковать результат проверяются раздельно. Такие действия подчиняются полномочиям рабочего окружения и процессу команды. В примере с отчётом о дефекте навык предлагает текст карточки, а сотрудник сверяет факты и решает, сохранять ли его. При использовании внутреннего трекера сервер должен проверять право записи и подтверждение действия. Инструкция напоминает о согласовании; фактический допуск к записи проверяет сервер.
- Разрешите загрузку навыка только в предусмотренной области применения.
- Дайте безопасной тестовой задаче материалы без ключей, токенов и клиентских личных данных.
- Отделите чтение исходного отчёта от записи в трекер и от рассылки результата.
- Назначьте человека, который принимает итог и отвечает за спорные формулировки.
Для команды важно различать доступность названия навыка и качество его исполнения. Список доступных навыков подтверждает обнаружение файла, а тестовая задача показывает, соблюдается ли процедура. Поэтому после настройки прав проведите проверку на примере с заранее известным пропуском. Результат сравните с эталоном. Эталон важнее уверенного тона ответа ИИ.
Тестовая задача
Предложите пилот на условном отчёте: «после нажатия кнопки сохранения изменений нет». В эталоне заранее отметьте, что отсутствуют шаги воспроизведения, версия приложения и ожидаемый результат. Попросите OpenCode применить навык к этому сообщению. Хороший ответ задаст уточняющие вопросы, выделит подтверждённый симптом и предложит шаблон карточки с пустыми полями. Он сохранит неизвестные факты открытыми до ответа сотрудника.
- Проверьте, что описание навыка отображается среди доступных и его имя совпадает с папкой.
- Дайте агенту условный отчёт и попросите выполнить процедуру без записи во внешнюю систему.
- Сравните ответ с эталоном: какие факты отмечены, какие вопросы заданы, какие поля остались пустыми.
- Добавьте второй пример с полным отчётом и посмотрите, сохраняется ли формат ответа без лишних уточнений.
- Передайте SKILL.md и оба результата на ревью владельцу процесса; согласованные правки внесите в файл.
Отчёт о проверке удобно хранить рядом с обсуждением изменения файла: входная задача, ожидаемые признаки и наблюдаемый ответ. Если тестовых карточек много, скрипт может проверить наличие обязательных полей и зафиксировать пропуски; языковая модель помогает разобрать спорные ответы и предложить гипотезы. Сотрудник сверяет каждый спорный факт с исходным сообщением. Аналогичный подход к сценариям и откату описан в материале о тестировании ИИ-агентов.
Если агент добавил обстоятельства сверх входных данных, исправьте правило о неизвестных фактах и повторите пример. Если поиск навыка завершился пустым результатом, вернитесь к месту файла, имени и разрешениям. Такой разбор разделяет сбой обнаружения и ошибку самой процедуры. Следующий пример для навыка имеет смысл выбирать по реальной вариации входных данных команды.
Какую процедуру вашего репозитория проверить первым навыком?
Ревью и поддержка
Ревью SKILL.md проводят как ревью рабочего правила. Проверьте, совпадает ли описание с фактическим содержимым, остаётся ли процедура узкой, понятно ли агенту, какие факты запросить у человека и как оформить результат. Если файл просит действие с побочным эффектом, рядом нужен явный шаг подтверждения и реальная проверка полномочий в исполнительной системе. Техническое разрешение на запись задаётся вне текста инструкции.
Поддержка начинается с изменений в процессе команды. Когда карточка дефекта получает новое обязательное поле, обновите инструкцию и эталонный пример в одном запросе на ревью. Если меняется структура репозитория, проверьте расположение папки навыка и обнаружение из обычного рабочего каталога. Сохранённая история изменений показывает, почему команда уточнила правило. Для более широкой практики обращения с агентом полезна статья о правах и секретах.
Навыки подходят для обучения общему порядку работы, когда сотрудник видит вход, проверку и критерий принятия. Обучение команды работе с ИИ можно связать с ревью таких процедур и разбором тестовых задач. Напишите нам, и мы оценим состав работ для ваших репозиториев: выбор процедуры, подготовку файла, настройку допуска и проверку на примерах. Стоимость зависит от сложности правил и числа команд; условия обсуждаем после знакомства с задачей.
Критерий приёмки: другой участник команды берёт тот же условный отчёт, запускает навык в предусмотренном окружении и проверяет, есть ли в ответе обязательные поля и обоснованные уточняющие вопросы. Если результат расходится, сначала сравните версии SKILL.md и входной задачи. Так исправление опирается на наблюдаемый факт и исходную задачу; впечатления от ответа ИИ остаются вспомогательным сигналом.