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.
| Campo | Tipo | Por omissão | Significado |
|---|---|---|---|
name | string | obrigatório | Identificador. [a-z0-9-], sem hífen inicial, final ou duplo, no máximo 64 bytes. Deve corresponder ao nome da pasta. |
description | string | obrigatório | O 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. |
version | string | "1.0.0" | Versão semântica. Verificada pelos intervalos requires de outras skills. Ponha-a entre aspas. |
triggers | lista 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ó. |
platform | lista de cadeias de texto | todos | macos, linux, windows. A skill só é carregada onde houver correspondência. |
capabilities | lista de cadeias de texto | [] | network e storage alargam a sandbox de scripts. Consulte Sandbox de scripts. |
metadata | map | {} | Contém secrets e allowed_domains. Consulte abaixo. |
requires | lista de {name, version} | [] | Outras skills em que esta skill se baseia. name é o nome curto da skill; version é um intervalo semver, por omissão "*". |
plugins | lista de {name, version, optional} | [] | Plugins que esta skill usa. version é "*" por omissão e optional é false. |
dependencies | lista de cadeias de texto | [] | Nomes curtos das skills que têm de estar presentes. |
priority | integer | 0 | Ordena as skills nas listas de gestão. Não afeta a skill que um funcionário escolhe. |
author | string | "" | Guardado para apresentação. |
license | string | "" | Guardado para apresentação. |
compatibility | string | "" | Nota de texto livre, no máximo 500 bytes. |
tags | lista de cadeias de texto | [] | Guardado para apresentação. |
allowed-tools | string | "" | 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 | Chave | Significado |
|---|---|
key | Nome da variável de ambiente que o script recebe. Obrigatório. |
label | Nome apresentado ao proprietário. |
hint | Onde obter o valor. |
required | Quando é 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ável | Valor |
|---|---|
${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. |
$ARGUMENTS | Os 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.
| Ferramenta | Parâmetros | O que faz |
|---|---|---|
use_skill | name, args | Carrega uma skill. Devolve o corpo expandido, o caminho da pasta e os primeiros 20 nomes de ficheiros. Volta a ativar uma skill desativada. |
find_skills | query | Devolve até 10 skills ordenadas pelas correspondências no nome, nos acionadores e na descrição. |
read_skill_file | name, path | Lê um ficheiro da pasta da skill. Sem path, lista os ficheiros e os respetivos tamanhos. |
save_skill | name, content | Escreve um SKILL.md completo na pasta de skills do utilizador. As skills da loja não podem ser substituídas. |
delete_skill | name | Elimina uma skill do utilizador. |
install_skill | code | Instala uma skill da loja a partir do seu código de instalação SKIL-. |
configure_skill | name, key, value | Define um segredo. Sem key, mostra o 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. 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.
| Script | Runtime |
|---|---|
.py | Python, através do uv incluído no Nebo, se existir; caso contrário, python3. |
.ts, .js | O Bun incluído no Nebo, se existir; 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 em JSON. |
Cada key de segredo | O valor do segredo decifrado. |
<PLUGIN>_BIN | Caminho 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 capacidadestorageacrescenta a pasta de dados do Nebo. - Não tem acesso à rede. A capacidade
networkpermite registos de pacotes e os domínios indicados emmetadata.allowed_domains.
Ficheiros e limites
| Item | Regra |
|---|---|
| Recursos | Todos os ficheiros exceto SKILL.md, manifest.json, signatures.json e ficheiros ocultos. |
| Executáveis | Ficheiros em scripts/ ou bin/ e um ficheiro na raiz chamado binary. |
| Caminhos | Relativos à pasta da skill. Os caminhos com .. ou que saiam da pasta são rejeitados. |
| Skill desativada | Uma pasta com SKILL.md.disabled em vez de SKILL.md. |
| Lista de skills | Cada 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.