Projetando, refinando e mantendo Skill de agentes na Perplexity

Os produtos de agentes de fronteira da Perplexity baseiam-se em uma fundação de know-how e especialização de domínio empacotados em Skills modulares. Mantemos uma biblioteca cuidadosamente selecionada de Skill em nossos ambientes técnicos. Essas Skill incluem muitos dos utilitários de propósito geral que impulsionam o Perplexity Computer; capacidades específicas de verticais em áreas como finanças, direito e saúde; e uma cauda muito longa de módulos para atender às necessidades dos usuários. Algumas Skill são invocadas com pouca frequência, mas são críticas quando invocadas. Para garantir uma experiência de usuário consistentemente excelente, a equipe de Agentes da Perplexity prioriza a qualidade da Skill tanto quanto a qualidade do código.

As intuições e melhores práticas necessárias para desenvolver uma Skill de alta qualidade diferem significativamente daquelas necessárias para criar softwares tradicionais. A equipe de Agentes revisa muitas solicitações de pull de excelentes engenheiros que desenvolvem Skill no curso de seu trabalho. O resultado é quase sempre inúmeros comentários e sugestões de revisão. Isso ocorre porque muitos padrões úteis para escrever código tornam-se antipadrões na criação de Skill.

Por exemplo, se você pegar alguns dos aforismos do PEP20 – O Zen do Python, torna-se rapidamente claro que escrever um bom código Python é diferente de escrever boas Skill. Das 20 linhas de sabedoria, pelo menos metade estão completamente erradas ou ativamente enganosas ao escrever Skill. Aqui estão cinco delas:

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

Este guia é o documento que os engenheiros da Perplexity usam ao desenvolver e revisar Skill. Também estamos lançando este guia ao público para que nossas descobertas e aprendizados possam beneficiar a comunidade em geral. Quer você seja um engenheiro projetando Skill de produção no seu trabalho diário, um usuário do Computer procurando desenvolver sua própria Skill em uma área que você conhece melhor, ou ambos, este guia é para você.

O que é uma Skill?

Quando você escreve uma Skill, você não está escrevendo um software comum (embora as Skill sejam agora parte dos principais motores lógicos para sistemas de agentes). Em vez disso, você está construindo contexto para modelos e seus ambientes. Uma Skill tem restrições diferentes e princípios de design diferentes. Se você escrever uma Skill como escreve código, você falhará.

Uma Skill é pelo menos quatro coisas, especialmente no contexto de como as construímos na Perplexity.

Uma Skill é um diretório

Uma Skill não é apenas um único arquivo SKILL.md. Em muitos casos, uma Skill inclui vários arquivos. Sob o diretório nomeado após sua Skill, você pode ter:

SKILL.md: frontmatter e instruções

scripts/: código que o agente executa, não reinventa

references/: documentos pesados, carregados condicionalmente

assets/: modelos, esquemas e dados

config.json: configuração do usuário na primeira execução

Este padrão hub-and-spoke permite que você mantenha as Skill muito focadas e concisas, e pode-se usar a estrutura de pastas de uma forma muito criativa. Às vezes, Skill particularmente complexas se beneficiam de múltiplos níveis de hierarquia para ajudar o modelo a navegar melhor. Suponha que uma Skill exija conhecimento em 300 tópicos, agrupáveis em 20 áreas temáticas. Escolher confiavelmente o tópico certo entre 300 é um desafio não resolvido, mesmo para os melhores modelos de fronteira atuais. É um problema de escolha muito mais fácil para um modelo focar em uma das 20 áreas, do que entre os 15 tópicos dentro dessa área.

Como exemplo de como a hierarquia multinível fornece valor, nossa equipe empregou três níveis de aninhamento tópico dentro das Skill que impulsionam as capacidades de imposto de renda dos EUA do Computer nesta última temporada de impostos. Essa hierarquia foi absolutamente indispensável dada a complexidade da lei tributária: em nossos primeiros testes, apresentar ao modelo uma única pasta contendo todas as 1.945 seções do Código da Receita Federal dos EUA resultou em um desempenho pior do que não carregar a Skill de forma alguma. Organizar as informações em subdivisões lógicas foi indispensável para garantir operações de leitura de alta precisão.

