NeboAI
NeboAI
Aan de slag

SKILL.md-referentie

Deze pagina noemt elk onderdeel van een skill dat Nebo leest: de frontmattervelden, de variabelen die het invult, de tools waarmee medewerkers met skills werken, en de omgeving waarin scripts draaien.

Bestandsindeling

SKILL.md is UTF-8-tekst. Het begint met een regel van drie koppeltekens, dan YAML-frontmatter, dan een afsluitende regel van drie koppeltekens. Alles daarna is de body: Markdown-instructies die de medewerker krijgt wanneer hij de skill laadt. Nebo vindt het bestand op naam, ongeacht hoofdletters.

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

Frontmattervelden

Alleen name en description zijn verplicht. Een veld met het verkeerde type laat het hele bestand mislukken, waardoor de skill niet laadt. Sleutels die hier niet staan, worden genegeerd.

VeldTypeStandaardBetekenis
namestringverplichtIdentificatie. [a-z0-9-], geen koppelteken aan het begin of eind en geen dubbel koppelteken, maximaal 64 bytes. Moet overeenkomen met de mapnaam.
descriptionstringverplichtWat de skill doet en wanneer je hem gebruikt. Maximaal 1.024 bytes. Getoond in de skilllijst van de medewerker en beoordeeld door find_skills.
versionstring"1.0.0"Semantische versie. Gecontroleerd door de requires-bereiken van andere skills. Zet hem tussen aanhalingstekens.
triggerslijst met strings[]Woorden en zinnen die beschrijven wanneer de skill van toepassing is. Maximaal drie verschijnen in de skilllijst; ze tellen allemaal mee in find_skills. Ze laden nooit zelf een skill.
platformlijst met stringsallemacos, linux, windows. De skill laadt alleen waar er een overeenkomt.
capabilitieslijst met strings[]network en storage verruimen de sandbox voor scripts. Zie Sandbox voor scripts.
metadatamap{}Bevat secrets en allowed_domains. Zie hieronder.
requireslijst met {name, version}[]Andere skills waarop deze skill voortbouwt. name is de korte skillnaam; version is een semver-bereik, standaard "*".
pluginslijst met {name, version, optional}[]Plugins die deze skill gebruikt. version is standaard "*", optional standaard false.
dependencieslijst met strings[]Korte namen van skills die aanwezig moeten zijn.
priorityinteger0Bepaalt de volgorde van skills in beheerlijsten. Het heeft geen invloed op welke skill een medewerker kiest.
authorstring""Opgeslagen voor weergave.
licensestring""Opgeslagen voor weergave.
compatibilitystring""Vrije notitie, maximaal 500 bytes.
tagslijst met strings[]Opgeslagen voor weergave.
allowed-toolsstring""Een string gescheiden door spaties. Opgeslagen; niet afgedwongen.

Als een skill die in requires of dependencies wordt genoemd ontbreekt of buiten het bereik valt, of als een vereiste plugin niet is geïnstalleerd, laadt de skill toch en wordt hij gemarkeerd als beperkt. De eigenaar ziet wat er ontbreekt.

Geheimen

Declareer de inloggegevens die de scripts van een skill nodig hebben onder metadata.secrets. De eigenaar levert de waarden, en Nebo slaat ze versleuteld op voor die skill.

metadata:
  secrets:
    - key: EXAMPLE_API_KEY
      label: Example API key
      hint: Create one at https://example.com/settings/keys
      required: true
SleutelBetekenis
keyNaam van de omgevingsvariabele die het script ontvangt. Verplicht.
labelNaam die aan de eigenaar wordt getoond.
hintWaar je de waarde vandaan haalt.
requiredBij true weigert execute de scripts van de skill uit te voeren tot de waarde is ingesteld. Standaard false.

Een medewerker stelt een waarde in met configure_skill. Je kunt in de tekst naar een geheim verwijzen als ${secret.KEY}, maar scripts kunnen beter de omgevingsvariabele lezen.

Sjabloonvariabelen

Nebo vervangt deze variabelen in de body wanneer een medewerker de skill laadt. Ze worden niet vervangen in andere bestanden; scripts lezen in plaats daarvan omgevingsvariabelen.

