NeboAI
NeboAI
Inizia

Riferimento SKILL.md

Questa pagina elenca ogni parte di una skill che Nebo legge: i campi del frontmatter, le variabili che espande, gli strumenti che i dipendenti usano per lavorare con le skill e l'ambiente in cui vengono eseguiti gli script.

Formato del file

SKILL.md è testo UTF-8. Inizia con una riga di tre trattini, poi il frontmatter YAML, poi una riga di chiusura di tre trattini. Tutto ciò che segue è il corpo: istruzioni in Markdown che il dipendente riceve quando carica la skill. Nebo trova il file per nome senza distinguere tra maiuscole e minuscole.

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

Campi del frontmatter

Solo name e description sono obbligatori. Un campo con il tipo sbagliato fa fallire l'intero file, quindi la skill non viene caricata. Le chiavi non elencate qui vengono ignorate.

CampoTipoPredefinitoSignificato
namestringobbligatorioIdentificatore. [a-z0-9-], senza trattini iniziali, finali o doppi, al massimo 64 byte. Deve corrispondere al nome della cartella.
descriptionstringobbligatorioCosa fa la skill e quando usarla. Al massimo 1.024 byte. Mostrata nell'elenco delle skill del dipendente e valutata da find_skills.
versionstring"1.0.0"Versione semantica. Verificata dagli intervalli requires di altre skill. Mettila tra virgolette.
triggerselenco di stringhe[]Parole e frasi che descrivono quando la skill è pertinente. Fino a tre compaiono nell'elenco delle skill; tutte contano in find_skills. Non caricano mai una skill da sole.
platformelenco di stringhetuttimacos, linux, windows. La skill si carica solo dove uno corrisponde.
capabilitieselenco di stringhe[]network e storage ampliano la sandbox degli script. Vedi Sandbox degli script.
metadatamap{}Contiene secrets e allowed_domains. Vedi sotto.
requireselenco di {name, version}[]Altre skill su cui si basa questa skill. name è il nome breve della skill; version è un intervallo semver, predefinito "*".
pluginselenco di {name, version, optional}[]Plugin usati da questa skill. version vale "*" per impostazione predefinita, optional vale false.
dependencieselenco di stringhe[]Nomi brevi delle skill che devono essere presenti.
priorityinteger0Ordina le skill negli elenchi di gestione. Non influisce su quale skill sceglie un dipendente.
authorstring""Memorizzato per la visualizzazione.
licensestring""Memorizzato per la visualizzazione.
compatibilitystring""Nota di testo libero, al massimo 500 byte.
tagselenco di stringhe[]Memorizzato per la visualizzazione.
allowed-toolsstring""Una stringa separata da spazi. Memorizzata; non imposta.

Quando una skill indicata in requires o dependencies manca o è fuori dall'intervallo, oppure un plugin obbligatorio non è installato, la skill si carica comunque e viene contrassegnata come ridotta. Il proprietario vede cosa manca.

Segreti

Dichiara le credenziali di cui hanno bisogno gli script di una skill sotto metadata.secrets. Il proprietario fornisce i valori, e Nebo li memorizza cifrati per quella skill.

metadata:
  secrets:
    - key: EXAMPLE_API_KEY
      label: Example API key
      hint: Create one at https://example.com/settings/keys
      required: true
ChiaveSignificato
keyNome della variabile d'ambiente che lo script riceve. Obbligatorio.
labelNome mostrato al proprietario.
hintDove ottenere il valore.
requiredCon true, execute si rifiuta di eseguire gli script della skill finché il valore non è impostato. Predefinito false.

Un dipendente imposta un valore con configure_skill. Puoi fare riferimento a un segreto nel corpo come ${secret.KEY}, anche se gli script dovrebbero invece leggere la variabile d’ambiente.

Variabili di modello

Nebo sostituisce queste variabili nel corpo quando un dipendente carica la skill. Non vengono sostituite negli altri file; gli script leggono invece le variabili d'ambiente.

