Навыки OpenCode

В OpenCode,Agent Skills— это механизм инкапсуляции переиспользуемых поведений, черезSKILL.mdопределённые в файлах, позволяя LLMзагружать по требованию и выполнять по требованиюконкретные возможности.

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

Skills — этосистема плагинов возможностейв OpenCode, которая переводит поведение ИИ с разовых промптов на переиспользуемые модули возможностей, делая рабочие процессы разработки более стандартизированными, компонуемыми и применимыми к сложным инженерным системам.

Skills существуют в виде Markdown-файлов. Они не выполняют функциональность; вместо этого за счёт загрузки по требованию и прогрессивного раскрытия они обеспечивают эффективную и переиспользуемую передачу знаний.

Самое большое отличие Skills от традиционных промптов: загрузка по требованию + прогрессивное раскрытие (только при необходимости объёмный SOP помещается в контекст, что значительно экономит токены).

Основной механизм

Навыки используют встроенныйskillинструмент для управления; рабочий процесс выглядит следующим образом:

1. Сканирование локальных и глобальных директорий навыков
2. Отображение списка доступных навыков в контексте
3. Агент автоматически выбирает навыки на основе задачи
4. Загрузка содержимого SKILL.md по требованию

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

Основная структура навыка

В основе навыков лежит:Папка + файл SKILL.md。

Файл SKILL.md содержит:

• Метаданные (как минимум имя и описание)
• Инструкции, которые объясняют ИИ, как выполнить конкретную задачу

Навык — это по сути файл Markdown (имя файла зафиксировано как SKILL.md)

my-skill/
└── SKILL.md   （唯一必需）

Базовый шаблон SKILL.md:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
---

# PDF 处理

## 使用场景
当需要对 PDF 文件进行操作时使用，例如：

- 提取 PDF 文本或表格数据
- 填写 PDF 表单
- 合并多个 PDF 文件

## 提取文本
- 使用 `pdfplumber` 提取文本型 PDF 内容  
- 扫描版 PDF 需配合 OCR 工具  

## 填写表单
- 读取 PDF 表单字段  
- 按输入数据填充并生成新文件  

Минимальный обязательный пример:

---
name: skill-name
description: 说明该 Skill 的功能以及适用场景
---

Пример с необязательными полями:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Если вам нужны справочные материалы, справочные примеры или скрипты выполнения, вы можете использовать более сложную структуру каталога Skill:

my-skill/
├── SKILL.md      # 必需：指令 + 元数据
├── scripts/      # 可选：可执行代码
├── references/   # 可选：文档资料
└── assets/       # 可选：模板、资源

Как работают навыки

Навыки используют прогрессивную загрузку для эффективного управления контекстом:

• Обнаружение:При запуске ИИ загружает только имя и описание каждого навыка, сохраняя лишь самую базовую идентификационную информацию.
• Активация:Когда задача соответствует описанию навыка, ИИ считывает полные инструкции SKILL.md в контекст.
• Выполнение:ИИ выполняет инструкции, загружая справочные файлы или запуская код по мере необходимости.

Такая конструкция сохраняет скорость ИИ и позволяет ему получать больше информации по требованию.

Места размещения файлов

Каждому навыку требуется собственная папка, и внутри папки вы размещаетеSKILL.mdфайл (примечание: имя файла должно быть полностью заглавными буквами). OpenCode автоматически ищет следующие шесть расположений:

Типичная структура каталогов проекта выглядит следующим образом:

your-repo/
├── .opencode/
│   └── skills/
│       ├── git-release/
│       │   └── SKILL.md      ← 发版流程技能
│       ├── code-review/
│       │   └── SKILL.md      ← 代码审查技能
│       └── api-doc/
│           └── SKILL.md      ← API 文档编写技能
├── src/
└── package.json

Механизм обнаружения

Обнаружение навыков в OpenCode разделено на два уровня:

