NeboAI
NeboAI
Começar

Referência do SKILL.md

Esta página lista todas as partes de uma skill que o Nebo lê: os campos do frontmatter, as variáveis que expande, as ferramentas que os funcionários usam para trabalhar com skills e o ambiente em que os scripts correm.

Formato do ficheiro

O SKILL.md é texto em UTF-8. Começa com uma linha de três hífenes, depois o frontmatter YAML e depois uma linha de fecho com três hífenes. Tudo o que vem a seguir é o corpo: instruções em Markdown que o funcionário recebe quando carrega a skill. O Nebo encontra o ficheiro pelo nome sem distinguir maiúsculas de minúsculas.

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

Campos do frontmatter

Só name e description são obrigatórios. Um campo com o tipo errado faz falhar o ficheiro inteiro, e a skill não é carregada. As chaves que não constam aqui são ignoradas.

CampoTipoPor omissãoSignificado
namestringobrigatórioIdentificador. [a-z0-9-], sem hífen inicial, final ou duplo, no máximo 64 bytes. Deve corresponder ao nome da pasta.
descriptionstringobrigatórioO que a skill faz e quando a usar. No máximo 1024 bytes. Apresentada na lista de skills do funcionário e pontuada por find_skills.
versionstring"1.0.0"Versão semântica. Verificada pelos intervalos requires de outras skills. Ponha-a entre aspas.
triggerslista de cadeias de texto[]Palavras e expressões que descrevem quando a skill se aplica. Até três aparecem na lista de skills; todas contam em find_skills. Nunca carregam uma skill por si só.
platformlista de cadeias de textotodosmacos, linux, windows. A skill só é carregada onde houver correspondência.
capabilitieslista de cadeias de texto[]network e storage alargam a sandbox de scripts. Consulte Sandbox de scripts.
metadatamap{}Contém secrets e allowed_domains. Consulte abaixo.
requireslista de {name, version}[]Outras skills em que esta skill se baseia. name é o nome curto da skill; version é um intervalo semver, por omissão "*".
pluginslista de {name, version, optional}[]Plugins que esta skill usa. version é "*" por omissão e optional é false.
dependencieslista de cadeias de texto[]Nomes curtos das skills que têm de estar presentes.
priorityinteger0Ordena as skills nas listas de gestão. Não afeta a skill que um funcionário escolhe.
authorstring""Guardado para apresentação.
licensestring""Guardado para apresentação.
compatibilitystring""Nota de texto livre, no máximo 500 bytes.
tagslista de cadeias de texto[]Guardado para apresentação.
allowed-toolsstring""Uma cadeia de texto separada por espaços. Guardada; não é imposta.

Quando uma skill indicada em requires ou dependencies está em falta ou fora do intervalo, ou quando um plugin obrigatório não está instalado, a skill carrega na mesma e fica marcada como degradada. O proprietário vê o que falta.

Segredos

Declare as credenciais de que os scripts de uma skill precisam em metadata.secrets. O proprietário fornece os valores e o Nebo guarda-os cifrados para essa skill.

metadata:
  secrets:
    - key: EXAMPLE_API_KEY
      label: Example API key
      hint: Create one at https://example.com/settings/keys
      required: true
ChaveSignificado
keyNome da variável de ambiente que o script recebe. Obrigatório.
labelNome apresentado ao proprietário.
hintOnde obter o valor.
requiredQuando é true, execute recusa-se a correr os scripts da skill até o valor estar definido. Por omissão false.

Um funcionário define um valor com configure_skill. Pode referir um segredo no corpo como ${secret.KEY}, embora os scripts devam ler antes a variável de ambiente.

Variáveis de modelo

O Nebo substitui estas variáveis no corpo quando um funcionário carrega a skill. Não são substituídas dentro de outros ficheiros; os scripts leem variáveis de ambiente.

