Skills — przećwiczone procedury (SKILL.md)

Czym jest skill i kiedy go użyć

Skill to opakowana instrukcja wykonania konkretnego zadania: „przygotuj release”, „przejrzyj migrację bazy”, „wygeneruj PDF-a”. Mechanizm jest oszczędny: model widzi tylko listę dostępnych skilli (ID + opis). Gdy zadanie pasuje do opisu, agent sam wzywa narzędzie skill i doładowuje pełną treść instrukcji do rozmowy.

Dzięki temu nie płacisz tokenami za każdą instrukcję w każdym prompcie (tak jak przy AGENTS.md) — płacisz wtedy, gdy skill realnie wchodzi do gry. AGENTS.md = zasady zawsze; skill = procedura na żądanie.

Struktura skillu

Podstawowa jednostka to plik SKILL.md z frontmatterem YAML i treścią Markdown. Format katalogowy jest zalecany, bo pozwala trzymać obok skrypty, referencje i szablony — ścieżki w treści liczone są od katalogu SKILL.md.

.opencode/skills/
└── git-release/
    ├── SKILL.md              ← definicja (frontmatter + procedura)
    ├── scripts/
    │   └── changelog.ts      ← skrypt wywoływany przez instrukcję
    └── references/
        └── release-policy.md ← doktryna release'ów (wczytywana w krokach)

---
name: Git Release
description: Przygotuj notesy release'owe, bump wersji i release na GitHubie
---

## Procedura

1. Przeczytaj `references/release-policy.md`.
2. Zsumuj zmiany od ostatniego taga (`git log <tag>..HEAD --oneline`).
3. Zaproponuj bump wersji ZANIM cokolwiek zmienisz w plikach.
4. Po mojej akceptacji: uruchom `scripts/changelog.ts`, utwórz tag i
   `gh release create` z wygenerowanymi notesami.

Gdzie OpenCode szuka skilli

Dwa dozwolone kształty plików: markdown leżący bezpośrednio w źródle (skills/review.md) albo katalog z plikiem o dokładnej nazwie SKILL.md (skills/git-release/SKILL.md).

To, że OpenCode skanuje ~/.claude/skills i .agents/skills, oznacza w praktyce: skill'e napisane dla Claude Code czy innych narzędzi zgodnych ze standardem Agent Skills zwykle działają u Ciebie bez zmian — po prostu je tam wrzuć.

Frontmatter — pola, które sterują widocznością

Ładowanie: automatyczne i ręczne

Automatycznie: przy każdym kroku model dostaje listę dozwolonych skilli z opisami; jeśli zadanie pasuje, wzywa narzędzie skill z ID-kiem, OpenCode sprawdza uprawnienia i wstrzykuje treść (bez frontmatteru) plus katalog bazowy i próbkę ścieżek plików wspierających. Zawartość plików wspierających NIE doładowuje się sama — agent czyta je, gdy procedura każe.

Ręcznie: wzmiankuj skill w prompcie jako @git-release albo powiedz wprost „załaduj skill git-release przed zmianą tego kodu”.

@git-release przygotuj wersję 2.4.0 na podstawie merge'y z ostatniego sprintu

Precedencja i kolizje ID

Skill'e rozwiązuje się po ID. Ten sam ID w dwóch źródłach = źródło o wyższym priorytecie wygrywa. Rejestracja od najniższego priorytetu: wbudowane → .claude/skills → .agents/skills → ~/.config/opencode/skills → projektowy .opencode/skills → wpisy z konfiguracji.

~/.config/opencode/skills/git-release/SKILL.md  ← niższy priorytet
.opencode/skills/git-release/SKILL.md           ← TEN zostanie wczytany

Dodatkowe źródła: katalogi i katalogi HTTP

Tablica skills w dowolnym pliku konfiguracyjnym dokłada źródła — lokalne katalogi (względne, ~/ albo absolutne) oraz zdalne katalogi HTTP. Ścieżki względne liczone są od katalogu roboczego OpenCode, a tablice z wielu plików konfiguracyjnych łączą się.

• Pliki pobierane są z <base-url>/<nazwa>/<plik>; ścieżki muszą być relatywne i tego samego pochodzenia (same-origin).
• Zmieniasz pliki — inkrementuj version, inaczej zostaniesz na cache'u.
• W katalogach HTTP preferuj formę <nazwa>.md; korzeniowy SKILL.md dostałby dziś literalne ID SKILL.

{
  "$schema": "https://opencode.ai/config.json",
  "skills": [
    "./team-skills",
    "~/shared/opencode-skills",
    "https://example.com/opencode/skills/"
  ]
}

{
  "skills": [
    {
      "name": "git-release",
      "version": "3",
      "files": ["git-release.md", "references/release-policy.md"]
    }
  ]
}

Uprawnienia do skilli

Akcja uprawnień to skill, zasobem jest ID skilla. Reguły działają last-match-wins: broad najpierw, wyjątki potem. deny nie tylko blokuje ładowanie — skill znika też z listy pokazywanej modelowi.

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

Skill się nie pojawia? Checklista

• Czy plik leży w źródle poprawnej formy: *.md w korzeniu źródła ALBO katalog z plikiem nazwanym dokładnie SKILL.md?
• Testujesz dobre ID? Pochodzi ze ścieżki, jest case-sensitive i nie zawsze równa się frontmatter name.
• Ma description? Bez niego model nigdy nie zobaczy skilla.
• Blokuje go opencode/autoinvoke: false albo reguła skill w permissions?
• Czy późniejsze źródło nie definiuje tego samego ID (nadpisanie)?
• Dla katalogów HTTP: zgadza się index.json, same-origin i podbite version?