Создание вашего первого навыка

Что вы сможете делать после прохождения

После завершения этого руководства вы сможете:

• Создавать структуру каталогов навыков в соответствии со спецификацией
• Правильно составлять Frontmatter для SKILL.md
• Понимать компоненты навыка
• Позволить OpenCode автоматически обнаруживать и загружать ваш навык
• Проверять работоспособность навыка

Ваша текущая проблема

Возможно, вы столкнулись со следующими ситуациями:

• Хотите создать специализированный навык для проекта, но не знаете, с чего начать
• Попытались написать SKILL.md, но плагин не может его найти
• Навык был обнаружен, но при загрузке возникла ошибка «Ошибка парсинга YAML»
• Не уверены, какие поля нужно заполнить в Frontmatter

Все эти проблемы возникают из-за незнания структурных спецификаций навыка. OpenCode Agent Skills следует спецификации Anthropic Agent Skills и имеет фиксированные требования к формату.

Когда применять

Создание навыка подходит для следующих сценариев:

• Специфичные рабочие процессы проекта: код-ревью, процессы развёртывания для конкретного проекта
• Командные стандарты: единые стандарты коммитов, проверка стиля кода
• Интеграция инструментов: интеграция часто используемых CLI-инструментов (git, docker)
• Накопление знаний: документирование часто используемых шагов для вызова ИИ

🎒 Подготовка перед началом

Перед началом убедитесь в следующем:

Предварительная проверка

• ✅ Установлен плагин OpenCode Agent Skills (см. руководство по установке)
• ✅ Знакомы с базовыми операциями командной строки (mkdir, cd, ls)
• ✅ Есть каталог проекта для размещения навыков

Ключевая концепция

Навык OpenCode Agent Skills представляет собой каталог, который обязательно должен содержать файл SKILL.md. Этот файл состоит из двух частей:

1. YAML Frontmatter: метаданные навыка (название, описание и т.д.)
2. Markdown-контент: руководство, которому следует ИИ при выполнении

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

1. .opencode/skills/              (проектный - OpenCode)
2. .claude/skills/                (проектный - Claude Code)
3. ~/.config/opencode/skills/     (пользовательский - OpenCode)
4. ~/.claude/skills/              (пользовательский - Claude Code)
5. ~/.claude/plugins/cache/        (кеш плагина)
6. ~/.claude/plugins/marketplaces/ (установленные плагины)

Навык с одинаковым названием, который соответствует первым, имеет приоритет.

Следуйте инструкции: создание первого навыка

Мы создадим простой навык «hello-world» для демонстрации базовой структуры.

Шаг 1: Создание каталога навыка

Зачем Навык должен находиться в специальном каталоге, чтобы плагин мог его автоматически обнаружить.

Действие

# Создание каталога навыков в корне проекта
mkdir -p .opencode/skills/hello-world

Результат:

Корень проекта/
└── .opencode/
    └── skills/
        └── hello-world/

Шаг 2: Написание SKILL.md

Зачем SKILL.md — это основной файл навыка, содержащий метаданные и руководство.

Действие

Запишите в .opencode/skills/hello-world/SKILL.md:

---
name: hello-world
description: A simple greeting skill for demonstration
---

# Hello World Skill

This is a demonstration skill that shows how to create a basic skill.

## Usage

Use this skill when you need to greet users or demonstrate skill functionality.

## Example

When asked "Say hello to the user", respond with a friendly greeting.

Результат:

.opencode/skills/hello-world/
└── SKILL.md

Шаг 3: Проверка обнаружения навыка

Зачем Убедиться, что формат Frontmatter корректен и плагин может правильно его распознать.

Действие

Спросите в OpenCode:

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

Результат: В списке навыков, возвращаемом плагином, должно присутствовать hello-world.

Или вызовите инструмент напрямую:

get_available_skills()

Ожидаемый вывод:

Available skills:
- hello-world: A simple greeting skill for demonstration

Шаг 4: Загрузка и тестирование навыка

Зачем Проверить, что содержимое навыка правильно внедряется в контекст сессии.

Действие

В OpenCode:

Загрузи навык hello-world

Результат:

Skill 'hello-world' loaded successfully.

