Conceber, aperfeiçoar e manter Agent Skills na Perplexity

Os produtos de agentes de ponta da Perplexity assentam numa base de conhecimento prático e especialização em domínios específicos, agrupada em Agent Skills modulares. Mantemos uma biblioteca de Skills cuidadosamente selecionada em todos os nossos ambientes técnicos. Estas Skills incluem muitos dos utilitários de uso geral que dão vida ao Perplexity Computer, capacidades específicas de setores como finanças, direito e saúde, e uma cauda muito longa de módulos para responder às necessidades dos utilizadores. Algumas Skills raramente são invocadas, mas são críticas quando são invocadas. Para garantir uma experiência de utilizador consistentemente excelente, a equipa de Agentes da Perplexity dá tanta prioridade à qualidade das Skills como à qualidade do código.

As intuições e boas práticas necessárias para desenvolver uma Skill de alta qualidade diferem significativamente das necessárias para criar software tradicional. A equipa de Agentes analisa muitos pull requests de engenheiros excelentes que desenvolvem Skills no âmbito do seu trabalho. O resultado é quase sempre uma série de comentários e sugestões de revisão. Isto acontece porque muitos padrões úteis na escrita de código se tornam antipadrões na criação de Skills.

Por exemplo, se pegarmos em alguns dos aforismos do PEP20 – The Zen of Python, rapidamente se torna evidente que escrever bom código Python não é como escrever boas Skills. Das 20 linhas de sabedoria, pelo menos metade estão totalmente erradas ou são claramente enganadoras quando se escrevem Skills. Eis cinco delas:

Cinco contrastes entre o Zen of Python e as orientações do artigo para escrever Skills.

Este guia é o documento que os engenheiros de toda a Perplexity utilizam ao desenvolver e rever Skills. Estamos também a disponibilizar este guia ao público para que as nossas descobertas e aprendizagens possam beneficiar a comunidade em geral. Quer seja um engenheiro que concebe Skills de produção no dia a dia, um utilizador do Computer que pretende desenvolver a sua própria Skill numa área que conhece bem, ou ambos, este guia é para si.

O que é uma Skill?

Quando escreve uma Skill, não está a escrever software comum (apesar de as Skills fazerem agora parte dos principais motores lógicos dos sistemas de agentes). Em vez disso, está a construir contexto para os modelos e os respetivos ambientes. Uma Skill tem restrições diferentes e princípios de conceção diferentes. Se escrever uma Skill como escreve código, vai falhar.

Uma Skill é, no mínimo, quatro coisas, sobretudo no contexto da forma como as criamos na Perplexity.

Uma Skill é um diretório

Uma Skill não é apenas um único ficheiro SKILL.md. Em muitos casos, uma Skill inclui vários ficheiros. No diretório com o nome da sua Skill, pode ter:

SKILL.md: frontmatter e instruções

scripts/: código que o agente executa, em vez de o reinventar

references/: documentação extensa, carregada condicionalmente

assets/: modelos, esquemas e dados

config.json: configuração do utilizador na primeira execução

Este padrão em estrela permite manter as Skills muito focadas e concisas, e a estrutura de pastas pode ser usada de forma muito criativa. Por vezes, as Skills particularmente complexas beneficiam de vários níveis de hierarquia que ajudam o modelo a orientar-se melhor. Suponha que uma Skill requer conhecimentos sobre 300 temas, agrupáveis em 20 áreas temáticas. Escolher de forma fiável o tema certo entre 300 é um desafio por resolver, mesmo para os melhores modelos de ponta atuais. Para um modelo, é um problema de escolha muito mais fácil concentrar-se numa de 20 áreas do que entre os 15 temas dessa área.

Como exemplo do valor que uma hierarquia multinível proporciona, a nossa equipa utilizou três níveis de aninhamento temático nas Skills que suportam as capacidades do Computer em matéria de imposto sobre o rendimento dos EUA durante a última época fiscal. Esta hierarquia foi absolutamente indispensável dada a complexidade da legislação fiscal: nos nossos primeiros testes, apresentar ao modelo uma única pasta com todas as 1945 secções do Código Fiscal dos EUA (Internal Revenue Code) resultou num desempenho pior do que não carregar a Skill de todo. Organizar a informação em subdivisões lógicas foi indispensável para garantir operações de leitura de elevada precisão.

