NeboAI
NeboAI
Zacznij

Dokumentacja SKILL.md

Ta strona wymienia każdą część umiejętności, którą odczytuje Nebo: pola nagłówka, zmienne, które rozwija, narzędzia, za pomocą których pracownicy korzystają z umiejętności, i środowisko, w którym działają skrypty.

Format pliku

SKILL.md to tekst w UTF-8. Zaczyna się od wiersza z trzema łącznikami, potem jest nagłówek YAML (frontmatter), a następnie wiersz zamykający z trzema łącznikami. Wszystko dalej to treść: instrukcje w Markdown, które pracownik otrzymuje po załadowaniu umiejętności. Nebo znajduje plik po nazwie bez względu na wielkość liter.

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

Pola nagłówka

Wymagane są tylko name i description. Pole o niewłaściwym typie unieważnia cały plik, więc umiejętność się nie ładuje. Klucze niewymienione tutaj są ignorowane.

PoleTypDomyślnieZnaczenie
namestringwymaganeIdentyfikator. [a-z0-9-], bez łącznika na początku, na końcu ani podwójnego, maksymalnie 64 bajty. Musi odpowiadać nazwie folderu.
descriptionstringwymaganeCo umiejętność robi i kiedy jej używać. Maksymalnie 1024 bajty. Wyświetlane na liście umiejętności pracownika i oceniane przez find_skills.
versionstring"1.0.0"Wersja semantyczna. Sprawdzana przez zakresy requires innych umiejętności. Ujmij ją w cudzysłów.
triggerslista ciągów znaków[]Słowa i wyrażenia opisujące, kiedy umiejętność ma zastosowanie. Maksymalnie trzy pojawiają się na liście umiejętności; wszystkie liczą się w find_skills. Nigdy same nie ładują umiejętności.
platformlista ciągów znakówwszystkiemacos, linux, windows. Umiejętność ładuje się tylko tam, gdzie któryś pasuje.
capabilitieslista ciągów znaków[]network i storage poszerzają piaskownicę skryptów. Zobacz Piaskownica skryptów.
metadatamap{}Zawiera secrets i allowed_domains. Zobacz niżej.
requireslista {name, version}[]Inne umiejętności, na których opiera się ta umiejętność. name to krótka nazwa umiejętności; version to zakres semver, domyślnie "*".
pluginslista {name, version, optional}[]Wtyczki, z których korzysta ta umiejętność. version domyślnie ma wartość "*", optional — false.
dependencieslista ciągów znaków[]Krótkie nazwy umiejętności, które muszą być obecne.
priorityinteger0Ustala kolejność umiejętności na listach zarządzania. Nie wpływa na to, którą umiejętność wybierze pracownik.
authorstring""Zapisywane do wyświetlania.
licensestring""Zapisywane do wyświetlania.
compatibilitystring""Dowolna notatka, maksymalnie 500 bajtów.
tagslista ciągów znaków[]Zapisywane do wyświetlania.
allowed-toolsstring""Ciąg znaków rozdzielany spacjami. Zapisywany; nie jest egzekwowany.

Gdy brakuje umiejętności wymienionej w requires lub dependencies albo jest ona poza zakresem, lub gdy wymagana wtyczka nie jest zainstalowana, umiejętność i tak się ładuje i zostaje oznaczona jako ograniczona. Właściciel widzi, czego brakuje.

Sekrety

Zadeklaruj dane logowania potrzebne skryptom umiejętności w metadata.secrets. Właściciel podaje wartości, a Nebo przechowuje je zaszyfrowane dla tej umiejętności.

metadata:
  secrets:
    - key: EXAMPLE_API_KEY
      label: Example API key
      hint: Create one at https://example.com/settings/keys
      required: true
KluczZnaczenie
keyNazwa zmiennej środowiskowej, którą otrzymuje skrypt. Wymagane.
labelNazwa wyświetlana właścicielowi.
hintSkąd wziąć wartość.
requiredGdy true, execute odmawia uruchomienia skryptów umiejętności, dopóki wartość nie zostanie ustawiona. Domyślnie false.

Pracownik ustawia wartość za pomocą configure_skill. W treści możesz odwołać się do sekretu jako ${secret.KEY}, choć skrypty powinny zamiast tego odczytywać zmienną środowiskową.

Zmienne szablonu

Nebo zastępuje te zmienne w treści, gdy pracownik ładuje umiejętność. Nie są zastępowane w innych plikach; skrypty odczytują zamiast tego zmienne środowiskowe.

