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.
| Campo | Tipo | Padrão | Significado |
|---|---|---|---|
name | string | obrigatório | Identificador. [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. |
description | string | obrigatório | O 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. |
version | string | "1.0.0" | Versão semântica. Verificada pelos intervalos requires de outras skills. Coloque-a entre aspas. |
triggers | lista 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. |
platform | lista de strings | todos | macos, linux, windows. A skill só é carregada onde um deles corresponde. |
capabilities | lista de strings | [] | network e storage ampliam a sandbox de scripts. Veja Sandbox de scripts. |
metadata | map | {} | Contém secrets e allowed_domains. Veja abaixo. |
requires | lista de {name, version} | [] | Outras skills em que esta se baseia. name é o nome curto da skill; version é um intervalo semver, com padrão "*". |
plugins | lista de {name, version, optional} | [] | Plugins que esta skill usa. version tem padrão "*"; optional, false. |
dependencies | lista de strings | [] | Nomes curtos de skills que precisam estar presentes. |
priority | integer | 0 | Ordena as skills nas listas de gerenciamento. Não afeta qual skill um funcionário escolhe. |
author | string | "" | Armazenado para exibição. |
license | string | "" | Armazenado para exibição. |
compatibility | string | "" | Nota em texto livre, com no máximo 500 bytes. |
tags | lista de strings | [] | Armazenado para exibição. |
allowed-tools | string | "" | 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 | Chave | Significado |
|---|---|
key | Nome da variável de ambiente que o script recebe. Obrigatório. |
label | Nome exibido ao proprietário. |
hint | Onde conseguir o valor. |
required | Quando 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ável | Valor |
|---|---|
${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. |
$ARGUMENTS | Os 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.
| Ferramenta | Parâmetros | O que faz |
|---|---|---|
use_skill | name, args | Carrega uma skill. Retorna o corpo expandido, o caminho da pasta e os primeiros 20 nomes de arquivo. Reativa uma skill desativada. |
find_skills | query | Retorna até 10 skills classificadas pelas correspondências no nome, nos gatilhos e na descrição. |
read_skill_file | name, path | Lê um arquivo da pasta da skill. Sem path, lista os arquivos e os tamanhos deles. |
save_skill | name, content | Grava um SKILL.md completo na pasta de skills do usuário. Skills da loja não podem ser sobrescritas. |
delete_skill | name | Exclui uma skill do usuário. |
install_skill | code | Instala uma skill da loja a partir do código de instalação SKIL- dela. |
configure_skill | name, key, value | Define um segredo. Sem key, mostra do que a skill precisa. |
rate_skill | name, rating, review | Avalia uma skill da loja de 1 a 5. |
read_skill_reviews | name | Lê as avaliações de uma skill da loja. |
execute | skill, script, args, timeout | Executa 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.
| Script | Runtime |
|---|---|
.py | Python, pelo uv incluído no Nebo, quando presente; caso contrário, python3. |
.ts, .js | O Bun incluído no Nebo, quando presente; caso contrário, node. |
bin/<file> ou binary | Executado diretamente. |
.sh | Não suportado. |
Cada execução começa com um ambiente vazio e estas variáveis:
| Variável | Valor |
|---|---|
SKILL_ARGS | O objeto args como JSON. |
Cada key de segredo | O valor do segredo, descriptografado. |
<PLUGIN>_BIN | Caminho 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 capacidadestorageadiciona a pasta de dados do Nebo. - Ele não tem acesso à rede. A capacidade
networklibera os registros de pacotes e os domínios listados emmetadata.allowed_domains.
Arquivos e limites
| Item | Regra |
|---|---|
| Recursos | Todos os arquivos, exceto SKILL.md, manifest.json, signatures.json e os arquivos ocultos. |
| Executáveis | Arquivos em scripts/ ou bin/ e um arquivo na raiz chamado binary. |
| Caminhos | Relativos à pasta da skill. Caminhos com .. ou que saem da pasta são rejeitados. |
| Skill desativada | Uma pasta com SKILL.md.disabled em vez de SKILL.md. |
| Lista de skills | Cada 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.