Projetando, refinando e mantendo agent skills na Perplexity

Os produtos de agentes de fronteira da Perplexity baseiam-se em uma fundação de know-how e especialização em domínio empacotados em Agent Skills modulares. Mantemos uma biblioteca cuidadosamente curada de Skills em nossos ambientes técnicos. Essas Skills incluem muitos dos utilitários de uso geral que alimentam 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 do usuário. Algumas Skills são invocadas raramente, mas são críticas quando invocadas. Para garantir uma experiência de usuário consistentemente excelente, a equipe de Agents da Perplexity prioriza a qualidade da Skill tanto quanto a qualidade do código.

As intuições e as melhores práticas necessárias para desenvolver uma Skill de alta qualidade diferem significativamente daquelas necessárias para construir software tradicional. A equipe de Agents analisa muitas pull requests de engenheiros excelentes que desenvolvem Skills durante o 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 se tornam antipadrões na criação de Skills.

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

Cinco contrastes entre o Zen of Python e a orientação do artigo para escrever Skills.

Este guia é o documento que os engenheiros em toda a Perplexity usam ao desenvolver e revisar Skills. Também estamos lançando este guia para o público para que nossas descobertas e aprendizados possam beneficiar a comunidade em geral. Seja você um engenheiro projetando Skills de produção em seu trabalho diário, um usuário do Computer que deseja 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, não está escrevendo software comum e antigo (mesmo que as Skills façam 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 faz com código, você vai 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 a 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 Skills muito focadas e restritas, e pode-se usar a estrutura de pastas de uma maneira muito criativa. Às vezes, Skills particularmente intrincadas se beneficiam de vários 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 de forma confiável o tópico certo entre 300 é um desafio não resolvido, mesmo para os melhores modelos de fronteira de hoje. É um problema de escolha muito mais fácil para um modelo concentrar-se em uma de 20 áreas do que entre os 15 tópicos dentro dessa área.

Como um exemplo de como a hierarquia multinível fornece valor, nossa equipe empregou três níveis de aninhamento tópico dentro das Skills que alimentam as capacidades de imposto de renda dos EUA do Computer nesta última temporada de impostos. Essa hierarquia era absolutamente indispensável dada a complexidade da legislação tributária: em nossos testes iniciais, apresentar ao modelo uma única pasta contendo todas as 1.945 seções do Código da Receita Federal dos EUA resultou em pior desempenho do que não carregar a Skill. 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 de 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. Neste caso, fazer o trabalho difícil de curadoria acabou produzindo um resultado final positivo: uma Skill que permitiu aos modelos executar tarefas relacionadas a impostos com muito mais capacidade do que usando ferramentas gerais sozinhas.

Expandir

Uma Skill é um Formato

Uma Skill é um formato. O arquivo raiz principal 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 qual a Skill está localizada. O nome deve consistir inteiramente de caracteres minúsculos, não ter espaços 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", e 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 Skills 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 maneira específica para esses sistemas. Como alternativa, metadados específicos de Skill podem ser empacotados em um arquivo de configuração auxiliar JSON ou YAML. 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, comportamento semelhante é obtenível através da remoção do frontmatter da Skill na leitura. O Computer emprega essa metodologia, o que permite que a configuração seja preservada no arquivo raiz SKILL.md. É necessária 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 são ú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 Skills nem sempre são agrupadas no contexto. Por padrão, a maioria dos sistemas de agentes desdobra as Skills progressivamente mediante necessidade específica.

Existem pelo menos três níveis de custos de contexto na maneira como implementamos Skills 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 optar por expor o conteúdo da Skill de diferentes maneiras. Como exemplo, alguns sistemas podem optar por 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 optar por 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 por base 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 em todos os três em vários estágios:

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

O Computer constrói um índice de Skills que possui 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 restrito porque você está pagando esse custo em cada sessão, para cada usuário. Isso é injetado no prompt do sistema bem no início da conversa. O modelo tem acesso a um monte de Skills nomeadas e descrições para que possa decidir se deve chamar "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 de 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é você atingir o limite de compactação. Muitas threads carregam entre três e cinco Skills diferentes, multiplicando esse custo. Skills com muita gordura quase certamente degradarão outras Skills, bem como as capacidades agênticas gerais. Em suma, se a sua Skill carrega e não faz a coisa certa, isso é contexto desperdiçado.

O nível final de progressão são scripts ou casos especiais, como subskills ou formatação. É aqui que você deseja colocar lógica ramificada condicional ilimitada. O agente só a usará quando precisar, o que significa que há uma barra muito mais baixa para o que você deseja 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.

Quando você precisa de uma Skill?

A equipe de Agents é frequentemente solicitada a opinar sobre se uma Skill é realmente necessária para um determinado domínio ou caso de uso. Muito raramente temos uma resposta definitiva apenas a partir de princípios fundamentais. A única maneira de realmente descobrir isso é começar com seu agente sem a Skill, executar várias consultas de herói e, em seguida, 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 alterar esse comportamento de alguma maneira específica que você não pode com, digamos, uma frase no seu prompt. Portanto, você precisa de uma Skill quando o agente errar sem um contexto especial, ou se houver alguma inconsistência ou não determinismo que você precise manter extremamente consistente entre 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 Skills relacionadas a design no Computer escritas por Henry Modisett (nosso chefe de design). A razão pela qual cada token existe nessas Skills é porque Henry tem um gosto muito bom quando se trata de projetar sites e PDFs. Henry especifica quais fontes usar e quais fontes não usar, como essas fontes se sentem, e outros assuntos de julgamento que o modelo não pode aprender apenas com dados de treinamento.

Quando você não precisa de uma Skill

Vemos muitas Skills 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 resulta em uma ótima documentação, mas uma Skill ruim.

Vemos exemplos em que as Skills 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 houver algo mudando mais rápido do que você pode manter, você não precisa de uma Skill. Por exemplo, se você estiver acessando algum endpoint MCP remoto e suas ferramentas ou as versões dessas ferramentas estiverem mudando com frequência, você não deve injetar isso em uma Skill. Se fizer isso, 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 precisar estar lá, ela não pode se dar ao luxo de estar lá porque todos estão pagando esse custo todas as vezes. Ao decidir se deve adicionar uma Skill ou não, lembre-se desse imposto em que 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 "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 a sua Skill for fácil de escrever, provavelmente é muito longa ou não deveria existir. Uma Skill boa é o mais curta possível.

Se você se pegar tentando gerar uma Skill de uma só vez e publicando PRs em cinco minutos, os resultados serão quase certamente abaixo do esperado. De fato, pesquisas iniciais mostraram que, se você estiver usando LLMs para escrever Skills, o LLM provavelmente não se beneficiará com isso: "Skills autogeradas não oferecem nenhum benefício em média, mostrando que os modelos não conseguem autorizar de forma confiável o conhecimento procedural do qual se beneficiam ao consumir."

Como construir uma Skill

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

Passo 0: Escreva as Evals

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

Consultas reais de usuários: amostras da produção ou do seu grupo 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 roteia para outra Skill

No mínimo, você deve garantir que está testando se a Skill é carregada 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ê se propôs a escrever a Skill seja devido a 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 importa 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 um pouco 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 ela é útil. Uma descrição boa diz quando o agente deve carregar a Skill. Por exemplo, digamos que você tenha algo para monitorar pull requests. 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", "watch CI" ou "make sure this lands".

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

Começa com "Load when..."

Almeje 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. Normalmente, dois ou três exemplos funcionam bem. Não é fácil adicionar exatamente e apenas o máximo que 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 o 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 uma explicação passo a passo de alguém com experiência e aprender a usar a ferramenta. Enquanto isso, para quase qualquer ferramenta de software que exista há pelo menos um ano, você só precisa mencionar seu nome e o LLM tem todas as informações de que precisa.

Quando você estiver escrevendo 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 novamente quando você está escrevendo uma Skill porque parece que você está escrevendo documentação, mas se você fizer isso, sua Skill será 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 para uma ramificação limpa. Resolva conflitos preservando a intenção. Se não puder ser integrado limpidamente, explique o motivo."

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 derem errado. Não seja autoritário nem excessivamente prescritivo, o que é frágil; em vez disso, seja flexível onde múltiplas abordagens possam funcionar. Novamente, uma boa documentação para humanos é mais frequentemente uma documentação ruim para modelos.

Em seguida, concentre-se nos gotchas ou exemplos negativos. Estes são conteúdos de altíssimo sinal porque frequentemente 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-o e os gotchas crescerão organicamente.

Por fim, se houver alguma porção que seja condicional ou extremamente pesada em conteúdo, retire-a do SKILL.md, que é o hub, e coloque-a em um dos spokes. Coloque-a em um arquivo acessório que possa ser carregado progressivamente, no qual mergulharemos em seguida.

Passo 3: Use a Hierarquia

Faça uso da hierarquia de Skills 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 uma Skill.

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

Passo 4: Iterar

Em seguida, faça um monte de iterações em uma ramificação. Comece na ramificação principal sem nenhuma Skill, faça algumas iterações, construa seu conjunto de consultas de herói e execute uma série de evals. Qualquer pessoa que revise o seu código de Skill agradecerá por você enviar um único conjunto de alterações completo com um conjunto de avaliação. Revisar alterações incrementais consecutivas (exceto um novo gotcha) é muito difícil, então tente minimizar isso.

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

Passo 5: Enviar

Envie.

Como Manter uma Skill

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

O Volante dos Gotchas

A partir deste ponto, sua lista de gotchas tende a crescer ou mudar muito. Frequentemente vemos engenheiros que fazem PRs que não foram avaliados, por exemplo, alterar a descrição. Se você estiver alterando a descrição após a sua Skill ter sido mesclada, você está fora do caminho. Se você estiver fazendo alterações na coisa que decide se deve rotear sua Skill, você precisa escrever algumas evals que apoiem as alterações.

As Skills são principalmente de adição. A seção de gotchas acumula o maior valor ao longo do tempo:

O agente falha em algo → Adicionar um gotcha

O agente carrega a Skill fora do alvo → Ajustar a descrição e adicionar evals negativos

O agente não carrega a Skill quando deveria → Adicionar palavras-chave e evals positivos

O prompt do sistema muda → Verificar contenda ou duplicação

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

À medida que você passa de 80-20 para alcançar uma taxa de sucesso de 99,9% ou 99,99%, é fácil fazer essa lista de gotchas crescer. Conforme você vê esses exemplos negativos, você deve adicionar principalmente à seção de gotchas. Você não deve adicionar instruções mais longas ou alterar a descrição.

Suítes de Evals

Na Perplexity, executamos muitas suítes de eval para verificar diferentes coisas. Há o carregamento de Skills e leituras de arquivos de Skills, o que verifica a precisão, o recall e as verificações proibidas do carregamento da Skill em si. O agente roteará sua Skill quando supostamente deveria? Isso garante que novas Skills não quebrem limites existentes.

Também há evals 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ê tiver uma Skill de finanças para consultas financeiras, ela lê o arquivo especial FORMATTING.md?

Também há evals para Skills que testam a conclusão de tarefas de ponta a ponta dentro de 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 evals contra diferentes modelos. O Computer suporta pelo menos três famílias de modelos de orquestração diferentes: GPT, Claude Opus e Claude Sonnet. Você deseja executar o carregamento da sua Skill e as Skills de domínio contra esses diferentes orquestradores de agentes para garantir que você não obtenha um comportamento diferente. Sonnet e GPT se comportam de maneira bastante diferente quando se trata de Skills.

Considerações finais e conclusões

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

O ato de construir Skills torna você melhor em construir mais Skills, mas além disso, elas são extremamente boas em automatizar processos de negócios. Se você puder descrever algo que faz toda semana antes do seu standup, no 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 o seu tempo.

Você pode automatizar post-mortems? Você pode revisar pull requests? Qualquer tarefa que você possa fazer, você pode pelo menos ter a primeira passagem como uma Agent Skill. Isso lhe poupará tempo significativo.

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

Escreva evals antes da Skill. Inclua exemplos negativos e carregamentos proibidos para skills adjacentes, mas distintas.

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

Gotchas são conteúdo de altíssimo valor. Comece enxuto, cresça conforme o agente falha.

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

Use todas as ferramentas disponíveis todas as vezes que você estiver escrevendo e mantendo uma Skill. Se você quiser saber mais, o site de Agent Skills tem muitos exemplos bons, e tanto nosso repositório interno quanto o ecossistema público contêm muitos exemplos de Skills 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://perplexity.coolkeypoint.com/hub/blog/designing-refining-and-maintaining-agent-skills-at-perplexity}
}