No entanto, esta hierarquia não saiu de graça. Mais níveis de hierarquia exigem mais curadoria em toda a arquitetura da informação para gerir a indireção resultante. Criámos guias de referência rápida, utilitários de pesquisa personalizados e outras ferramentas para ajudar o modelo a localizar informação com o mínimo de indireção. Neste caso, o árduo trabalho de curadoria acabou por produzir um resultado final positivo: uma Skill que permitiu aos modelos executar tarefas fiscais com muito mais competência do que recorrendo apenas a ferramentas genéricas.

Expandir

Uma Skill é um formato

Uma Skill é um formato. O ficheiro raiz principal SKILL.md tem de ter um nome e uma descrição. Além disso, a Skill tem de corresponder exatamente ao nome do diretório em que se encontra. O nome tem de estar todo em minúsculas, não pode ter espaços e pode usar hífenes. A descrição é o acionador de encaminhamento. Este é um ponto de falha comum: a descrição não é documentação interna sobre o que a Skill faz. Equivale a instruções para o modelo sobre quando carregar a Skill. Por isso, verá frequentemente «Load when» («Carregar quando») e não «This Skill does» («Esta Skill faz»). Isto é importante devido à forma como a maioria das implementações injeta a descrição no contexto do modelo.

No frontmatter, existe também «depends:», que permite criar dependências hierárquicas entre Skills, e «metadata:», que é utilizado para revisões e avaliações. Diferentes sistemas de agentes podem até definir os seus próprios campos de frontmatter, para serem utilizados de forma específica nesses sistemas. Em alternativa, os metadados específicos de cada Skill podem ser incluídos num ficheiro de configuração JSON ou YAML auxiliar. Isto é desejável ao criar sistemas de agentes que precisam de suportar diferentes tipos de comportamento em tempo de execução por Skill sem poluir o contexto do modelo com minúcias. Por fim, é possível obter um comportamento semelhante removendo o frontmatter da Skill no momento da leitura. O Computer utiliza esta metodologia, que permite preservar a configuração no ficheiro raiz SKILL.md. É necessária uma atenção cuidadosa aos detalhes na lógica de análise, e pode ser útil implementar uma remoção condicional se existirem determinados campos que seja vantajoso manter no contexto do modelo.

Uma Skill é invocável

Uma Skill é invocável. O agente carrega uma Skill em tempo de execução. Importa salientar que as Skills nem sempre são incluídas no contexto. Por predefinição, a maioria dos sistemas de agentes revela as Skills progressivamente, consoante a necessidade específica.

Existem pelo menos três níveis de custos de contexto na forma como implementámos as Skills no Computer. Eis o processo:

O Computer chama load_skill(name="...")

O Computer copia o diretório da Skill para a sandbox de execução isolada

O Computer carrega automática e recursivamente as dependências indicadas na etiqueta «depends:»

Em seguida, o Computer remove o frontmatter e, assim, o agente só vê o corpo e os ficheiros adicionais

Diferentes sistemas de agentes podem optar por expor o conteúdo das Skills de formas diferentes. Por exemplo, alguns sistemas podem optar por não expor de todo a hierarquia de ficheiros, deixando que o modelo a descubra através de operações no sistema de ficheiros. Outros sistemas podem optar por fornecer ao modelo um mapa de toda a árvore de ficheiros até um determinado limite de truncagem e/ou de profundidade. Para manter o contexto limpo, o Computer omite as hierarquias de ficheiros completas do contexto de invocação; no entanto, este comportamento pode ser substituído em cada Skill.

Uma Skill é progressiva

As Skills são progressivas. No Computer, existem três níveis diferentes de custos de contexto, e incorremos nos três em várias fases:

Os três níveis de contexto de uma Skill: índice, carregamento completo da Skill e ficheiros de referência em tempo de execução.

