NeboAI
NeboAI
Začít

Reference SKILL.md

Tato stránka uvádí každou část dovednosti, kterou Nebo čte: pole úvodního bloku, proměnné, které rozvíjí, nástroje, kterými zaměstnanci s dovednostmi pracují, a prostředí, ve kterém běží skripty.

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í.

PoleTypVýchozíVýznam
namestringpovinné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.
descriptionstringpovinné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.
versionstring"1.0.0"Sémantická verze. Kontrolují ji rozsahy requires jiných dovedností. Uveďte ji v uvozovkách.
triggersseznam ř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.
platformseznam řetězcůvšechnymacos, linux, windows. Dovednost se načte jen tam, kde některá hodnota odpovídá.
capabilitiesseznam řetězců[]network a storage rozšiřují izolované prostředí skriptu. Viz Izolované prostředí skriptů.
metadatamap{}Obsahuje secrets a allowed_domains. Viz níže.
requiresseznam {name, version}[]Další dovednosti, na kterých tato dovednost staví. name je krátký název dovednosti; version je rozsah semver, výchozí "*".
pluginsseznam {name, version, optional}[]Pluginy, které tato dovednost používá. version má výchozí hodnotu "*", optional hodnotu false.
dependenciesseznam řetězců[]Krátké názvy dovedností, které musí být k dispozici.
priorityinteger0Určuje pořadí dovedností v seznamech pro správu. Nemá vliv na to, kterou dovednost si zaměstnanec vybere.
authorstring""Ukládá se pro zobrazení.
licensestring""Ukládá se pro zobrazení.
compatibilitystring""Volná poznámka, nejvýše 500 bajtů.
tagsseznam řetězců[]Ukládá se pro zobrazení.
allowed-toolsstring""Ř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
keyNázev proměnné prostředí, kterou skript dostane. Povinné.
labelNázev zobrazený vlastníkovi.
hintKde hodnotu získat.
requiredPř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.
$ARGUMENTSargs 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ástrojParametryCo dělá
use_skillname, argsNačte dovednost. Vrátí rozvinuté tělo, cestu ke složce a prvních 20 názvů souborů. Znovu povolí vypnutou dovednost.
find_skillsqueryVrátí až 10 dovedností seřazených podle shody s názvem, spouštěči a popisem.
read_skill_filename, pathPřečte soubor ve složce dovednosti. Bez path vypíše soubory a jejich velikosti.
save_skillname, contentZapíše kompletní SKILL.md do uživatelské složky dovedností. Dovednosti z obchodu nelze přepsat.
delete_skillnameSmaže uživatelskou dovednost.
install_skillcodeNainstaluje dovednost z obchodu podle jejího instalačního kódu SKIL-.
configure_skillname, key, valueNastaví tajný údaj. Bez key ukáže, co dovednost potřebuje.
rate_skillname, rating, reviewOhodnotí dovednost z obchodu známkou od 1 do 5.
read_skill_reviewsnameNačte recenze dovednosti z obchodu.
executeskill, script, args, timeoutSpustí 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.

SkriptBěhové prostředí
.pyPython, přes uv přibalený k Nebo, pokud je k dispozici, jinak python3.
.ts, .jsBun přibalený k Nebo, pokud je k dispozici, jinak node.
bin/<file> nebo binarySpustí se přímo.
.shNepodporová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_ARGSObjekt args jako JSON.
Každý key tajného údajeDešifrovaná hodnota tajného údaje.
<PLUGIN>_BINCesta 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. Schopnost storage přidává datovou složku Nebo.
  • Nemá přístup k síti. Schopnost network povoluje registry balíčků a domény uvedené v metadata.allowed_domains.

Soubory a limity

PoložkaPravidlo
ZdrojeVšechny soubory kromě SKILL.md, manifest.json, signatures.json a skrytých souborů začínajících tečkou.
Spustitelné souborySoubory ve složkách scripts/ nebo bin/ a kořenový soubor s názvem binary.
CestyRelativně ke složce dovednosti. Cesty s .. nebo cesty vedoucí mimo složku se odmítnou.
Vypnutá dovednostSlož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í.