Do que uma skill é feita, e como ela chega ao agente

Camada funcional

Uma skill é um procedimento que o agente carrega quando a tarefa pede: um texto com as instruções, mais os arquivos auxiliares que ele precisar — roteiros, referências, modelos, imagens. Quem escreve é, na maior parte das vezes, o próprio agente.

O texto da skill

O texto abre com um cabeçalho de campos — nome, descrição, quanto tempo a skill costuma poupar — e segue com as instruções em si. O formato é o mesmo que o resto do ecossistema de skills usa, e a leitura dele é estrita de propósito: campo escrito fora do formato é recusado na hora, em vez de ser ignorado e virar comportamento faltando no meio de uma execução.

O VolundOS acrescenta um ramo próprio de requisitos: quais serviços a skill precisa conectados, quais credenciais espera, o que tem de existir na máquina. É o que permite dizer se ela é aplicável antes de tentá-la, em vez de descobrir no meio do caminho.

Onde a skill vive

A skill existe em três lugares ao mesmo tempo, e cada um tem um papel:

O nome da pasta sai do nome da skill, por uma convenção previsível — e o próprio agente descobre a skill por ele.

Detalhe que evita cópia desnecessária: skill publicada e instalada em outro agente continua lendo os auxiliares de onde eles já estavam, sem duplicar arquivo.

A marca de montagem incompleta

Esta é a parte que merece atenção — nasceu de perda real de dados.

O ciclo: no início da execução, os auxiliares são trazidos para a pasta do agente; no fim do turno, o que está guardado é conferido contra o que ficou em disco, e o que sumiu de lá é removido.

O problema: trazer os auxiliares podia falhar sem derrubar a execução — o texto da skill vem de outro lugar e chega de qualquer jeito. Resultado: uma falha passageira de leitura no início deixava a pasta sem os auxiliares, e a conferência do fim do turno apagava o que faltava ali. Uma piscada virava perda permanente.

A defesa: quando os auxiliares não chegam inteiros, fica na pasta uma marca dizendo isso — e a conferência do fim do turno, ao ver a marca, pula a remoção naquela skill. Ausência deixa de ser lida como apagamento.

Isso nasceu de um incidente real, em 06/07/2026: as skills de vários arquivos de um agente se perderam.

Sutileza de projeto: a marca tem conteúdo fixo, sem data. Ela participa da conta que decide se a pasta já está montada, e um conteúdo que mudasse a cada turno faria a montagem ser refeita do zero justamente numa skill que segue degradada.

Como o que o agente escreve volta

Sempre que o agente mexe na pasta de uma skill — escrevendo, copiando ou descompactando —, a plataforma vai até a máquina dele, lê os arquivos como eles estão e guarda essa fotografia. Skill apagada na máquina some também do outro lado.

A razão de ler os arquivos, em vez de aceitar o que o agente enviaria junto: o aviso de escrita não carrega arquivo binário, e o de comando não carrega conteúdo nenhum. Ler os bytes de lá é a única forma de guardar imagem, PDF ou pacote sem corromper.

Consequência prática para quem cria skill: arquivo binário tem de ser copiado por comando, não escrito como texto.

O link de download dura pouco de propósito

Quando um auxiliar precisa ser baixado, o endereço gerado vale quinze minutos. Antes eram sessenta dias. Como quem recebe o link usa na hora, quinze minutos cobrem com folga — e encurtam a janela em que um endereço que vazou para algum registro ainda serviria para alguém.