O Computer cria um índice de Skills com o nome e a descrição de cada Skill disponível. O orçamento para isto é de cerca de 100 tokens por Skill (quanto mais curto, melhor). É tão apertado porque está a pagar este custo em todas as sessões, para todos os utilizadores. Este índice é injetado no prompt de sistema logo no início da conversa. O modelo tem acesso a um conjunto de Skills com nome e descrição para poder decidir se deve chamar «load_skill()». A fasquia para entrar neste índice é extremamente alta. A sua Skill tem de ser muito útil, e a descrição tem de ser extremamente densa e concisa, porque todos estão a pagar o custo a toda a hora.

Depois de o sistema de agentes carregar a Skill, surge o corpo completo do SKILL.md. Idealmente, o texto do corpo não excede 5000 tokens. Mesmo assim, convém que cada frase conte, porque, depois de carregar uma Skill, o resto da conversa tem de pagar esse custo até atingir o limite de compactação. Muitas conversas carregam entre três e cinco Skills diferentes, o que multiplica este custo. As Skills com muito conteúdo supérfluo irão quase de certeza degradar outras Skills, bem como as capacidades agênticas globais. Em suma, se a sua Skill for carregada e não fizer o que deve, é contexto desperdiçado.

O último nível de progressão são os scripts ou casos especiais, como sub-Skills ou formatação. É aqui que deve colocar lógica condicional ramificada e ilimitada. O agente só a utilizará quando precisar, o que significa que a fasquia para o que quer colocar aqui é muito mais baixa.

No índice, cada token é importante. O corpo da Skill carregada é mais flexível, e o tempo de execução é o mais flexível de todos. Pode ser 20 000 tokens ou zero tokens. É neste nível que pode pensar em expandir o contexto do modelo de forma progressiva.

Quando é que precisa de uma Skill?

Pedem frequentemente à equipa de Agentes uma opinião sobre se uma Skill é realmente necessária para um determinado domínio ou caso de utilização. Muito raramente temos uma resposta definitiva apenas a partir de princípios fundamentais. A única forma de descobrir realmente é começar com o seu agente sem a Skill, executar várias consultas de referência e depois perceber se o agente está a fazer um bom trabalho.

Quando precisa de uma Skill

Há muitas tarefas que estão dentro da distribuição dos modelos treinados. Só precisa de aplicar uma Skill se quiser alterar esse comportamento de alguma forma específica que não consiga com, por exemplo, uma frase no seu prompt. Por isso, precisa de uma Skill quando o agente vai errar sem contexto especial, ou se existir alguma inconsistência ou não determinismo que precise de tornar extremamente consistente entre execuções.

Pode acontecer que o seu conhecimento seja duradouro, mas não esteja nos dados de treino. Pode haver datas de corte ou fluxos de trabalho específicos da empresa, ou pode ser uma questão de gosto. Por exemplo, temos várias Skills relacionadas com design no Computer escritas por Henry Modisett (o nosso responsável de design). A razão pela qual cada token existe nessas Skills é que o Henry tem muito bom gosto no que toca a desenhar sites e PDFs. O Henry especifica que tipos de letra usar e quais não usar, a sensação que esses tipos de letra transmitem e outras questões de critério que o modelo não consegue aprender apenas com os dados de treino.

Quando não precisa de uma Skill

Vemos muitas Skills em que os engenheiros escreveram uma série de comandos git que têm de ser executados por ordem. Isso é desnecessário, porque o modelo já sabe fazê-lo, o que significa que dá uma ótima documentação, mas uma má Skill.

Vemos exemplos em que as Skills repetem instruções do prompt de sistema. Não precisa de uma Skill para isso. O conhecimento relevante para a maioria dos pedidos deve ser incluído no contexto global e não numa Skill carregada condicionalmente

Se algo muda mais depressa do que consegue mantê-lo, não precisa de uma Skill. Por exemplo, se estiver a aceder a um endpoint MCP remoto e as respetivas ferramentas ou as versões dessas ferramentas mudarem com frequência, não as deve injetar numa Skill. Se o fizer, vai acabar por ter desvios e o modelo vai cometer erros.

Cada Skill é um imposto

Eis um teste útil que pode aplicar a cada frase da sua Skill: «O agente faria isto mal sem esta instrução?» Se a frase não precisa de estar lá, não se pode dar ao luxo de estar lá, porque todos pagam este custo todas as vezes. Quando estiver a decidir se adiciona ou não uma Skill, lembre-se deste imposto, segundo o qual cada sessão e cada utilizador custam tokens.

