Skills

Instruções reutilizáveis, instaláveis, que ensinam fluxos de trabalho repetíveis aos agentes.

Uma skill é um documento de instruções que só se abre quando é preciso: um ficheiro Markdown que ensina ao agente um procedimento, seja como instalar uma ferramenta ou como lidar com uma mensagem de áudio. É assim que um agente aprende algo novo sem que uma única linha de código mude.

Aparecem na lista, mas não carregam sozinhas

Uma skill nunca é colada por inteiro no prompt de sistema; no contexto do agente aparecem só o nome e um resumo de uma linha. Quando o assunto surge, é o próprio agente quem chama a ferramenta skill com esse nome, lê o documento inteiro, e segue-o.

É essa indireção que mantém tudo barato. Um agente consegue carregar dezenas de procedimentos pagando apenas uma linha de contexto por cada um, e só abre a versão longa no exato momento em que o trabalho o exige. O resumo é simplesmente a primeira linha não vazia do ficheiro, por isso vale a pena escrever essa abertura já a dizer quando a skill se aplica - a não ser que a skill declare esse resumo num cabeçalho de metadados, caso em que este vence: é isso que faz com que uma skill escrita noutra ferramenta funcione aqui tal como está (vê “Um formato que outras ferramentas partilham”, mais abaixo).

Skills nativas

Vêm de fábrica com o Pepe, em priv/skills/:

• skill-creator: como criar, editar, auditar e melhorar skills (a meta-skill).
• install-tool: escrever uma ferramenta em forma de plugin e ativá-la pela conversa.
• write-a-script: resolver tarefas complexas escrevendo e guardando um programa para correr.
• manage-routing: alterar rotas entre agentes através do set_route.
• handle-media: perceber uma entrada de voz, áudio, imagem ou ficheiro (transcrever, ler), instalando o que fizer falta.
• install-skill: instalar uma skill a partir de um URL, um gist, um repositório, ou outro Pepe.
• create-watch: montar um watch durável do género “verifica X e avisa-me quando acontecer”.

Escrever as tuas próprias