ZmiennaWartość
${NEBO_SKILL_DIR}Ścieżka bezwzględna folderu umiejętności.
${NEBO_DATA_DIR}Folder z prawem zapisu dla tej umiejętności: <data>/appdata/skills/<name>. Tworzony przy pierwszym użyciu.
${NEBO_USER_NAME}Imię i nazwisko właściciela.
${NEBO_OS}System operacyjny.
${NEBO_ARCH}Architektura procesora.
${plugin.SLUG_BIN}Ścieżka pliku binarnego zadeklarowanej wtyczki. Slug jest zapisany wielkimi literami, z łącznikami zamienionymi na podkreślenia: example-ledger staje się ${plugin.EXAMPLE_LEDGER_BIN}.
${secret.KEY}Wartość zadeklarowanego sekretu.
$ARGUMENTSargs przekazane do use_skill. Gdy treść nie zawiera $ARGUMENTS, argumenty są dopisywane na jej końcu.

Narzędzia umiejętności

Pracownicy korzystają z umiejętności za pomocą tych narzędzi. use_skill jest zawsze dostępne; pozostałe ładują się, gdy pracownik ich potrzebuje.

NarzędzieParametryDziałanie
use_skillname, argsŁaduje umiejętność. Zwraca rozwiniętą treść, ścieżkę folderu i pierwsze 20 nazw plików. Ponownie włącza wyłączoną umiejętność.
find_skillsqueryZwraca maksymalnie 10 umiejętności uszeregowanych według dopasowania nazwy, wyzwalaczy i opisu.
read_skill_filename, pathOdczytuje plik w folderze umiejętności. Bez path wyświetla listę plików i ich rozmiary.
save_skillname, contentZapisuje kompletny plik SKILL.md w folderze umiejętności użytkownika. Umiejętności ze sklepu nie można nadpisać.
delete_skillnameUsuwa umiejętność użytkownika.
install_skillcodeInstaluje umiejętność ze sklepu za pomocą jej kodu instalacyjnego SKIL-.
configure_skillname, key, valueUstawia sekret. Bez key pokazuje, czego potrzebuje umiejętność.
rate_skillname, rating, reviewOcenia umiejętność ze sklepu w skali od 1 do 5.
read_skill_reviewsnameOdczytuje recenzje umiejętności ze sklepu.
executeskill, script, args, timeoutUruchamia skrypt z folderu umiejętności. Zobacz Piaskownica skryptów.

Piaskownica skryptów

Narzędzie execute uruchamia jeden skrypt z folderu umiejętności. Środowisko wykonawcze wybiera na podstawie pliku.

SkryptŚrodowisko wykonawcze
.pyPython, przez dołączony do Nebo uv, jeśli jest dostępny, w przeciwnym razie python3.
.ts, .jsDołączony do Nebo Bun, jeśli jest dostępny, w przeciwnym razie node.
bin/<file> lub binaryUruchamiane bezpośrednio.
.shNieobsługiwane.

Każde uruchomienie zaczyna się z pustym środowiskiem i tymi zmiennymi:

ZmiennaWartość
SKILL_ARGSObiekt args jako JSON.
Każdy key sekretuOdszyfrowana wartość sekretu.
<PLUGIN>_BINŚcieżka pliku binarnego każdej zadeklarowanej wtyczki. Foldery wtyczek są też dodawane 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", []))}))

Skrypt działa w tymczasowej kopii folderu umiejętności, z domyślnym limitem czasu 30 sekund. W macOS i Linuksie działa w piaskownicy systemu operacyjnego:

  • Nie może odczytywać magazynów danych logowania, danych przeglądarki i pęku kluczy ani własnych ustawień i bazy danych Nebo.
  • Może zapisywać tylko w swoim folderze roboczym i w /tmp/nebo. Możliwość storage dodaje folder danych Nebo.
  • Nie ma dostępu do sieci. Możliwość network zezwala na rejestry pakietów i domeny wymienione w metadata.allowed_domains.

Pliki i limity

ElementReguła
ZasobyKażdy plik oprócz SKILL.md, manifest.json, signatures.json i plików ukrytych (zaczynających się od kropki).
Pliki wykonywalnePliki w scripts/ lub bin/ oraz plik w katalogu głównym o nazwie binary.
ŚcieżkiWzględem folderu umiejętności. Ścieżki z .. lub wychodzące poza folder są odrzucane.
Wyłączona umiejętnośćFolder z plikiem SKILL.md.disabled zamiast SKILL.md.
Lista umiejętnościKażdy wpis jest przycinany do 250 znaków. Gdy cała lista przekracza 8000 znaków, najpierw skracane są wspólne umiejętności; własne umiejętności pracownika zachowują pełne wpisy.

Limity dla plików publikowanych w sklepie znajdziesz na stronie Publikowanie.