VariabeleWaarde
${NEBO_SKILL_DIR}Absoluut pad van de map van de skill.
${NEBO_DATA_DIR}Een beschrijfbare map voor deze skill: <data>/appdata/skills/<name>. Aangemaakt bij het eerste gebruik.
${NEBO_USER_NAME}De naam van de eigenaar.
${NEBO_OS}Het besturingssysteem.
${NEBO_ARCH}De processorarchitectuur.
${plugin.SLUG_BIN}Pad van de binary van een gedeclareerde plugin. De slug wordt in hoofdletters gezet, met koppeltekens als underscores: example-ledger wordt ${plugin.EXAMPLE_LEDGER_BIN}.
${secret.KEY}De waarde van een gedeclareerd geheim.
$ARGUMENTSDe args die aan use_skill zijn meegegeven. Als de body geen $ARGUMENTS bevat, worden de argumenten erachter toegevoegd.

Skilltools

Medewerkers werken met skills via deze tools. use_skill is altijd beschikbaar; de andere worden geladen wanneer een medewerker ze nodig heeft.

ToolParametersWat het doet
use_skillname, argsLaadt een skill. Geeft de ingevulde body terug, het mappad en de eerste 20 bestandsnamen. Schakelt een uitgeschakelde skill weer in.
find_skillsqueryGeeft maximaal 10 skills terug, gerangschikt op overeenkomsten in naam, trigger en beschrijving.
read_skill_filename, pathLeest een bestand in de map van de skill. Zonder path toont het de bestanden en hun grootte.
save_skillname, contentSchrijft een complete SKILL.md naar de map met gebruikersskills. Marktplaatsskills kunnen niet worden overschreven.
delete_skillnameVerwijdert een gebruikersskill.
install_skillcodeInstalleert een marktplaatsskill via de SKIL--installatiecode.
configure_skillname, key, valueStelt een geheim in. Zonder key toont het wat de skill nodig heeft.
rate_skillname, rating, reviewBeoordeelt een marktplaatsskill van 1 tot 5.
read_skill_reviewsnameLeest de beoordelingen van een marktplaatsskill.
executeskill, script, args, timeoutVoert een script uit de map van een skill uit. Zie Sandbox voor scripts.

Sandbox voor scripts

De tool execute voert één script uit de map van een skill uit. Hij kiest de runtime op basis van het bestand.

ScriptRuntime
.pyPython, via de meegeleverde uv van Nebo indien aanwezig, anders python3.
.ts, .jsDe meegeleverde Bun van Nebo indien aanwezig, anders node.
bin/<file> of binaryDirect uitgevoerd.
.shNiet ondersteund.

Elke uitvoering begint met een lege omgeving en deze variabelen:

VariabeleWaarde
SKILL_ARGSHet args-object als JSON.
Elke key van een geheimDe ontsleutelde waarde van het geheim.
<PLUGIN>_BINPad van de binary van elke gedeclareerde plugin. Pluginmappen worden ook aan PATH toegevoegd.
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", []))}))

Het script draait in een tijdelijke kopie van de skillmap, met een standaard time-out van 30 seconden. Op macOS en Linux draait het in een sandbox van het besturingssysteem:

  • Het kan geen opslag voor inloggegevens, browser- en sleutelhangergegevens of de eigen instellingen en database van Nebo lezen.
  • Het kan alleen schrijven naar zijn werkmap en /tmp/nebo. De capability storage voegt de gegevensmap van Nebo toe.
  • Het heeft geen netwerktoegang. De capability network staat pakketregisters toe en de domeinen die in metadata.allowed_domains staan.

Bestanden en limieten

ItemRegel
BronnenElk bestand behalve SKILL.md, manifest.json, signatures.json en dotfiles.
Uitvoerbare bestandenBestanden onder scripts/ of bin/, en een bestand in de hoofdmap met de naam binary.
PadenRelatief ten opzichte van de skillmap. Paden met .. of die buiten de map gaan, worden geweigerd.
Uitgeschakelde skillEen map met SKILL.md.disabled in plaats van SKILL.md.
SkilllijstElke vermelding wordt afgekapt op 250 tekens. Als de hele lijst langer is dan 8.000 tekens, worden eerst gedeelde skills ingekort; de eigen skills van een medewerker houden hun volledige vermelding.

Limieten voor bestanden die je op de marktplaats publiceert, staan op de pagina Publiceren.