Available scripts: (none)
Available files: (none)

Содержимое SKILL.md внедрено в контекст.

Шаг 5: Проверка работоспособности навыка

Зачем Убедиться, что ИИ понимает и следует руководству навыка.

Действие

Спросите ИИ:

Поприветствуй меня согласно навыку hello-world

Результат: ИИ выводит приветствие в соответствии с содержимым навыка.

Контрольные точки ✅

После выполнения вышеуказанных шагов проверьте следующие пункты:

• [ ] Файл .opencode/skills/hello-world/SKILL.md существует
• [ ] get_available_skills() перечисляет навык hello-world
• [ ] use_skill("hello-world") успешно загружается, ошибок нет
• [ ] ИИ понимает и следует содержимому навыка

Если какой-либо пункт не выполнен, обратитесь к разделу «提醒» ниже.

##提醒

Навык не найден?

Ошибка	Возможная причина	Решение
Плагин не находит навык	Неправильное имя каталога или файла	Убедитесь, что имя файла — SKILL.md (все буквы заглавные)
Плагин не навык	Ошибка формата Frontmatter	Проверьте наличие --- и пустых строк до и после
Плагин не находит навык	Поле name не соответствует спецификации	name должно содержать только строчные буквы, цифры и дефисы

Ошибка парсинга?

Ошибка	Возможная причина	Решение
Ошибка парсинга YAML	Неправильный формат Frontmatter	Используйте корректный формат YAML, строки в кавычках
Ошибка валидации	name содержит заглавные буквы или спецсимволы	Поле name только строчные буквы, цифры, дефисы
Ошибка валидации	description пустое	description обязательно должно иметь значение

Примеры частых ошибок

# ❌ Ошибка: name содержит заглавные буквы
---
name: HelloWorld
description: A skill
---

# ❌ Ошибка: name содержит пробелы
---
name: hello world
description: A skill
---

# ❌ Ошибка: name содержит спецсимволы (кроме дефиса)
---
name: hello_world
description: A skill
---

# ✅ Правильно
---
name: hello-world
description: A skill for demonstration
---

Обязательность полей Frontmatter

Поле	Обязательно	Ограничение	Пример
name	✅ Да	Строчные буквы, цифры, дефисы	my-skill
description	✅ Да	Непустая строка	A skill for git management
license	❌ Нет	Название лицензии	MIT
allowed-tools	❌ Нет	Массив названий инструментов	["read", "write"]
metadata	❌ Нет	Объект key-value	{"namespace": "project"}

Итоги урока

В этом руководстве мы рассмотрели:

1. Структура каталога навыка: .opencode/skills/<skill-name>/SKILL.md
2. Формат Frontmatter: YAML-формат с обязательными полями name и description
3. Правила обнаружения навыков: автоматическое обнаружение из 6 расположений по приоритету
4. Процесс загрузки навыков: загрузка содержимого в контекст через инструмент use_skill

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

Анонс следующего урока

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

Вы узнаете:

• 6 расположений для обнаружения навыков и правила приоритета
• Логику дедупликации одноимённых навыков
• Механизм совместимости с навыками Claude Code
• Как узнать источник и пространство имён навыка

---

Приложение: Ссылка на исходный код

Нажмите, чтобы увидеть расположение исходного кода

Время обновления: 2026-01-24

Функция	Путь к файлу	Номера строк
Определение схемы Frontmatter	src/skills.ts	105-114
Парсинг файла SKILL.md	src/skills.ts	122-167
Поиск скриптов навыка	src/skills.ts	59-99
Список приоритетов обнаружения навыков	src/skills.ts	241-246
Парсинг YAML Frontmatter	src/utils.ts	41-49

Ключевые константы:

• Максимальная глубина рекурсии для скриптов: maxDepth = 10
• Пропускаемые каталоги: node_modules, __pycache__, .git, .venv, venv, .tox, .nox

Ключевые функции:

• parseSkillFile(): парсинг файла SKILL.md, валидация Frontmatter и извлечение метаданных
• findScripts(): рекурсивный поиск исполняемых скриптов в каталоге навыка
• discoverAllSkills(): обнаружение всех навыков из нескольких расположений