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. Sumir do disco é o sinal de que algo foi apagado — mas, desde 11/09/2026, sumir não basta: a remoção exige também a prova de que o arquivo chegou a estar ali. A seção "Apagar exige prova, não só ausência", mais abaixo, conta por que, e o que aconteceu antes de essa prova existir.

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.

A instrução da skill não é um arquivo como os outros (correção de 24/09/2026)

Toda skill tem um texto principal — a instrução que o agente segue. Ele não é um dos arquivos auxiliares: mora na plataforma, e o que aparece junto dos anexos é só uma cópia que a máquina do agente monta para ele poder ler durante o trabalho.

Até 24/09/2026 dava para gravar por cima dessa cópia pela porta comum de arquivos — pela ferramenta do agente, ou enviando, salvando e movendo pela tela. O estrago não ficava na cópia: no fim do turno, a plataforma lia o que estava na máquina e promovia aquilo a instrução oficial da skill, apagando a original. Aconteceu de verdade, com uma skill real, em 24/09/2026.

Hoje essa gravação é recusada dos dois lados, com mensagem explicando onde editar. Um envio em lote que inclua a instrução junto de outros arquivos é recusado inteiro — aceitar os demais e descartar um calado é o tipo de meia-gravação que ninguém percebe na hora. A recusa também ignora maiúsculas e minúsculas: para a máquina do agente os dois nomes seriam arquivos diferentes, mas aceitar um e barrar o outro só confundiria quem está enviando.

Para mudar a instrução, use a aba própria dela na tela da skill, ou peça a atualização ao agente — nunca a porta de arquivos.

O explorador de arquivos — o da tela do agente e o da vitrine — também parou de mostrar essa cópia como se fosse um anexo, e ela não conta mais para o rótulo de "com arquivos" de uma skill.

Apagar exige prova, não só ausência (correção de 11/09/2026)

A frase acima — "skill apagada na máquina some também do outro lado" — era imprecisa demais até 11/09/2026, e um caso real mostrou o custo: arquivos auxiliares de várias skills foram apagados porque a preparação de início de turno não os encontrou. Eles tinham sido gravados por um caminho antigo e não apareciam na listagem nova. O agente recebia só o texto principal da skill, reimplementava o resto, e ao fim do turno a conferência lia "sumiu da máquina" como "o agente apagou" — quando na verdade a máquina nunca tinha visto aquele arquivo.

A correção troca o critério: a pasta de cada skill passa a carregar uma anotação do que esteve ali. Ela nasce na preparação do turno, com o que foi entregue, e é reescrita a cada fotografia da pasta — então ela descreve o que esta máquina de fato teve, não só o que chegou no começo. A conferência deixa de tratar "está guardado e não está na máquina" como prova suficiente de exclusão: agora só apaga um arquivo que consta dessa anotação. Sem a anotação, a exclusão é suprimida — o que está guardado fica à frente da máquina até o turno seguinte reconciliar, o que é reversível; apagar por engano não é.

Para a exclusão da skill inteira — a mais destrutiva, que a remove da plataforma —, duas provas diferentes servem:

• a pasta da skill não existe mais, o que é sinal direto de intenção;
• ou a pasta existe, está sem conteúdo, e a anotação afirma que algo tinha sido entregue ali.

Os arquivos de controle da própria preparação não contam como conteúdo nessa conta. Se contassem, esvaziar a pasta por um caminho que não alcança arquivo oculto deixaria o controle para trás, e a exclusão nunca seria espelhada.

Uma falha de leitura ambígua durante a varredura (por exemplo, uma subpasta que sumiu no meio do caminho, numa corrida com o próprio agente) também não conta como "a skill não existe" — só a pasta raiz ausente conta.

É a reescrita a cada fotografia que faz a regra funcionar nos dois sentidos. Um arquivo que o agente cria e apaga dentro do mesmo turno entra na anotação quando é criado, e por isso sai do armazenamento quando é apagado — em vez de ficar guardado e voltar sozinho na preparação seguinte. Se a anotação congelasse no início do turno, esse arquivo nunca constaria dela, e o que o agente apagou de propósito voltaria.

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.