As skills do utilizador vivem em ~/.pepe/skills/*.md. Uma skill do utilizador sobrepõe-se sempre a uma nativa do mesmo nome, por isso, se escreveres o teu próprio handle-media.md, é ele que passa a valer em vez do que vem com o Pepe. A primeira linha não vazia funciona como resumo; tudo o resto é o procedimento em si, escrito em Markdown simples, pensado para o agente ler e seguir.

~/.pepe/skills/publicar-release.md

Não há passo de registo, nem reinício: basta pousares o ficheiro ali e a skill já aparece na lista do agente na mensagem seguinte.

Deixa o próprio agente escrevê-la

Um agente consegue escrever as suas próprias skills. Pede-lhe que guarde como skill a maneira de fazer alguma coisa e, guiado pelo skill-creator, ele grava um skills/<nome>.md novo, que já aparece de imediato na sua própria lista.

Tu: resultou. guarda como skill o processo de publicar uma release

Agente: guardei skills/publicar-release.md. Vou segui-lo da próxima vez que pedires uma release.

É isto que torna durável o conhecimento acumulado por um agente: um procedimento descoberto uma vez fica escrito, em vez de precisar de ser reinventado a cada sessão.

Aprender sem ninguém pedir

A meio da tarefa que a pessoa queria mesmo ver resolvida, ninguém se lembra de pedir uma skill, e por isso quase nenhum procedimento chega a ficar escrito. O skill_learning, desligado por omissão, fecha essa falha pelo outro lado: o Pepe repara no que o turno fez de facto e, nos turnos que o justificam, é o próprio agente a levantar o assunto.

• Um procedimento que vale a pena guardar. A tarefa exigiu pelo menos quatro chamadas de ferramenta bem-sucedidas, em pelo menos duas ferramentas diferentes, e não houve nenhuma skill existente consultada. O agente pode terminar a resposta com uma frase a propor guardar aquilo que acabou de descobrir.
• Uma skill que afinal estava errada. O agente leu uma skill e algo a seguir falhou. As instruções dela levaram a um sítio que não funciona, por isso o agente pode propor corrigi-la com o que a falha lhe ensinou: uma edição à skill que já existe, nunca uma segunda com outro nome.

Propor é tudo o que ele faz. Nada é escrito nem alterado antes do teu sim, e uma consulta rápida, um ciclo de tentativas na mesma ferramenta ou uma tarefa que já tinha skill passam sem uma palavra.

pepe agent add ops --skill-learning ...

Liga-o num agente cujo conhecimento deve ir acumulando e deixa-o desligado quando a biblioteca de skills é tratada à mão. O mesmo interruptor está no editor de agentes do painel, e um agente com a ferramenta manage_agent pode ligar o skill_learning noutro.

Arrumar a sua própria confusão

Um agente que escreve as suas próprias skills acaba por acumular um monte que ninguém volta a arrumar. É isso que o curador faz, com hora marcada, e só em skills que um agente escreveu por conta própria: uma skill que tu escreveste à mão, instalaste, ou fixaste nunca é tocada, seja qual for o estado em que está.

Ligado por omissão, faz duas passagens:

• Uma passagem determinística, sem modelo nenhum. Uma skill escrita por um agente vai passando por active → stale → archived só consoante o tempo que leva sem uso (fica stale ao fim de 14 dias, é arquivada ao fim de 30, ambos configuráveis). Se voltar a ser usada enquanto stale, regressa a active. Arquivar move a skill para .archive/ - nada é apagado, e pepe skill restore traz de volta.
• Uma passagem opcional com modelo (consolidate, desligada por omissão porque custa uma chamada): funde skills parecidas e demasiado estreitas noutras mais amplas, pelo mesmo caminho revisto e analisado que qualquer edição via manage_skill usa.

Corre no máximo uma vez por semana, e só quando nada acontece em nenhuma conversa há já algumas horas - nunca a meio do trabalho. Antes de mudar seja o que for, tira um snapshot de toda a biblioteca de skills, por isso uma passagem é sempre reversível:

pepe skill curator status                  # última passagem, próxima, contagens
pepe skill curator run --dry-run           # ver o que faria, sem mudar nada
pepe skill curator run --consolidate       # também fundir skills parecidas, só desta vez
pepe skill curator pause                   # impede novas passagens automáticas
pepe skill curator backup                  # tira um snapshot à mão
pepe skill curator rollback [ID]           # restaura o último snapshot (ou um em concreto)
pepe skill curator settings                # stale_after_days, archive_after_days, etc.
pepe skill curator set archive_after_days 45

Uma única passagem nunca arquiva mais de metade da biblioteca (ou 20 skills, o que for maior) a não ser que passes --force - uma proteção contra um limiar mal configurado, ou um conjunto de skills a ficarem ociosas todas de uma vez, que deitaria a biblioteca abaixo antes de alguém dar por isso. Também deixa de lado qualquer skill editada à mão fora do manage_skill, já que essa edição nunca passou por nada em que o curador confie. Desliga tudo com pepe skill curator set enabled false. Por agora é só CLI - ainda não há controlo pelo painel nem pela conversa.

Empacotar uma skill com scripts

Uma skill também pode chegar como um pequeno pacote em vez de um ficheiro solto: uma pasta <nome>/ com um SKILL.md (o documento de entrada, lido exatamente como um <nome>.md avulso) ao lado do que mais for preciso, tipicamente uma pasta scripts/.

~/.pepe/skills/publicar-release/
  SKILL.md
  scripts/marcar-e-publicar.sh

Os ficheiros do pacote nunca são copiados para outro lado: o agente chega até eles mesmo onde estão, do mesmo modo que já chega ao workspace partilhado ou a um plugin instalado, passando ao run_script (ou ao read_file) um caminho no formato skills/<nome>/scripts/<ficheiro>. Aponta as instruções do próprio SKILL.md para esse caminho, e o script corre exatamente como foi empacotado, sem o agente ter de o reescrever do zero a cada primeiro pedido de cada sessão.

Uma skill instalada pelo manage_skill ou pelo mix pepe skill install (mais abaixo) traz o pacote inteiro com ela sempre que a fonte tiver um: basta um SKILL.md na raiz do que foi instalado para marcar isso como pacote; qualquer coisa sem ele continua a instalar-se como um único <nome>.md, exatamente como antes. E não é só o documento que passa por análise de segurança antes de instalar, é cada ficheiro do pacote: o SKILL.md recebe a análise habitual contra injeção de prompt, e cada script incluído recebe a mesma análise profunda que o código de um plugin recebe.

Um formato que outras ferramentas partilham

Muitas ferramentas de agente publicam hoje as suas skills exactamente na forma que o Pepe já usa: uma pasta com um SKILL.md lá dentro. Os ficheiros delas abrem com um bloco YAML entre --- a trazer pelo menos name e description, e é essa description que serve de resumo. O Pepe lê esse cabeçalho, por isso uma skill escrita para qualquer uma dessas ferramentas corre aqui tal como está, sem nada a converter.

---
name: read-pdf
description: Extrai texto e tabelas de PDFs. Usa quando o utilizador enviar um PDF.
---

Corre `scripts/extract.py` com o caminho.

O cabeçalho é opcional e nada muda nas skills que já tens: sem ele, o resumo continua a ser a primeira linha não vazia. Usa-o quando a skill for feita para circular, porque uma skill tua que o traga fica igualmente legível por todas as outras ferramentas que falam este formato. Chaves para além de name e description (license, compatibility, metadata) ficam guardadas no ficheiro e não são tocadas. O formato completo está documentado em agentskills.io.

Duas peças a mais fecham este ciclo com o formato:

pepe skill validate PATH|NOME

verifica uma skill contra o que a especificação exige de facto (a forma e o comprimento do name, o comprimento da description, os tipos de license/compatibility/ metadata, o SKILL.md a abrir com um cabeçalho que faz parse) e reporta à parte o que apenas tropeça numa convenção do Pepe, meramente indicativa. O que falha a especificação não vai correr noutra ferramenta; o que só falha as convenções do Pepe continua a funcionar aqui na mesma. O mesmo relatório corre automaticamente em cada instalação e aparece no painel.

Uma skill também pode declarar o que precisa para correr de facto: variáveis de ambiente (required_environment_variables, ou as grafias setup.collect_secrets/ prerequisites.env_vars que outras ferramentas usam) e comandos (required_commands). O Pepe mostra o que falta no índice de skills, no pepe skill list, e no momento em que a skill é aberta, em vez de o agente só descobrir quando o primeiro comando falha a meio da tarefa. Um requisito em falta nunca esconde a skill: as instruções continuam a valer a pena ler, e podes estar prestes a definir a variável.

Uma skill instalada também passa a ser o seu próprio comando de barra em qualquer superfície que os tenha (Telegram, a consola, o chat do painel, um editor via ACP): uma skill chamada weather responde tanto a /weather como a /skill weather, e aparece no menu “/”. Corrê-la continua a ser um turno normal, lido pela ferramenta skill, nunca texto colado dentro do que escreveste, por isso aplica-se a mesma marcação de confiança que em qualquer outro sítio onde uma skill é lida, e só é oferecida a quem realmente a pode ver - vê a referência de comandos do Telegram para perceber essa verificação.

Instalar uma vinda de fora

Há dois caminhos, consoante a origem. Um agente com a ferramenta manage_skill usa-a para tudo o que o marketplace conseguir resolver: um nome no registo incluído ou num tap, ou uma referência do PepeHub (@handle/nome, ou o próprio URL da página), a mesma instalação com conhecimento de registo que o mix pepe skill install faz, com confiança e proveniência registadas da mesma forma. Para uma fonte sem entrada em nenhum registo (um URL avulso, um gist, um repositório fora de qualquer catálogo), é a skill install-skill que ensina o agente a ir buscá-la à mão. Seja qual for o caminho, texto de skill vindo de fora é sempre entrada não fiável: o agente analisa-o com a ferramenta scan_skill antes de o gravar em disco. A análise sinaliza injeção de prompt, exfiltração de segredos, comandos destrutivos, persistência e ofuscação, e serve como segunda verificação, não como substituto para leres o conteúdo tu mesmo; nunca instala nada por conta própria.

Instalar a partir de um marketplace

O manage_skill (visto acima) é o caminho conversacional para tudo o que os registos ou o PepeHub conseguirem resolver. Já o mix pepe skill é o caminho do operador para os mesmos registos, com a mesma pesquisa e a mesma história de atualização:

pepe skill search release            # pesquisa em cada tap mais o registo incluído
pepe skill install cut-a-release     # instala pelo nome
pepe skill install @jhonathas/google-workspace   # ou uma referência do PepeHub (vê abaixo)
pepe skill install cut-a-release --source https://example.com/cut-a-release.md   # ou diretamente
pepe skill install read-pdf --source https://github.com/some-org/skills          # uma skill de dentro de uma colecção
pepe skill update cut-a-release      # volta a obtê-la a partir da fonte exata de onde foi instalada
pepe skill tap add https://github.com/a-tua-equipa/pepe-skills   # acrescenta um registo além do incluído

Um nome no formato @handle/nome (ou o próprio URL da página do pacote, copiado diretamente do PepeHub) resolve-se contra o PepeHub em si, o registo de plugins e skills do Pepe, em vez do registo incluído ou de um tap; é verificado primeiro, já que nenhuma entrada incluída ou de tap usa esse formato. Fica instalado sob o slug puro do pacote (google-workspace, e não @jhonathas/google-workspace), o nome que todos os outros comandos de skill e a própria ferramenta skill usam. Se apontares o skill install para um nome que afinal é um plugin no PepeHub, e não uma skill, a instalação falha com uma mensagem clara a indicar plugin install em vez disso.

Uma origem pode guardar uma colecção inteira de skills lado a lado, cada uma na sua própria pasta, que é como a maioria das colecções públicas é publicada. Instalar por nome escolhe a pasta com esse nome, por isso pepe skill install read-pdf --source <repo> traz essa skill e os ficheiros dela, e não a primeira que o repositório listar.

Toda instalação passa pela mesma análise de segurança estática que o manage_skill/install-skill já usam; um veredito perigoso é recusado a menos que passes --force. A confiança fica marcada como "official" para o registo incluído no próprio repositório (curado pela equipa que mantém o Pepe) e para um pacote do PepeHub que o próprio PepeHub marcou manualmente como oficial. Tudo o resto, resolvido através de um tap que tu adicionaste, um pacote do PepeHub sem essa marca, ou instalado com --source, fica marcado como "community": quando um agente o lê pela ferramenta skill, o conteúdo vem envolvido no mesmo marcador de conteúdo não fiável de uma página web obtida da internet, até que o tenhas revisto tu mesmo.

O update fica preso à fonte exata de onde a skill foi instalada. Se o registo de um tap passar a apontar esse nome para uma fonte diferente mais tarde, o update recusa-se a seguir, em vez de o fazer em silêncio. Uma skill com o mesmo nome vinda de outro sítio só consegue substituir a já instalada através de um install --force explícito, nunca de uma atualização de rotina.

Skills, plugins e scripts

Skills, plugins e scripts funcionam em conjunto, e é essa combinação que permite pedir a um agente, em linguagem simples, algo que ele ainda não sabe fazer.

Juntando plugins ao enable_tool, dá para pedir pela conversa que o agente instale uma ferramenta que faça X: ele lê a skill install-tool, escreve o plugin em plugins/<nome>.exs, ativa a ferramenta em si mesmo, e já começa a usá-la, sem precisar de reiniciar nada.

Para trabalho complexo ou de vários passos, o agente não tenta fazer tudo à mão. A ferramenta run_script deixa-o escrever um programa curto (Python, Node, Ruby, Bash, ou Elixir, este último sempre disponível) e correr esse programa, recebendo de volta stdout, stderr e o código de saída para conseguir iterar sobre os erros. Os scripts que compensam ficam guardados em scripts/ e são reaproveitados mais tarde, bastando passar ao run_script uma referência file:. E quando o agente descobre como fazer uma tarefa recorrente, ler um PDF ou tratar de uma folha de cálculo, escreve para si próprio uma skill em skills/<nome>.md. É a skill write-a-script que ensina esse ciclo completo.