No entanto, essa hierarquia não veio de graça. Níveis crescentes de hierarquia exigem níveis crescentes de curadoria em toda a arquitetura da informação para gerenciar a indireção resultante. Criamos guias de referência rápida, utilitários de pesquisa personalizados e outras ferramentas para apoiar o modelo na localização de informações com um mínimo de indireção. Nesse caso, fazer o trabalho árduo de curadoria produziu, em última análise, um resultado final positivo: uma Skill que permitiu que os modelos realizassem tarefas relacionadas a impostos de forma muito mais capaz do que usando ferramentas gerais apenas.

Expandir

Uma Skill é um formato

Uma Skill é um formato. O arquivo raiz central SKILL.md deve ter um nome e uma descrição. Além disso, a Skill precisa mapear exatamente para o nome do diretório em que a Skill está localizada. O nome deve conter apenas caracteres minúsculos, não ter Espaço e pode usar hífens. A descrição é o gatilho de roteamento. Este é um ponto de falha comum: a descrição não é documentação interna para o que a Skill faz. Equivale a instruções para o modelo sobre quando carregar a Skill. Portanto, você verá frequentemente “Carregar quando”, não “Esta Skill faz”. Isso é importante por causa da maneira como a maioria das implementações injeta a descrição no contexto do modelo.

Dentro do frontmatter, há também “depends:”, que permite criar dependências de Skill hierárquicas, e “metadata:”, que é usado para revisões e avaliações. Diferentes sistemas de agentes podem até definir seus próprios campos de frontmatter, para serem usados de uma maneira específica para esses sistemas. Como alternativa, metadados específicos da Skill podem ser empacotados em um arquivo de configuração JSON ou YAML auxiliar. Isso é desejável ao construir sistemas de agentes que precisam facilitar diferentes tipos de comportamento de tempo de execução por Skill sem poluir o contexto do modelo com minúcias. Finalmente, um comportamento semelhante é obtenível através da remoção do frontmatter da Skill na leitura. O Computer emprega esta metodologia, que permite que a configuração seja preservada no arquivo raiz SKILL.md. É necessária uma atenção cuidadosa aos detalhes na lógica de análise, e pode-se desejar implementar a remoção condicional se houver certos campos que sejam úteis para ter dentro do contexto do modelo.

Uma Skill é invocável

Uma Skill é invocável. O agente carrega uma Skill em tempo de execução. É importante ressaltar que as Skill nem sempre são agrupadas no contexto. Por padrão, a maioria dos sistemas de agentes desdobra as Skill progressivamente conforme a necessidade específica.

Existem pelo menos três níveis de custos de contexto na maneira como implementamos Skill no Computer. Aqui está o processo:

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

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

O Computer carrega automaticamente de forma recursiva as dependências na tag “depends:”

O Computer então remove o frontmatter e o agente, portanto, vê apenas o corpo e os arquivos adicionais

Diferentes sistemas de agentes podem escolher expor o conteúdo da Skill de diferentes maneiras. Como exemplo, alguns sistemas podem escolher não expor a hierarquia de arquivos de forma alguma, deixando para o modelo descobrir a hierarquia através de operações de sistema de arquivos. Outros sistemas podem escolher dar ao modelo um mapeamento de toda a árvore de arquivos até um certo limite de truncamento e/ou profundidade. Para manter o contexto limpo, o Computer omite hierarquias de arquivos completas do contexto de invocação; no entanto, isso é substituível com base em cada Skill.

Uma Skill é progressiva

As Skill são progressivas. No Computer, existem três níveis diferentes de custos de contexto, e incorremos em todos os três em vários estágios:

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

