223 lines
4.9 KiB
Plaintext
223 lines
4.9 KiB
Plaintext
---
|
||
title: "Agent Skills"
|
||
description: "Define reusable behavior via SKILL.md definitions"
|
||
---
|
||
|
||
Umiejętności agenta pozwalają OpenCode odkryć instrukcje wielokrotnego użytku z repozytorium lub katalogu domowego.
|
||
Umiejętności są ładowane na żądanie za pośrednictwem natywnego narzędzia `skill` — agenci widzą dostępne umiejętności i w razie potrzeby mogą załadować pełną zawartość.
|
||
|
||
---
|
||
|
||
## Place files
|
||
|
||
Utwórz jeden folder na nazwę umiejętności i umieść w nim `SKILL.md`.
|
||
OpenCode searches these locations:
|
||
|
||
- Project config: `.opencode/skills/<name>/SKILL.md`
|
||
- Global config: `~/.config/opencode/skills/<name>/SKILL.md`
|
||
- Project Claude-compatible: `.claude/skills/<name>/SKILL.md`
|
||
- Global Claude-compatible: `~/.claude/skills/<name>/SKILL.md`
|
||
- Project agent-compatible: `.agents/skills/<name>/SKILL.md`
|
||
- Global agent-compatible: `~/.agents/skills/<name>/SKILL.md`
|
||
|
||
---
|
||
|
||
## Understand discovery
|
||
|
||
W przypadku ścieżek lokalnych projektu OpenCode przechodzi od bieżącego katalogu roboczego, aż dotrze do drzewa roboczego git.
|
||
Ładuje po drodze dowolne pasujące `skills/*/SKILL.md` w `.opencode/` i dowolne pasujące `.claude/skills/*/SKILL.md` lub `.agents/skills/*/SKILL.md`.
|
||
|
||
Ładowane są także definicje globalne z `~/.config/opencode/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md` i `~/.agents/skills/*/SKILL.md`.
|
||
|
||
---
|
||
|
||
## Write frontmatter
|
||
|
||
Każdy `SKILL.md` musi zaczynać się od treści YAML.
|
||
Only these fields are recognized:
|
||
|
||
- `name` (required)
|
||
- `description` (required)
|
||
- `license` (optional)
|
||
- `compatibility` (optional)
|
||
- `metadata` (optional, string-to-string map)
|
||
|
||
Unknown frontmatter fields are ignored.
|
||
|
||
---
|
||
|
||
## Validate names
|
||
|
||
`name` must:
|
||
|
||
- Be 1–64 characters
|
||
- Należy używać małych liter alfanumerycznych i oddzielać je pojedynczym łącznikiem
|
||
- Nie zaczyna się ani nie kończy na `-`
|
||
- Not contain consecutive `--`
|
||
- Dopasuj nazwę katalogu zawierającą `SKILL.md`
|
||
|
||
Equivalent regex:
|
||
|
||
```text
|
||
^[a-z0-9]+(-[a-z0-9]+)*$
|
||
```
|
||
|
||
---
|
||
|
||
## Follow length rules
|
||
|
||
`description` must be 1-1024 characters.
|
||
Zadbaj o to, aby agent mógł dokonać prawidłowego wyboru.
|
||
|
||
---
|
||
|
||
## Skorzystaj z przykładu
|
||
|
||
Utwórz `.opencode/skills/git-release/SKILL.md` w ten sposób:
|
||
|
||
```markdown
|
||
---
|
||
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.
|
||
```
|
||
|
||
---
|
||
|
||
## Recognize tool description
|
||
|
||
OpenCode wymienia dostępne umiejętności w opisie narzędzia `skill`.
|
||
Każdy wpis zawiera nazwę i opis umiejętności:
|
||
|
||
```xml
|
||
<available_skills>
|
||
<skill>
|
||
<name>git-release</name>
|
||
<description>Create consistent releases and changelogs</description>
|
||
</skill>
|
||
</available_skills>
|
||
```
|
||
|
||
Agent ładuje umiejętność wywołując narzędzie:
|
||
|
||
```
|
||
skill({ name: "git-release" })
|
||
```
|
||
|
||
---
|
||
|
||
## Skonfiguruj uprawnienia
|
||
|
||
Control which skills agents can access using pattern-based permissions in `opencode.json`:
|
||
|
||
```json
|
||
{
|
||
"permission": {
|
||
"skill": {
|
||
"*": "allow",
|
||
"pr-review": "allow",
|
||
"internal-*": "deny",
|
||
"experimental-*": "ask"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| Permission | Behavior |
|
||
| ---------- | ----------------------------------------- |
|
||
| `allow` | Skill loads immediately |
|
||
| `deny` | Skill hidden from agent, access rejected |
|
||
| `ask` | Użytkownik proszony o zatwierdzenie przed załadowaniem |
|
||
|
||
Wzorce obsługują symbole wieloznaczne: `internal-*` odpowiada `internal-docs`, `internal-tools` itd.
|
||
|
||
---
|
||
|
||
## Override per agent
|
||
|
||
Nadaj konkretnym agentom inne uprawnienia niż globalne ustawienia domyślne.
|
||
|
||
**Dla agentów niestandardowych** (w temacie agentów):
|
||
|
||
```yaml
|
||
---
|
||
permission:
|
||
skill:
|
||
"documents-*": "allow"
|
||
---
|
||
```
|
||
|
||
**Dla agentów wbudowanych** (w `opencode.json`):
|
||
|
||
```json
|
||
{
|
||
"agent": {
|
||
"plan": {
|
||
"permission": {
|
||
"skill": {
|
||
"internal-*": "allow"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Wyłącz narzędzie umiejętności
|
||
|
||
Całkowicie wyłącz umiejętności agentów, którzy nie powinni ich używać:
|
||
|
||
**Dla agentów celnych**:
|
||
|
||
```yaml
|
||
---
|
||
tools:
|
||
skill: false
|
||
---
|
||
```
|
||
|
||
**W przypadku agentów wbudowanych**:
|
||
|
||
```json
|
||
{
|
||
"agent": {
|
||
"plan": {
|
||
"tools": {
|
||
"skill": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Jeśli opcja jest wyłączona, sekcja `<available_skills>` jest całkowicie pomijana.
|
||
|
||
---
|
||
|
||
## Troubleshoot loading
|
||
|
||
Jeśli umiejętność nie pojawi się:
|
||
|
||
1. Verify `SKILL.md` is spelled in all caps
|
||
2. Sprawdź, czy frontmatter zawiera `name` i `description`
|
||
3. Ensure skill names are unique across all locations
|
||
4. Sprawdź uprawnienia — umiejętności z `deny` są ukryte przed agentami
|