A seguinte citação célebre, que soa muito melhor em francês, traduz-se aproximadamente por «Só fiz esta carta mais longa porque não tive tempo de a fazer mais curta.»

« Je n’ai fait celle-ci plus longue que parce que je n’ai pas eu le loisir de la faire plus courte. » — Blaise Pascal, Lettres Provinciales, 1657

Tal como Pascal, tem de investir tempo em cada Skill. É difícil escrever uma Skill curta. Se a sua Skill é fácil de escrever, provavelmente é demasiado longa ou não deveria existir. Uma boa Skill é tão curta quanto possível.

Se der por si a tentar gerar uma Skill à primeira e a abrir PRs em cinco minutos, os resultados serão quase de certeza medíocres. Na verdade, estudos iniciais demonstraram que, se estiver a usar LLMs para escrever Skills, o LLM provavelmente não beneficiará disso: «As Skills autogeradas não trazem qualquer benefício, em média, o que mostra que os modelos não conseguem criar de forma fiável o conhecimento procedimental de que beneficiam ao consumi-lo.»

Como criar uma Skill

Dito de outra forma, tem de injetar a sua opinião em qualquer Skill que escreva. Siga estes passos.

Passo 0: escrever as avaliações

Escreva primeiro algumas das avaliações. Pode obter casos de avaliação a partir de:

Consultas reais de utilizadores: amostras da produção ou do seu grupo de confiança

Falhas conhecidas: o agente falhou porque a Skill não existia

Confusão com vizinhos: próximo da fronteira do seu domínio, mas encaminhado para outra Skill

No mínimo, deve garantir que está a testar se a Skill é carregada quando necessário. Idealmente, recolha uma amostra destes casos, talvez de um ambiente de produção. Pode também considerar casos de erro conhecidos: talvez o motivo pelo qual decidiu escrever a Skill seja uma falha específica que detetou, ou talvez esteja a refatorizar e exista alguma confusão entre dois domínios próximos abrangidos por uma Skill.

Comece com exemplos negativos e positivos semelhantes. Os exemplos negativos são extremamente poderosos e podem ser mais importantes do que os positivos.

Passo 1: a descrição

Esta é a linha mais difícil da Skill. É um acionador de encaminhamento, não documentação. Para acertar no nome e na descrição, o conteúdo da Skill não interessa. Só interessa se a Skill é carregada e injetada nos pontos certos e se não tem efeitos secundários indesejados, que são o modo de falha número um. Sempre que adiciona outra Skill, arrisca-se a piorar ligeiramente todas as outras Skills, por isso tem de garantir que minimiza as regressões.

Repetindo: uma má descrição descreve o que a Skill faz ou porque é útil. Uma boa descrição diz quando o agente deve carregar a Skill. Por exemplo, imagine que tem algo para monitorizar pull requests. Não escreva o que a Skill faz. Escreva o que os engenheiros dizem quando estão frustrados e querem que garanta que o PR deles funciona, como «vigia isto», «acompanha a CI» ou «garante que isto é integrado».

Eis uma lista de verificação rápida:

Começa com «Load when...» («Carregar quando...»)

Objetivo: 50 palavras ou menos

Descreve a intenção do utilizador, idealmente com base em consultas reais

Não resume o fluxo de trabalho

As consultas reais são o que consegue cobrir numa lógica 80-20. Normalmente, dois ou três exemplos funcionam bem. Não é fácil adicionar exatamente e apenas o necessário.

Passo 2: escrever o corpo

Em seguida, escreva o conteúdo da própria Skill. Repare que isto não é o Passo 0 nem o Passo 1.

Comunicar fluxos de trabalho a um LLM é completamente diferente de os comunicar a um colega, ou mesmo ao seu sistema de tempo de execução. Ao aprender uma nova ferramenta de software, um engenheiro pode precisar de ler a documentação, receber uma demonstração de alguém com experiência e aprender a usar a ferramenta. Já no caso de praticamente qualquer ferramenta de software que exista há pelo menos um ano, basta mencionar o nome e o LLM tem toda a informação de que precisa.