O Computer constrói um índice de Skill que tem o nome e a descrição para cada Skill disponível. O orçamento para isso é de cerca de 100 tokens por Skill (mais curto é ainda melhor). É tão apertado porque você paga esse custo em toda Sessão, para cada usuário. Isso é injetado no prompt do sistema logo no início da conversa. O modelo tem acesso a um monte de Skill nomeadas e descrições para que possa decidir se chama “load_skill()”. A barra para entrar neste índice é extremamente alta. Sua Skill precisa ser muito útil, e a descrição precisa ser extremamente densa e concisa porque todos estão pagando o custo o tempo todo.

Depois que o sistema de agentes carrega a Skill, há o corpo completo do SKILL.md. Idealmente, o texto do corpo não excede 5.000 tokens. Mesmo assim, você quer que cada frase importe, porque uma vez que você carrega uma Skill, o resto da conversa tem que pagar isso até que você atinja o limite de compactação. Muitos tópicos carregam entre três e cinco Skill diferentes, multiplicando esse custo. Skill com muita informação desnecessária quase certamente degradarão outras Skill, bem como as capacidades agenticas gerais. Em suma, se sua Skill carrega e não faz a coisa certa, é contexto desperdiçado.

O nível final de progressão são scripts ou casos especiais, como sub-skill ou formatação. É aqui que você quer colocar a lógica ramificada condicional sem limites. O agente só a usará quando precisar, o que significa que há uma barra muito mais baixa para o que você quer colocar aqui.

No índice, cada token é importante. O corpo da Skill carregada é mais relaxado, e o tempo de execução é o mais relaxado. Isso pode ser 20.000 tokens ou zero tokens. Este é o nível em que você pode pensar em expandir o contexto do modelo de forma progressiva. O Raciocínio pode ser útil aqui.

Quando você precisa de uma Skill?

A equipe de Agentes é frequentemente solicitada a opinar se uma Skill é verdadeiramente necessária para um determinado domínio ou caso de uso. Muito raramente temos uma resposta definitiva apenas a partir dos primeiros princípios. A única maneira de realmente descobrir isso é começar com seu agente sem a Skill, executar várias consultas de herói e, então, descobrir se o agente está fazendo um bom trabalho.

Quando você precisa de uma Skill

Existem muitas tarefas que estão na distribuição para modelos treinados. Você só precisa aplicar uma Skill se quiser mudar esse comportamento de alguma forma específica que não consegue com, digamos, uma frase no seu prompt. Então, você precisa de uma Skill quando o agente errará sem contexto especial, ou se houver alguma inconsistência ou não-determinismo que você precise ser extremamente consistente em todas as execuções.

Pode ser que seu conhecimento seja durável, mas não esteja nos dados de treinamento. Pode haver limites ou fluxos de trabalho específicos da empresa, ou pode ser uma questão de gosto. Por exemplo, temos várias Skill relacionadas ao design no Computer escritas por Henry Modisett (nosso chefe de design). A razão pela qual cada token existe nessas Skill é porque Henry tem muito bom gosto quando se trata de projetar sites e PDFs. Henry especifica quais fontes usar e quais fontes não usar, como essas fontes transmitem uma sensação, e outras questões de julgamento que o modelo não pode aprender apenas com os dados de treinamento.

Quando você não precisa de uma Skill

Vemos muitas Skill em que os engenheiros escreveram uma série de comandos git que precisam ser executados em ordem. Isso é desnecessário porque o modelo já sabe como fazer isso, o que significa que se torna uma ótima documentação, mas uma Skill ruim.

Vemos exemplos em que as Skill recapitulam instruções do prompt do sistema. Você não precisa de uma Skill para isso. O conhecimento relevante para a maioria das solicitações deve ser incluído no contexto global, não em uma Skill carregada condicionalmente.

Se há algo que está mudando mais rápido do que você pode manter, você não precisa de uma Skill. Por exemplo, se você está acessando algum endpoint MCP remoto e suas ferramentas ou as versões dessas ferramentas estão mudando frequentemente, você não deve injetá-las em uma Skill. Se o fizer, você acabará apenas com desvio e o modelo cometerá erros.