VariávelValor
${NEBO_SKILL_DIR}Caminho absoluto da pasta da skill.
${NEBO_DATA_DIR}Uma pasta com permissão de escrita para esta skill: <data>/appdata/skills/<name>. Criada na primeira utilização.
${NEBO_USER_NAME}O nome do proprietário.
${NEBO_OS}O sistema operativo.
${NEBO_ARCH}A arquitetura do processador.
${plugin.SLUG_BIN}Caminho do binário de um plugin declarado. O slug passa a maiúsculas, com os hífenes trocados por sublinhados: example-ledger passa a ${plugin.EXAMPLE_LEDGER_BIN}.
${secret.KEY}O valor de um segredo declarado.
$ARGUMENTSOs args passados a use_skill. Quando o corpo não tem $ARGUMENTS, os argumentos são acrescentados no fim.

Ferramentas de skills

Os funcionários trabalham com skills através destas ferramentas. use_skill está sempre disponível; as outras são carregadas quando um funcionário precisa delas.

FerramentaParâmetrosO que faz
use_skillname, argsCarrega uma skill. Devolve o corpo expandido, o caminho da pasta e os primeiros 20 nomes de ficheiros. Volta a ativar uma skill desativada.
find_skillsqueryDevolve até 10 skills ordenadas pelas correspondências no nome, nos acionadores e na descrição.
read_skill_filename, pathLê um ficheiro da pasta da skill. Sem path, lista os ficheiros e os respetivos tamanhos.
save_skillname, contentEscreve um SKILL.md completo na pasta de skills do utilizador. As skills da loja não podem ser substituídas.
delete_skillnameElimina uma skill do utilizador.
install_skillcodeInstala uma skill da loja a partir do seu código de instalação SKIL-.
configure_skillname, key, valueDefine um segredo. Sem key, mostra o que a skill precisa.
rate_skillname, rating, reviewAvalia uma skill da loja de 1 a 5.
read_skill_reviewsnameLê as avaliações de uma skill da loja.
executeskill, script, args, timeoutExecuta um script da pasta de uma skill. Consulte Sandbox de scripts.

Sandbox de scripts

A ferramenta execute executa um script da pasta de uma skill. Escolhe o runtime a partir do ficheiro.

ScriptRuntime
.pyPython, através do uv incluído no Nebo, se existir; caso contrário, python3.
.ts, .jsO Bun incluído no Nebo, se existir; caso contrário, node.
bin/<file> ou binaryExecutado diretamente.
.shNão suportado.

Cada execução começa com um ambiente vazio e estas variáveis:

VariávelValor
SKILL_ARGSO objeto args em JSON.
Cada key de segredoO valor do segredo decifrado.
<PLUGIN>_BINCaminho do binário de cada plugin declarado. As pastas dos plugins também são acrescentadas ao 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", []))}))

O script corre numa cópia temporária da pasta da skill, com um tempo limite por omissão de 30 segundos. No macOS e no Linux corre numa sandbox do sistema operativo:

  • Não consegue ler armazéns de credenciais, dados do navegador e do porta-chaves, nem as definições e a base de dados do próprio Nebo.
  • Só pode escrever na sua pasta de trabalho e em /tmp/nebo. A capacidade storage acrescenta a pasta de dados do Nebo.
  • Não tem acesso à rede. A capacidade network permite registos de pacotes e os domínios indicados em metadata.allowed_domains.

Ficheiros e limites

ItemRegra
RecursosTodos os ficheiros exceto SKILL.md, manifest.json, signatures.json e ficheiros ocultos.
ExecutáveisFicheiros em scripts/ ou bin/ e um ficheiro na raiz chamado binary.
CaminhosRelativos à pasta da skill. Os caminhos com .. ou que saiam da pasta são rejeitados.
Skill desativadaUma pasta com SKILL.md.disabled em vez de SKILL.md.
Lista de skillsCada entrada é cortada aos 250 caracteres. Quando a lista inteira ultrapassa 8000 caracteres, as skills partilhadas são encurtadas primeiro; as skills próprias de um funcionário mantêm as entradas completas.

Os limites para os ficheiros que publica na loja estão na página Publicação.