Ao escrever o corpo, ignore o óbvio. Muitos engenheiros têm bastante experiência a escrever ficheiros readme.md que enumeram todos os comandos que alguém precisa de executar. É fácil voltar a esse hábito quando está a escrever uma Skill, porque parece que está a escrever documentação, mas, se o fizer, a sua Skill não vai prestar. Por isso, não escreva uma série de comandos.

Por exemplo, não precisa de escrever «git log # find the commit; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;»

Em vez disso, escreva: «Faça cherry-pick do commit para um branch limpo. Resolva os conflitos sem perder a intenção. Se não for possível integrar sem problemas, explique porquê.»

O modelo fará um trabalho muito melhor com a segunda opção do que com a série de comandos excessivamente prescritiva da primeira, sobretudo quando algo corre mal. Não imponha um caminho rígido nem seja excessivamente prescritivo, o que é frágil; seja antes flexível quando várias abordagens podem funcionar. Mais uma vez, uma boa documentação para humanos é, na maioria das vezes, má documentação para modelos.

Em seguida, concentre-se nas armadilhas ou nos exemplos negativos. São conteúdos com um sinal extremamente elevado, porque muitas vezes orientam o modelo sobre o que não fazer. Se adicionar uma linha sempre que o agente tropeça, vai aprender ao executá-lo e as armadilhas vão crescer de forma orgânica.

Por fim, se houver alguma parte condicional ou extremamente pesada em conteúdo, retire-a do SKILL.md, que é o núcleo, e coloque-a numa das ramificações. Coloque-a num ficheiro acessório que possa ser carregado progressivamente, algo que vamos aprofundar a seguir.

Passo 3: usar a hierarquia

Tire partido da hierarquia da Skill quando tiver um script, referências ou estiver a usar alguma ferramenta específica:

Utilizações sugeridas para scripts, referências, recursos e configuração numa Skill.

Para tudo o que seja condicional ou que se ramifique a partir da Skill principal, separe-o numa pasta. Lembre-se também de que a hierarquia multinível pode ser usada para Skills particularmente complexas. Nestes casos, deve ponderar cuidadosamente se a funcionalidade deve ser implementada de forma monolítica ou como um conjunto de Skills (talvez com relações de carregamento baseadas em depends:).

Passo 4: iterar

Em seguida, faça várias iterações num branch. Comece no branch principal sem Skill, faça algumas iterações, crie o seu conjunto de consultas de referência e execute uma série de avaliações. Quem rever o código da sua Skill vai agradecer-lhe por submeter um único conjunto de alterações acompanhado de um conjunto de avaliação. Rever alterações incrementais consecutivas (exceto uma nova armadilha) é muito difícil, por isso tente minimizá-las.

É provável que faça muitas pequenas alterações de palavras. Pequenas alterações de palavras nas descrições podem ter um impacto desproporcionado no encaminhamento (incluindo efeitos colaterais noutras Skills), por isso faça todo esse trabalho antes do Passo 5.

Passo 5: lançar

Lance-o.

Como manter uma Skill

Agora que escreveu uma Skill, tem de a manter.

O ciclo virtuoso das armadilhas

A partir deste momento, a sua lista de armadilhas tende a crescer ou a mudar muito. Vemos muitas vezes engenheiros a fazer PRs sem avaliações, por exemplo, para alterar a descrição. Se está a alterar a descrição depois de a sua Skill ter sido integrada, está a desviar-se do caminho. Se está a fazer alterações àquilo que decide se a sua Skill é encaminhada, tem de escrever algumas avaliações que sustentem essas alterações.

As Skills funcionam sobretudo por acréscimo. A secção de armadilhas é a que acumula mais valor ao longo do tempo:

O agente falha em algo → Adicionar uma armadilha

O agente carrega a Skill fora do alvo → Restringir a descrição e adicionar avaliações negativas

O agente não carrega a Skill quando deveria → Adicionar palavras-chave e avaliações positivas

Alterações ao prompt de sistema → Verificar se há conflitos ou duplicações