Toda Skill é um imposto

Aqui está um teste útil que você pode aplicar a cada frase na sua Skill: “O agente erraria isso sem esta instrução?” Se a frase não precisa estar lá, ela não pode se dar ao luxo de estar, porque todos estão pagando esse custo todas as vezes. Ao decidir se adiciona uma Skill ou não, lembre-se desse imposto onde cada Sessão e cada usuário custam tokens.

A seguinte citação famosa, que soa muito melhor em francês, traduz-se aproximadamente como “Eu só fiz esta carta mais longa porque não tive tempo de torná-la 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

Assim como Pascal, você precisa investir tempo em cada Skill. É difícil escrever uma Skill curta. Se sua Skill é fácil de escrever, provavelmente é muito longa ou não deveria existir. Uma boa Skill é o mais curta que puder ser.

Se você se encontrar tentando gerar uma Skill de uma só vez e enviando PRs em cinco minutos, os resultados serão quase certamente inferiores. Na verdade, pesquisas iniciais mostraram que, se você estiver usando LLMs para escrever Skill, o LLM provavelmente não se beneficiará disso: “As Skill autogeradas não oferecem nenhum benefício em média, mostrando que os modelos não podem autorar confiavelmente o conhecimento procedimental do qual eles se beneficiam ao consumir.”

Como construir uma Skill

Colocando de outra forma, você precisa injetar sua opinião em qualquer Skill que escrever. Siga estes passos.

Passo 0: Escreva as Evals

Escreva algumas das avaliações primeiro. Você pode obter casos de avaliação de:

Consultas reais de usuários: amostra da produção ou de sua base de confiança

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

Confusão de vizinhos: Perto do limite do seu domínio, mas direciona para outra Skill

No mínimo, você deve ter certeza de que está testando se a Skill carrega quando necessário. Idealmente, você amostra algumas delas, talvez de um ambiente de produção. Você também pode considerar casos de erro conhecidos: talvez toda a razão pela qual você decidiu escrever a Skill seja por causa de uma falha específica que você notou ou talvez você esteja refatorando e haja alguma confusão em dois domínios próximos que são cobertos por uma Skill.

Comece com exemplos negativos e positivos semelhantes. Exemplos negativos são extremamente poderosos e podem importar mais do que exemplos positivos.

Passo 1: A Descrição

Esta é a linha mais difícil na Skill. É um gatilho de roteamento, não documentação. Para acertar o nome e a descrição, você não se importa com o conteúdo da Skill. Você só se preocupa se a Skill é carregada e injetada nos pontos certos e está livre de efeitos colaterais fora do alvo, que é o modo de falha número um. Toda vez que você adiciona uma Skill adicional, você corre o risco de tornar cada outra Skill ligeiramente pior, então você precisa garantir que está minimizando a regressão.

Novamente, uma descrição ruim descreve o que a Skill faz ou por que é útil. Uma boa descrição diz quando o agente deve carregar a Skill. Por exemplo, digamos que você tenha algo para monitorar solicitações de pull. Não escreva o que a Skill faz. Escreva o que os engenheiros dizem quando estão frustrados e querem que você garanta que o PR deles funcione, como “babysit” ou “watch CI” ou “make sure this lands.”

Aqui está uma lista de verificação rápida:

Começa com "Load when..."

Tente 50 palavras ou menos

Descreve a intenção do usuário, idealmente a partir de consultas reais

Não resume o fluxo de trabalho

Consultas reais são o que você pode cobrir em um 80-20. Geralmente, dois ou três exemplos funcionam bem. Não é fácil adicionar exatamente e apenas o quanto você precisa.

Passo 2: Escreva o Corpo

Em seguida, escreva o conteúdo da própria Skill. Note que este não é o Passo 0 ou Passo 1.