VariabileValore
${NEBO_SKILL_DIR}Percorso assoluto della cartella della skill.
${NEBO_DATA_DIR}Una cartella scrivibile per questa skill: <data>/appdata/skills/<name>. Creata al primo utilizzo.
${NEBO_USER_NAME}Il nome del proprietario.
${NEBO_OS}Il sistema operativo.
${NEBO_ARCH}L'architettura del processore.
${plugin.SLUG_BIN}Percorso del binario di un plugin dichiarato. Lo slug è in maiuscolo, con i trattini sostituiti da trattini bassi: example-ledger diventa ${plugin.EXAMPLE_LEDGER_BIN}.
${secret.KEY}Il valore di un segreto dichiarato.
$ARGUMENTSGli args passati a use_skill. Quando il corpo non contiene $ARGUMENTS, gli argomenti vengono aggiunti dopo di esso.

Strumenti delle skill

I dipendenti lavorano con le skill tramite questi strumenti. use_skill è sempre disponibile; gli altri si caricano quando un dipendente ne ha bisogno.

StrumentoParametriCosa fa
use_skillname, argsCarica una skill. Restituisce il corpo espanso, il percorso della cartella e i primi 20 nomi di file. Riattiva una skill disattivata.
find_skillsqueryRestituisce fino a 10 skill ordinate per corrispondenze con nome, trigger e descrizione.
read_skill_filename, pathLegge un file nella cartella della skill. Senza path, elenca i file e le loro dimensioni.
save_skillname, contentScrive un SKILL.md completo nella cartella delle skill utente. Le skill del marketplace non si possono sovrascrivere.
delete_skillnameElimina una skill utente.
install_skillcodeInstalla una skill del marketplace dal suo codice di installazione SKIL-.
configure_skillname, key, valueImposta un segreto. Senza key, mostra ciò di cui la skill ha bisogno.
rate_skillname, rating, reviewValuta una skill del marketplace da 1 a 5.
read_skill_reviewsnameLegge le recensioni di una skill del marketplace.
executeskill, script, args, timeoutEsegue uno script dalla cartella di una skill. Vedi Sandbox degli script.

Sandbox degli script

Lo strumento execute esegue uno script dalla cartella di una skill. Sceglie il runtime in base al file.

ScriptRuntime
.pyPython, tramite l'uv incluso in Nebo quando presente, altrimenti python3.
.ts, .jsIl Bun incluso in Nebo quando presente, altrimenti node.
bin/<file> o binaryEseguito direttamente.
.shNon supportato.

Ogni esecuzione parte con un ambiente vuoto e queste variabili:

VariabileValore
SKILL_ARGSL'oggetto args come JSON.
Ogni key di segretoIl valore decifrato del segreto.
<PLUGIN>_BINPercorso del binario di ogni plugin dichiarato. Le cartelle dei plugin vengono aggiunte anche a 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", []))}))

Lo script viene eseguito in una copia temporanea della cartella della skill, con un timeout predefinito di 30 secondi. Su macOS e Linux viene eseguito in una sandbox del sistema operativo:

  • Non può leggere archivi di credenziali, dati del browser e del portachiavi, né le impostazioni e il database di Nebo.
  • Può scrivere solo nella sua cartella di lavoro e in /tmp/nebo. La capacità storage aggiunge la cartella dei dati di Nebo.
  • Non ha accesso alla rete. La capacità network consente i registri dei pacchetti e i domini elencati in metadata.allowed_domains.

File e limiti

ElementoRegola
RisorseTutti i file tranne SKILL.md, manifest.json, signatures.json e i file nascosti.
EseguibiliI file in scripts/ o bin/, e un file nella radice chiamato binary.
PercorsiRelativi alla cartella della skill. I percorsi con .. o che escono dalla cartella vengono rifiutati.
Skill disattivataUna cartella con SKILL.md.disabled al posto di SKILL.md.
Elenco delle skillOgni voce viene troncata a 250 caratteri. Quando l'intero elenco supera 8.000 caratteri, vengono accorciate prima le skill condivise; le skill proprie di un dipendente mantengono le voci complete.

I limiti per i file che pubblichi sul marketplace sono nella pagina Pubblicazione.