Навыки агентов

Навыки агентов позволяют OpenCode обнаруживать переиспользуемые инструкции из вашего репозитория или домашней директории. Навыки загружаются по требованию через встроенный инструмент skill — агенты видят доступные навыки и могут загрузить полное содержимое при необходимости.

Размещение файлов

Создайте папку для каждого имени навыка и поместите в неё SKILL.md. OpenCode ищет в следующих местах:

• Конфигурация проекта: .opencode/skills/<name>/SKILL.md
• Глобальная конфигурация: ~/.config/opencode/skills/<name>/SKILL.md
• Проект Claude-совместимый: .claude/skills/<name>/SKILL.md
• Глобальный Claude-совместимый: ~/.claude/skills/<name>/SKILL.md
• Проект agent-совместимый: .agents/skills/<name>/SKILL.md
• Глобальный agent-совместимый: ~/.agents/skills/<name>/SKILL.md

Понимание обнаружения

Для локальных путей проекта OpenCode проходит вверх от текущей рабочей директории до корня git worktree. Он загружает все соответствующие skills/*/SKILL.md в .opencode/ и соответствующие .claude/skills/*/SKILL.md или .agents/skills/*/SKILL.md по пути.

Глобальные определения также загружаются из ~/.config/opencode/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md и ~/.agents/skills/*/SKILL.md.

Написание Frontmatter

Каждый SKILL.md должен начинаться с YAML frontmatter. Распознаются только эти поля:

• name (обязательно)
• description (обязательно)
• license (опционально)
• compatibility (опционально)
• metadata (опционально, словарь строка-строка)

Неизвестные поля frontmatter игнорируются.

Валидация имён

name должен:

• Быть от 1 до 64 символов
• Содержать строчные буквы и цифры с одиночными дефисами-разделителями
• Не начинаться и не заканчиваться на -
• Не содержать последовательных --
• Совпадать с именем директории, содержащей SKILL.md

Эквивалентное регулярное выражение:

^[a-z0-9]+(-[a-z0-9]+)*$

Правила длины

description должен быть от 1 до 1024 символов. Делайте его достаточно конкретным, чтобы агент мог правильно выбрать.

Пример использования

Создайте .opencode/skills/git-release/SKILL.md следующим образом:

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---
 
## What I do
 
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command
 
## When to use me
 
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

Распознавание описания инструмента

OpenCode перечисляет доступные навыки в описании инструмента skill. Каждая запись включает имя навыка и описание:

<available_skills>
<skill>
  <name>git-release</name>
  <description>Create consistent releases and changelogs</description>
</skill>
</available_skills>

Агент загружает навык, вызывая инструмент:

skill({ name: "git-release" })

Настройка разрешений

Управляйте доступом агентов к навыкам с помощью разрешений на основе шаблонов в opencode.json:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

Шаблоны поддерживают подстановочные знаки: internal-* соответствует internal-docs, internal-tools и т.д.

Переопределение для агента

Дайте конкретным агентам разрешения, отличные от глобальных значений по умолчанию.

Для пользовательских агентов (в frontmatter агента):

---
permission:
  skill:
    "documents-*": "allow"
---

Для встроенных агентов (в opencode.json):

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

Отключение инструмента навыков

Полностью отключите навыки для агентов, которые не должны их использовать:

Для пользовательских агентов:

---
tools:
  skill: false
---

Для встроенных агентов:

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

При отключении раздел <available_skills> полностью опускается.

Устранение проблем загрузки

Если навык не отображается:

• Убедитесь, что SKILL.md написан заглавными буквами
• Проверьте, что frontmatter включает name и description
• Убедитесь, что имена навыков уникальны во всех местах
• Проверьте разрешения — навыки с deny скрыты от агентов