Comunicar fluxos de trabalho a um LLM é completamente diferente de comunicar fluxos de trabalho a um colega, ou mesmo ao seu sistema de tempo de execução. Ao aprender uma nova ferramenta de software, um engenheiro pode precisar ler a documentação, obter um passo a passo de alguém com experiência e aprender a usar a ferramenta. Enquanto isso, para quase qualquer ferramenta de software que existe há pelo menos um ano, você só precisa mencionar seu nome e o LLM tem todas as informações de que precisa.

Ao escrever o corpo, pule as coisas óbvias. Muitos engenheiros têm muita experiência escrevendo arquivos readme.md que listam todos os comandos que alguém precisa executar. É fácil cair nisso quando você está escrevendo uma Skill porque parece que você está escrevendo documentação, mas se você fizer isso, sua Skill será um lixo. Portanto, não escreva uma série de comandos.

Por exemplo, você não precisa escrever, “git log # find the commit; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;”

Em vez disso, escreva, “Cherry-pick o commit em um branch limpo. Resolva conflitos preservando a intenção. Se não puder ser finalizado de forma limpa, explique por quê.”

O modelo fará um trabalho muito melhor com o último do que com a série de comandos excessivamente prescritiva do primeiro, especialmente quando as coisas dão errado. Não force, ou seja excessivamente prescritivo, o que é frágil, e em vez disso seja flexível onde várias abordagens podem funcionar. Novamente, uma boa documentação para humanos é, na maioria das vezes, uma documentação ruim para modelos.

Em seguida, concentre-se nos problemas ou exemplos negativos. Esses são conteúdos de sinal extremamente alto porque muitas vezes orientam o modelo em termos do que não fazer. Se você adicionar uma linha cada vez que o agente tropeçar, você aprenderá executando-a e os problemas crescerão organicamente.

Por último, se houver alguma parte que seja condicional ou extremamente pesada em conteúdo, tire-a do SKILL.md, que é o hub, e coloque-a em um dos spokes. Coloque-a em um arquivo acessório que pode ser carregado progressivamente, que veremos a seguir.

Passo 3: Use a Hierarquia

Faça uso da hierarquia de Skill quando você tiver um script, referências, ou estiver usando alguma ferramenta específica:

Usos sugeridos para scripts, referências, ativos e configuração dentro de um Skill.

Para qualquer coisa que seja condicional ou ramificada da Skill principal, separe-a em uma pasta. Lembre-se, também, de que a hierarquia multinível pode ser usada para Skill particularmente intrincadas. Para essas, você vai querer pensar cuidadosamente sobre se a funcionalidade deve ser implementada de forma monolítica ou como uma coleção de Skill (talvez com relacionamentos de carregamento baseados em depends:).

Passo 4: Itere

Em seguida, faça várias iterações em um branch. Comece no branch principal sem Skill, faça algumas iterações, construa seu conjunto de consultas de herói e execute uma série de avaliações. Qualquer pessoa que revise seu código de Skill agradecerá por enviar um único conjunto de alterações completo com um conjunto de avaliação. Revisar alterações incrementais consecutivas (exceto um novo problema) é muito difícil, então tente minimizá-las.

Você provavelmente fará muitas pequenas alterações de palavras. Pequenas alterações de palavras nas descrições podem ter um impacto desproporcional no roteamento (incluindo efeitos de transbordamento em outras Skill), então faça todo esse trabalho antes do Passo 5.

Passo 5: Publique

Publique-a.

Como manter uma Skill

Agora que você escreveu uma Skill, você precisa mantê-la.

O Volante dos Problemas

A partir deste ponto, sua lista de problemas tende a crescer ou mudar muito. Muitas vezes vemos engenheiros que fazem PRs que não são avaliados, por exemplo, mudam a descrição. Se você está mudando a descrição após sua Skill ter sido mesclada, você está fora do caminho. Se você está fazendo alterações na coisa que decide se deve rotear sua Skill, você precisa escrever algumas avaliações que suportem as alterações.