É fácil detetar um único caso de falha nos testes internos ou em produção e acrescentar um gotcha. Trata-se de um exemplo negativo, pelo que não altera propriamente as orientações explícitas, mas permite ao modelo saber: «Atenção, existe esta falha conhecida.»

À medida que se passa do 80-20 para uma taxa de sucesso de 99,9% ou 99,99%, é fácil que esta lista de gotchas cresça. Ao encontrar estes exemplos negativos, deve acrescentá-los sobretudo à secção de gotchas. Não deve adicionar instruções mais longas nem alterar a descrição.

Conjuntos de avaliações

Na Perplexity, executamos muitos conjuntos de avaliações para verificar diferentes aspetos. Há avaliações de carregamento de Skills e de leitura de ficheiros de Skills, que verificam a precisão, a revocação (recall) e as verificações de cargas proibidas do próprio carregamento da Skill. O agente encaminha a sua Skill quando é suposto fazê-lo? Estas avaliações garantem que as novas Skills não quebram os limites existentes. 

Há também avaliações que verificam se o carregamento progressivo é feito corretamente. O agente pode carregar a Skill, mas lê o ficheiro ou ficheiros acessórios? Por exemplo, se tiver uma Skill de finanças para consultas financeiras, o agente lê o ficheiro especial FORMATTING.md?

Há ainda avaliações de Skills que testam a conclusão de tarefas de ponta a ponta dentro de domínios específicos. Executamos o ciclo completo do agente e usamos um LLM como juiz para classificar os resultados com base numa grelha de critérios bem definidos.

Por fim, é importante executar estas avaliações com diferentes modelos. O Computer suporta pelo menos três famílias de modelos de orquestração diferentes: GPT, Claude Opus e Claude Sonnet. Convém executar as avaliações de carregamento de Skills e das Skills de domínio com estes diferentes orquestradores de agentes, para garantir que não obtém comportamentos diferentes. O Sonnet e o GPT comportam-se de forma bastante diferente no que toca a Skills.

Reflexões finais e conclusões

Quanto mais Skills criar, melhor ficará a criá-las. Se ainda não está a usar Skills para automatizar as tarefas do dia a dia ou para as tornar mais reproduzíveis, comece imediatamente.

Criar Skills torna-o melhor a criar mais Skills, mas, além disso, as Skills são extremamente eficazes a automatizar processos de negócio. Se consegue descrever algo que faz todas as semanas antes da reunião diária (standup), no final de cada sprint, ou qualquer outra coisa que faça como engenheiro numa base diária, semanal ou até trimestral, deve escrever uma Skill para recuperar o seu tempo.

É possível automatizar postmortems? E rever pull requests? Em qualquer tarefa que consiga fazer, pode, no mínimo, deixar a primeira passagem a cargo de uma Agent Skill. Vai poupar-lhe imenso tempo.

Dito isto, lembre-se de que uma Skill não é fácil, nem sequer é sempre necessária. Menos é mais. Algumas outras conclusões:

Escreva as avaliações antes da Skill. Inclua exemplos negativos e cargas proibidas para Skills adjacentes, mas distintas.

A descrição é a parte difícil. «Carregar quando...» (cada palavra tem um custo em atenção).

Os gotchas são conteúdos de valor extremamente elevado. Comece com pouco e vá acrescentando à medida que o agente falha.

Lembre-se de que é fácil estragar outras Skills já existentes ao adicionar uma nova Skill, mesmo sem lhes ter tocado (cuidado com a ação à distância).

Utilize todas as ferramentas disponíveis sempre que escrever e mantiver uma Skill. Se quiser saber mais, o site Agent Skills tem muitos bons exemplos, e tanto o nosso repositório interno como o ecossistema público contêm muitos exemplos de Skills bem concebidas.

Citação

@online{perplexity2026DesigningRefiningAndMaintainingAgentSkillsAtPerplexity,
  author = {{Perplexity} and Marshall Kiely and Daisy Lee and Jerry Ma and Lauren Kolm},
  title = {{Designing, refining, and maintaining agent skills at Perplexity}},
  date = {2026-05-01},
  url = {https://www.perplexity.ai/hub/blog/designing-refining-and-maintaining-agent-skills-at-perplexity}
}