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 ele expande, as ferramentas que os funcionários usam para trabalhar com skills e o ambiente em que os scripts rodam.

Formato do arquivo

O SKILL.md é um texto em UTF-8. Ele começa com uma linha de três hifens, depois vem o frontmatter YAML e então uma linha de fechamento com três hifens. Tudo o que vem depois é o corpo: as instruções em Markdown que o funcionário recebe quando carrega a skill. O Nebo encontra o arquivo pelo nome sem diferenciar 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 invalida o arquivo inteiro, e a skill não carrega. Chaves que não estão listadas aqui são ignoradas.

CampoTipoPadrãoSignificado
namestringobrigatórioIdentificador. [a-z0-9-], sem hífen no início, no fim ou duplicado, no máximo 64 bytes. Deve ser igual ao nome da pasta.
descriptionstringobrigatórioO que a skill faz e quando usá-la. No máximo 1.024 bytes. Exibida 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. Coloque-a entre aspas.
triggerslista de strings[]Palavras e frases que descrevem quando a skill se aplica. Até três aparecem na lista de skills; todas contam em find_skills. Elas nunca carregam uma skill sozinhas.
platformlista de stringstodosmacos, linux, windows. A skill só é carregada onde um deles corresponde.
capabilitieslista de strings[]network e storage ampliam a sandbox de scripts. Veja Sandbox de scripts.
metadatamap{}Contém secrets e allowed_domains. Veja abaixo.
requireslista de {name, version}[]Outras skills em que esta se baseia. name é o nome curto da skill; version é um intervalo semver, com padrão "*".
pluginslista de {name, version, optional}[]Plugins que esta skill usa. version tem padrão "*"; optional, false.
dependencieslista de strings[]Nomes curtos de skills que precisam estar presentes.
priorityinteger0Ordena as skills nas listas de gerenciamento. Não afeta qual skill um funcionário escolhe.
authorstring""Armazenado para exibição.
licensestring""Armazenado para exibição.
compatibilitystring""Nota em texto livre, com no máximo 500 bytes.
tagslista de strings[]Armazenado para exibição.
allowed-toolsstring""Uma string separada por espaços. Armazenada; não é aplicada.

Quando uma skill citada em requires ou dependencies está ausente ou fora do intervalo, ou um plugin obrigatório não está instalado, a skill ainda carrega e é marcada como degradada. O proprietário vê o que está faltando.

Segredos

Declare em metadata.secrets as credenciais de que os scripts de uma skill precisam. O proprietário fornece os valores, e o Nebo os armazena criptografados 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 exibido ao proprietário.
hintOnde conseguir o valor.
requiredQuando true, execute se recusa a rodar os scripts da skill até que o valor seja definido. Padrão false.

Um funcionário define um valor com configure_skill. Você pode referenciar um segredo no corpo como ${secret.KEY}, mas os scripts devem ler a variável de ambiente.

Variáveis de template

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

VariávelValor
${NEBO_SKILL_DIR}Caminho absoluto da pasta da skill.
${NEBO_DATA_DIR}Uma pasta gravável para esta skill: <data>/appdata/skills/<name>. Criada no primeiro uso.
${NEBO_USER_NAME}O nome do proprietário.
${NEBO_OS}O sistema operacional.
${NEBO_ARCH}A arquitetura do processador.
${plugin.SLUG_BIN}Caminho do binário de um plugin declarado. O slug fica em maiúsculas, com hífens trocados por sublinhados: example-ledger vira ${plugin.EXAMPLE_LEDGER_BIN}.
${secret.KEY}O valor de um segredo declarado.
$ARGUMENTSOs args passados para use_skill. Quando o corpo não tem $ARGUMENTS, os argumentos são acrescentados depois dele.

Ferramentas de skill

Os funcionários trabalham com skills por meio 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. Retorna o corpo expandido, o caminho da pasta e os primeiros 20 nomes de arquivo. Reativa uma skill desativada.
find_skillsqueryRetorna até 10 skills classificadas pelas correspondências no nome, nos gatilhos e na descrição.
read_skill_filename, pathLê um arquivo da pasta da skill. Sem path, lista os arquivos e os tamanhos deles.
save_skillname, contentGrava um SKILL.md completo na pasta de skills do usuário. Skills da loja não podem ser sobrescritas.
delete_skillnameExclui uma skill do usuário.
install_skillcodeInstala uma skill da loja a partir do código de instalação SKIL- dela.
configure_skillname, key, valueDefine um segredo. Sem key, mostra do 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. Veja Sandbox de scripts.

Sandbox de scripts

A ferramenta execute executa um script da pasta de uma skill. Ela escolhe o runtime a partir do arquivo.

ScriptRuntime
.pyPython, pelo uv incluído no Nebo, quando presente; caso contrário, python3.
.ts, .jsO Bun incluído no Nebo, quando presente; 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 como JSON.
Cada key de segredoO valor do segredo, descriptografado.
<PLUGIN>_BINCaminho do binário de cada plugin declarado. As pastas dos plugins também são adicionadas 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 roda em uma cópia temporária da pasta da skill, com um tempo limite padrão de 30 segundos. No macOS e no Linux, ele roda em uma sandbox do sistema operacional:

  • Ele não consegue ler repositórios de credenciais, dados do navegador e do keychain, nem as configurações e o banco de dados do próprio Nebo.
  • Ele só pode gravar na própria pasta de trabalho e em /tmp/nebo. A capacidade storage adiciona a pasta de dados do Nebo.
  • Ele não tem acesso à rede. A capacidade network libera os registros de pacotes e os domínios listados em metadata.allowed_domains.

Arquivos e limites

ItemRegra
RecursosTodos os arquivos, exceto SKILL.md, manifest.json, signatures.json e os arquivos ocultos.
ExecutáveisArquivos em scripts/ ou bin/ e um arquivo na raiz chamado binary.
CaminhosRelativos à pasta da skill. Caminhos com .. ou que saem da pasta são rejeitados.
Skill desativadaUma pasta com SKILL.md.disabled em vez de SKILL.md.
Lista de skillsCada entrada é cortada em 250 caracteres. Quando a lista inteira passa de 8.000 caracteres, as skills compartilhadas são encurtadas primeiro; as skills próprias de um funcionário mantêm as entradas completas.

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