As Skill são majoritariamente de acréscimo. A seção de problemas acumula mais valor ao longo do tempo:

O agente falha em algo → Adicione um problema

O agente carrega a Skill fora do alvo → Aperfeiçoe a descrição e adicione avaliações negativas

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

O prompt do sistema muda → Verifique se há contenção ou duplicação

É fácil notar um único caso de falha em testes internos ou em produção e adicionar um problema. É um exemplo negativo, então não está realmente mudando a orientação explícita, mas permite que o modelo saiba: “Ei, há essa falha conhecida.”

À medida que você passa do 80-20 para atingir uma taxa de sucesso de 99,9% ou 99,99%, é fácil aumentar essa lista de problemas. Ao ver esses exemplos negativos, você deve estar adicionando majoritariamente à seção de problemas. Você não deve estar adicionando instruções mais longas ou alterando a descrição.

Conjuntos de Avaliação

Na Perplexity, executamos muitos conjuntos de avaliação para verificar coisas diferentes. Existem o carregamento de Skill e leituras de arquivos de Skill, que verificam a precisão, recall e verificações proibidas do carregamento da Skill em si. O agente roteará sua Skill quando deveria? Isso garante que novas Skill não quebrem limites existentes.

Também existem avaliações que podem verificar o carregamento progressivo adequado. O agente pode carregar a Skill, mas ele lê o arquivo ou arquivos acessórios? Por exemplo, se você tem uma Skill de finanças para consultas financeiras, ele lê o arquivo especial FORMATTING.md?

Também existem avaliações para Skill que testam a conclusão de tarefas de ponta a ponta dentro dos domínios. Executamos o loop completo do agente e usamos um juiz LLM para avaliar os resultados com base em uma rubrica de critérios bem definidos.

Finalmente, é importante executar essas avaliações contra diferentes modelos. O Computer suporta pelo menos três famílias diferentes de modelos de orquestração: GPT, Claude Opus e Claude Sonnet. Você deseja executar o carregamento da sua Skill e as Skill de domínio contra esses diferentes orquestradores de agentes para garantir que você não obtenha comportamentos diferentes. Sonnet e GPT se comportam de maneira bastante diferente quando se trata de Skill.

Reflexões finais e lições aprendidas

Quanto mais Skill você construir, melhor você ficará em construí-las. Se você não está automatizando ou tentando tornar mais reprodutíveis as tarefas que você faz no dia a dia usando Skill, comece imediatamente.

O ato de construir Skill torna você melhor em construir mais Skill, mas também, elas são extremamente boas em automatizar processos de negócios. Se você pode descrever algo que você faz toda semana antes da sua reunião rápida, ao final de cada sprint, ou qualquer coisa que você faça como engenheiro em uma base diária, semanal ou mesmo trimestral, você deve estar escrevendo uma Skill para recuperar seu tempo.

Você pode automatizar postmortems? Você pode revisar pull requests? Qualquer tarefa que você possa fazer, você pode, pelo menos, ter a primeira passagem como uma Skill de Agente. Isso economizará um tempo significativo.

Dito isso, lembre-se de que uma Skill não é fácil ou mesmo sempre necessária. Menos é mais. Algumas outras lições aprendidas:

Escreva avaliações antes da Skill. Inclua exemplos negativos e carregamentos proibidos para skill adjacentes, mas distintas.

A descrição é a parte difícil. "Carregar quando..." (cada palavra custa atenção).

Problemas são conteúdo de valor extremamente alto. Comece magro, cresça conforme o agente falha.

Lembre-se de que é fácil quebrar outras Skill pré-existentes adicionando uma nova Skill, mesmo que você não a tenha tocado (cuidado com a ação à distância).

Use todas as ferramentas disponíveis toda vez que estiver escrevendo e mantendo uma Skill. Se você quiser saber mais, o site de Agent Skills tem muitos bons exemplos, e tanto nosso repositório interno quanto o ecossistema público contêm muitos exemplos de Skill bem projetadas.

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}
}