• Локальные навыки проекта:OpenCode начинает с текущего рабочего каталога,проходит по дереву каталогов вверх уровень за уровнем, пока не достигнет корня рабочего дерева Git. В этом процессе он собирает с каждого уровня каталогов по пути.opencode/skills/*/SKILL.md、.claude/skills/*/SKILL.md、.agents/skills/*/SKILL.mdвсе соответствующие файлы навыков.

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

Навыки с обоих уровней объединяются и предоставляются агенту. Если локальный навык проекта имеет то же имя, что и глобальный навык,локальные навыки проекта имеют приоритет。

Написание SKILL.md

1. Поля frontmatter

КаждыйSKILL.mdфайл должен начинаться с YAML frontmatter (т.е.---заключённая часть). OpenCode распознаёт только следующие поля; неизвестные поля автоматически игнорируются:

2. Правила именования

nameЗначение поля должно одновременно удовлетворять всем следующим условиям; иначе навык не может быть загружен:

• Длина составляет1–64 символов
• Может содержать толькострочные буквыицифры, слова могут использовать один дефис (-) в качестве разделителя.
• Не должен-начинаться или заканчиваться на
• Не должен содержать подряд идущие--
• Должен соответствовать содержащемуSKILL.mdизимени папки точно.

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

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

Примеры допустимых имён:git-release、api-doc、code-review、deploy2prod

Примеры недопустимого именования:Git-Release(содержит заглавные буквы),-release(с-в начале),git--release(Continuous--）

3. Написание описания

descriptionСодержимое поля напрямую влияет на то, сможет ли агент правильно выбрать и вызвать навык.Рекомендуется, чтобы описание было конкретным и ясным, объясняющим, что делает навык и в каких сценариях он используется, избегая чрезмерно общих описаний:

• ❌ Слишком общо:Help complete the release task.
• ✅ Конкретно и ясно:从合并的 PR 中起草发版说明、提出版本号建议，并生成可直接使用的 gh release create 命令

4. Полный пример

Создайте в проекте.opencode/skills/git-release/SKILL.md, со следующим содержимым:

В Frontmatternameзначение должно соответствовать имени папки. В этом примере имя папки —git-release, поэтомуnameоно также должно быть записано какgit-release, иначе навык не может быть распознан.

Как агенты обнаруживают и загружают навыки

После запуска OpenCode он внедряет все доступные на данный момент навыки в формате XML вskillописание инструмента. Агенты могут узнать, какие навыки доступны, просмотрев описание инструмента:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
  <skill>
    <name>code-review</name>
    <description>Perform structured code reviews with consistent criteria</description>
  </skill>
</available_skills>

Когда агент определяет, что навык релевантен текущей задаче, он проактивно вызываетskillинструмент для загрузки полногоSKILL.mdcontent:

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

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

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

Вopencode.jsonВ, используйтеpermission.skillПоле управляет тем, к каким навыкам агент может получить доступ, и поддерживает два метода сопоставления: точные имена и подстановочные знаки Glob:

Конкретные эффекты трёх действий разрешений на навыки следующие:

Переопределение разрешений для каждого агента

Разным агентам может потребоваться доступ к разным наборам навыков. Вы можете настроить разрешения отдельно для каждого агента, переопределив глобальные значения по умолчанию.

1. Настройка в frontmatter пользовательского агента

# 文件路径：~/.config/opencode/agents/my-agent.md
---
permission:
  skill:
    "documents-*": "allow"    # 该代理可以加载所有 documents- 开头的技能
                               # 其他技能遵循全局权限配置
---
 
You are a documentation assistant.

2. Настройка для встроенных агентов в opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {                          // 内置代理名称
      "permission": {
        "skill": {
          "internal-*": "allow"        // plan 代理可以加载 internal- 开头的技能，
                                       // 即使全局配置中对其设置了 deny
        }
      }
    }
  }
}

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

Для агентов, которым совсем не нужно использовать навыки, можно напрямую отключитьskillинструмент. После его отключения,<available_skills>список будет полностью удалён из контекста агента, что сократит потребление токенов и предотвратит попытки агента загружать какие-либо навыки.

1. Отключение в Frontmatter пользовательского агента

2. Отключение для встроенных агентов в opencode.json

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

Если навык не появляется в списке доступных, проверьте следующие пункты по порядку:

1. Проверьте регистр имени файла

   SKILL.mdИмя файла должно быть написано только заглавными буквами; если написать какskill.mdилиSkill.mdоно не будет распознано.

2. Проверьте полноту Frontmatter

   УбедитесьSKILL.mdон начинается с корректного YAML frontmatter и содержитnameиdescriptionдва обязательных поля. Если хотя бы одно из них отсутствует, навык не будет загружен.

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

   Если навыки с одинаковым именем существуют в разных путях, могут возникнуть конфликты. Также проверьтеnameсоответствует ли поле правилам именования (только строчные буквы и цифры, разделённые дефисами) и точно ли совпадает с именем папки.

4. Проверьте конфигурацию разрешений

   Вopencode.jsonизpermission.skillВ, если разрешение —"deny"Навык будет полностью скрыт от агента и не появится в<available_skills>списке. Проверьте, нет ли каких-либо правил с подстановочными знаками (таких как"*": "deny") случайно этот навык.

Для получения дополнительных навыков см.:

• Руководство по навыкам:https://www.example.com/ai-agent/skills-agent.html