Навыки

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

Навыки ZuBrIQ

Те же навыки, что в чате: договоры, таблицы, презентации, PDF, разбор выписок и другие — каталог на zubriq.by/skills.

zubrcode skills list                        # каталог, ✓ — установленные
zubrcode skills add contract-review         # поставить навык (или обновить)
zubrcode skills add --shelf documents       # все навыки полки
zubrcode skills remove contract-review

Навык ставится в ~/.config/zubrcode/skills/ и подхватывается со следующей сессии: агент сам берёт его, когда задача подходит, или по просьбе — «используй навык xlsx». Навыки со скриптами (Word, Excel, PowerPoint, PDF, распознавание сканов) пользуются Python-библиотеками — openpyxl, python-docx, python-pptx, pdfplumber и другими; пересчёт таблиц и превью документов — через LibreOffice. Не хватает библиотеки — агент скажет, какой; в сессиях «Кода» в чате всё это уже стоит.

Свои навыки

Положите SKILL.md в .opencode/skills/<skill-id> и опишите в description, когда навык применять:

.opencode/skills/git-release/SKILL.md

---
name: Git Release
description: Prepare release notes, version bumps, and GitHub releases
---

## Workflow

1. Read `references/release-policy.md`.
2. Summarize merged changes since the previous tag.
3. Propose the version bump before changing files.
4. Run `scripts/changelog.ts` only after the user approves the version.

ZubrCode показывает навык модели, когда он уместен, и загружает инструкции инструментом skill — не все навыки сразу.

Рядом с SKILL.md держите скрипты, шаблоны и справочные файлы:

.opencode/skills/
└── git-release/
    ├── SKILL.md
    ├── scripts/
    │   └── changelog.ts
    └── references/
        └── release-policy.md

Пути внутри навыка считаются относительно каталога с SKILL.md.

Где искать

Источник	Каталоги
Глобальные	~/.config/zubrcode/skills
Совместимость	~/.claude/skills, ~/.agents/skills
Проект	.opencode/skills (от текущей папки до корня проекта)
Совместимость в проекте	.claude/skills, .agents/skills

В каждом источнике может быть и одиночный файл, и каталог:

skills/
├── review.md
└── git-release/
    └── SKILL.md

• Markdown-файлы лежат в корне источника (skills/review.md).
• Файл с точным именем SKILL.md может быть во вложенном каталоге (skills/teams/release/SKILL.md).
• Каталог с SKILL.md — один навык; внутри него другие навыки не ищутся.
• Скрытые файлы, node_modules и глубина больше шести уровней пропускаются.

Дополнительные каталоги и HTTP-каталоги добавляются массивом skills в opencode.json или opencode.jsonc:

{
  "skills": ["./team-skills", "~/shared/skills", "https://example.com/skills/"]
}

HTTP-каталог — это базовый URL с файлом index.json; при изменении файлов навыка увеличивайте его version, чтобы ZubrCode обновил кеш.

Frontmatter и id

Поле	Поведение
name	отображаемое имя; по умолчанию — id из пути
description	краткое описание для модели; без него навык не показывается
metadata.opencode/autoinvoke	false — не предлагать навык модели
disable-model-invocation	то же, что opencode/autoinvoke: false

Id определяется путём файла, а не именем во frontmatter, и чувствителен к регистру: .opencode/skills/release/SKILL.md → id release.

Если два источника определяют один id, загружается поздний: проектные навыки перекрывают глобальные, явные записи skills — всё остальное. Избегайте одинаковых id, если не хотите перекрыть навык.

Загрузка

На каждом шаге модель видит список разрешённых навыков — только id, имя и описание. Навык загружается инструментом skill по точному id; своё направление — упомянуть его в запросе как @skill-id. Содержимое вспомогательных файлов автоматически не читается: агент открывает их по инструкции навыка.

Разрешения

Действие skill, в качестве ресурса — id навыка. Правила применяются по порядку, последнее подходящее побеждает:

{
  "permissions": [
    { "action": "skill", "resource": "*", "effect": "allow" },
    { "action": "skill", "resource": "internal-*", "effect": "deny" },
    { "action": "skill", "resource": "experimental-*", "effect": "ask" }
  ]
}

allow — предлагать и загружать без вопроса, ask — спрашивать перед загрузкой, deny — прятать от модели и не загружать. Те же правила под agents.<имя>.permissions действуют только для одного агента.

Если навык не находится

1. Файл должен быть либо *.md в корне источника, либо вложенным файлом с точным именем SKILL.md.
2. Проверяйте id из пути, а не name из frontmatter; регистр важен.
3. Добавьте description, чтобы модель видела навык.
4. Проверьте opencode/autoinvoke и разрешения skill выбранного агента.
5. Посмотрите, не определяет ли тот же id более поздний источник.