Formát souboru
SKILL.md je text v kódování UTF-8. Začíná řádkem se třemi pomlčkami, pak následuje úvodní blok YAML a uzavírací řádek se třemi pomlčkami. Vše za ním je tělo: pokyny v Markdownu, které zaměstnanec dostane při načtení dovednosti. Nebo soubor najde podle názvu bez ohledu na velikost písmen.
---
name: expense-review
description: Check submitted expenses against the company policy and flag anything that needs a receipt or an approval. Use when someone asks to review expenses or a reimbursement request.
version: "1.2.0"
author: Example Co
license: MIT
tags: [finance, expenses]
triggers: [reimbursement, expense report]
platform: [macos, linux, windows]
capabilities: [network]
metadata:
allowed_domains: [api.example.com]
secrets:
- key: EXAMPLE_API_KEY
label: Example API key
hint: Create one at https://example.com/settings/keys
required: true
requires:
- name: receipt-capture
version: ">=1.0.0"
plugins:
- name: example-ledger
version: ">=2.0.0"
optional: true
---
# Expense review
Follow the policy in references/policy.md ... Pole úvodního bloku
Povinná jsou jen pole name a description. Pole s nesprávným typem znehodnotí celý soubor, takže se dovednost nenačte. Klíče, které zde nejsou uvedeny, se ignorují.
| Pole | Typ | Výchozí | Význam |
|---|---|---|---|
name | string | povinné | Identifikátor. [a-z0-9-], bez pomlčky na začátku a na konci a bez dvojité pomlčky, nejvýše 64 bajtů. Musí odpovídat názvu složky. |
description | string | povinné | Co dovednost dělá a kdy ji použít. Nejvýše 1 024 bajtů. Zobrazuje se v seznamu dovedností zaměstnance a hodnotí ho find_skills. |
version | string | "1.0.0" | Sémantická verze. Kontrolují ji rozsahy requires jiných dovedností. Uveďte ji v uvozovkách. |
triggers | seznam řetězců | [] | Slova a fráze popisující, kdy se dovednost uplatní. Až tři se zobrazí v seznamu dovedností; v find_skills se počítají všechny. Samy dovednost nikdy nenačtou. |
platform | seznam řetězců | všechny | macos, linux, windows. Dovednost se načte jen tam, kde některá hodnota odpovídá. |
capabilities | seznam řetězců | [] | network a storage rozšiřují izolované prostředí skriptu. Viz Izolované prostředí skriptů. |
metadata | map | {} | Obsahuje secrets a allowed_domains. Viz níže. |
requires | seznam {name, version} | [] | Další dovednosti, na kterých tato dovednost staví. name je krátký název dovednosti; version je rozsah semver, výchozí "*". |
plugins | seznam {name, version, optional} | [] | Pluginy, které tato dovednost používá. version má výchozí hodnotu "*", optional hodnotu false. |
dependencies | seznam řetězců | [] | Krátké názvy dovedností, které musí být k dispozici. |
priority | integer | 0 | Určuje pořadí dovedností v seznamech pro správu. Nemá vliv na to, kterou dovednost si zaměstnanec vybere. |
author | string | "" | Ukládá se pro zobrazení. |
license | string | "" | Ukládá se pro zobrazení. |
compatibility | string | "" | Volná poznámka, nejvýše 500 bajtů. |
tags | seznam řetězců | [] | Ukládá se pro zobrazení. |
allowed-tools | string | "" | Řetězec oddělený mezerami. Ukládá se; nevynucuje se. |
Když dovednost uvedená v requires nebo dependencies chybí nebo je mimo rozsah, případně když není nainstalovaný povinný plugin, dovednost se přesto načte a označí jako s omezenou funkčností. Vlastník vidí, co chybí.
Tajné údaje
Přihlašovací údaje, které skripty dovednosti potřebují, deklarujte v metadata.secrets. Hodnoty zadá vlastník a Nebo je pro danou dovednost uloží zašifrované.
metadata:
secrets:
- key: EXAMPLE_API_KEY
label: Example API key
hint: Create one at https://example.com/settings/keys
required: true | Klíč | Význam |
|---|---|
key | Název proměnné prostředí, kterou skript dostane. Povinné. |
label | Název zobrazený vlastníkovi. |
hint | Kde hodnotu získat. |
required | Při true odmítne execute spouštět skripty dovednosti, dokud není hodnota nastavena. Výchozí false. |
Zaměstnanec nastaví hodnotu pomocí configure_skill. Na tajný klíč můžete v těle odkázat jako ${secret.KEY}, skripty by však měly místo toho číst proměnnou prostředí.
Proměnné šablon
Když zaměstnanec načte dovednost, Nebo v těle nahradí tyto proměnné. V jiných souborech se nenahrazují; skripty místo toho čtou proměnné prostředí.
| Proměnná | Hodnota |
|---|---|
${NEBO_SKILL_DIR} | Absolutní cesta ke složce dovednosti. |
${NEBO_DATA_DIR} | Zapisovatelná složka pro tuto dovednost: <data>/appdata/skills/<name>. Vytvoří se při prvním použití. |
${NEBO_USER_NAME} | Jméno vlastníka. |
${NEBO_OS} | Operační systém. |
${NEBO_ARCH} | Architektura procesoru. |
${plugin.SLUG_BIN} | Cesta k binárnímu souboru deklarovaného pluginu. Slug se převede na velká písmena a pomlčky na podtržítka: z example-ledger se stane ${plugin.EXAMPLE_LEDGER_BIN}. |
${secret.KEY} | Hodnota deklarovaného tajného údaje. |
$ARGUMENTS | args předané nástroji use_skill. Když tělo neobsahuje $ARGUMENTS, argumenty se připojí na jeho konec. |
Nástroje pro dovednosti
Zaměstnanci pracují s dovednostmi pomocí těchto nástrojů. use_skill je k dispozici vždy; ostatní se načtou, když je zaměstnanec potřebuje.
| Nástroj | Parametry | Co dělá |
|---|---|---|
use_skill | name, args | Načte dovednost. Vrátí rozvinuté tělo, cestu ke složce a prvních 20 názvů souborů. Znovu povolí vypnutou dovednost. |
find_skills | query | Vrátí až 10 dovedností seřazených podle shody s názvem, spouštěči a popisem. |
read_skill_file | name, path | Přečte soubor ve složce dovednosti. Bez path vypíše soubory a jejich velikosti. |
save_skill | name, content | Zapíše kompletní SKILL.md do uživatelské složky dovedností. Dovednosti z obchodu nelze přepsat. |
delete_skill | name | Smaže uživatelskou dovednost. |
install_skill | code | Nainstaluje dovednost z obchodu podle jejího instalačního kódu SKIL-. |
configure_skill | name, key, value | Nastaví tajný údaj. Bez key ukáže, co dovednost potřebuje. |
rate_skill | name, rating, review | Ohodnotí dovednost z obchodu známkou od 1 do 5. |
read_skill_reviews | name | Načte recenze dovednosti z obchodu. |
execute | skill, script, args, timeout | Spustí skript ze složky dovednosti. Viz Izolované prostředí skriptů. |
Izolované prostředí skriptů
Nástroj execute spustí jeden skript ze složky dovednosti. Běhové prostředí zvolí podle souboru.
| Skript | Běhové prostředí |
|---|---|
.py | Python, přes uv přibalený k Nebo, pokud je k dispozici, jinak python3. |
.ts, .js | Bun přibalený k Nebo, pokud je k dispozici, jinak node. |
bin/<file> nebo binary | Spustí se přímo. |
.sh | Nepodporováno. |
Každé spuštění začíná s prázdným prostředím a těmito proměnnými:
| Proměnná | Hodnota |
|---|---|
SKILL_ARGS | Objekt args jako JSON. |
Každý key tajného údaje | Dešifrovaná hodnota tajného údaje. |
<PLUGIN>_BIN | Cesta k binárnímu souboru každého deklarovaného pluginu. Složky pluginů se také přidají do PATH. |
import json, os
args = json.loads(os.environ.get("SKILL_ARGS", "{}"))
api_key = os.environ["EXAMPLE_API_KEY"]
print(json.dumps({"checked": len(args.get("items", []))})) Skript běží v dočasné kopii složky dovednosti s výchozím časovým limitem 30 sekund. V macOS a Linuxu běží v izolovaném prostředí operačního systému:
- Nemůže číst úložiště přihlašovacích údajů, data prohlížeče a klíčenky ani vlastní nastavení a databázi Nebo.
- Může zapisovat jen do své pracovní složky a do
/tmp/nebo. Schopnoststoragepřidává datovou složku Nebo. - Nemá přístup k síti. Schopnost
networkpovoluje registry balíčků a domény uvedené vmetadata.allowed_domains.
Soubory a limity
| Položka | Pravidlo |
|---|---|
| Zdroje | Všechny soubory kromě SKILL.md, manifest.json, signatures.json a skrytých souborů začínajících tečkou. |
| Spustitelné soubory | Soubory ve složkách scripts/ nebo bin/ a kořenový soubor s názvem binary. |
| Cesty | Relativně ke složce dovednosti. Cesty s .. nebo cesty vedoucí mimo složku se odmítnou. |
| Vypnutá dovednost | Složka se souborem SKILL.md.disabled místo SKILL.md. |
| Seznam dovedností | Každá položka se zkrátí na 250 znaků. Když celý seznam přesáhne 8 000 znaků, zkracují se nejprve sdílené dovednosti; vlastní dovednosti zaměstnance si ponechají celé položky. |
Limity pro soubory, které publikujete do obchodu, najdete na stránce Publikování.