Deseño, refinamento e mantemento de agent skills en Perplexity

Os produtos de axentes de vangarda de Perplexity baséanse nun cimento de coñecemento e experiencia no dominio empacados en Agent Skills modulares. Mantemos unha biblioteca coidadosamente seleccionada de Skills nos nosos entornas técnicas. Estas Skills inclúen moitas das utilidades de propósito xeral que alimentan Perplexity Computer; capacidades específicas de verticais en áreas como finanzas, dereito e saúde; e unha cola moi longa de módulos para atender as necesidades dos usuarios. Algunhas Skills invocáranse con pouca frecuencia pero son críticas cando se invocar. Para garantir unha experiencia de usuario consistentemente excelente, o equipo de axentes de Perplexity prioriza a calidade das Skills tanto como a calidade do código.

As intuicións e as mellores prácticas necesarias para desenvolver unha Skill de alta calidade difiren significativamente das necesarias para construír software tradicional. O equipo de axentes revisa moitas solicitudes de extracción de enxeñeiros excelentes que desenvolven Skills no curso do seu traballo. O resultado é case sempre numerosos comentarios e suxestións de revisión. Isto débese a que moitos patróns útiles para escribir código convértense en antipatróns na creación de Skills.

Por exemplo, se colles algúns dos aforismos de PEP20 – The Zen of Python, queda rapidamente claro que escribir bo código Python non é como escribir boas Skills. Das 20 liñas de sabedoría, polo menos a metade son completamente erróneas ou activamente enganosas ao escribir Skills. Aquí tes cinco delas:

Cinco contrastes entre o Zen de Python e a orientación do artigo para escribir Skills.

Esta guía é o documento que os enxeñeiros de todo Perplexity usan ao desenvolver e revisar Skills. Tamén estamos a publicar esta guía para o público para que os nosos descubrimentos e aprendizaxes poidan beneficiar á comunidade máis ampla. Tanto se es un enxeñeiro que deseña Skills de produción no seu traballo diario, un usuario de Computer que busca desenvolver a súa propia Skill nunha área que coñece mellor, ou ambos, esta guía é para ti.

Que é unha Skill?

Cando escribes unha Skill, non estás escribindo software vello e sinxelo (aínda que as Skills forman agora parte dos motores lóxicos principais para os sistemas de axentes). Pola contra, estás construíndo contexto para os modelos e os seus contornos. Unha Skill ten diferentes restricións e diferentes principios de deseño. Se escribes unha Skill como o fas con código, fallarás.

Unha Skill son polo menos catro cousas, especialmente no contexto de como as construímos en Perplexity.

Unha Skill é un directorio

Unha Skill non é só un único ficheiro SKILL.md. En moitos casos, unha Skill inclúe varios ficheiros. Baixo o directorio co nome da túa Skill, podes ter:

SKILL.md: frontmatter e instrucións

scripts/: código que executa o axente, non reinventa

references/: documentos pesados, cargados condicionalmente

assets/: modelos, esquemas e datos

config.json: configuración do usuario na primeira execución

Este patrón de cubo e raios permíteche manter as Skills moi enfocadas e axustadas, e pódese usar a estrutura de cartafoles dun xeito moi creativo. Ás veces, as Skills particularmente intrincadas benefícianse de múltiples niveis de hierarquía para axudar ao modelo a navegar mellor. Supoñamos que unha Skill require coñecemento en 300 temas, agrupables en 20 áreas temáticas. Escoller de forma fiable o tema correcto entre 300 é un desafío sen resolver incluso para os mellores modelos de vangarda actuais. É un problema de elección moito máis doado para un modelo centrarse nunha de 20 áreas, que entre os 15 temas desa área.

Como exemplo de como a hierarquía multinivel achega valor, o noso equipo empregou tres niveis de aniuamento de temas dentro das Skills que impulsan as capacidades de imposto sobre a renda dos Estados Unidos de Computer esta tempada de impostos pasada. Esta hierarquía era absolutamente indispensable dada a complexidade do dereito fiscal: nas nosas primeiras probas, presentar ao modelo un único cartafol que contivese as 1.945 seccións do Código de Recepción Interna dos EE. UU. deu lugar a un rendemento peor que non cargar a Skill en absoluto. Organizar a información en subdivisións lóxicas foi indispensable para garantir operacións de lectura de alta precisión.

Con todo, esta hierarquía non veu de balde. Os crecentes niveis de hierarquía requiren crecentes niveis de curación en toda a arquitectura de información para xestionar a indirección resultante. Deseñamos guías de referencia rápida, utilidades de busca personalizadas e outras ferramentas para axudar ao modelo a localizar información cun mínimo de indirección. Neste caso, facer o traballo duro de curación produciu finalmente un resultado final positivo: unha Skill que permitiu aos modelos realizar tarefas relacionadas cos impostos de forma moito máis capaz que usar só ferramentas xerais.

Ampliar

Unha Skill é un formato

Unha Skill é un formato. O ficheiro raíz central SKILL.md debe ter tanto un nome como unha descrición. Ademais, a Skill debe mapear exactamente co nome do directorio no que se atopa a Skill. O nome debe estar todo en minúsculas, non ter espazos e pode usar guións. A descrición é o disparador de encamiñamento. Este é un punto de fallo común: a descrición non é documentación interna do que fai a Skill. Equivale a instrucións para o modelo sobre cando cargar a Skill. Polo tanto, verás con frecuencia "Load when," non "This Skill does." Isto é importante debido á forma en que a maioría das implementacións inxectan a descrición no contexto do modelo.

Dentro do frontmatter, tamén hai "depends:", que che permite crear dependencias xerárquicas de Skills, e "metadata:", que se usa para revisións e avaliacións. Os diferentes sistemas de axentes poden incluso definir os seus propios campos de frontmatter, para ser usados dun xeito específico para eses sistemas. Como alternativa, os metadatos específicos de Skills pódense empaquetar nun ficheiro de configuración JSON ou YAML auxiliar. Isto é deseñable cando se constrúen sistemas de axentes que necesitan facilitar diferentes tipos de comportamento en tempo de execución por Skill sen contaminar o contexto do modelo con minucias. Finalmente, pódese obter un comportamento similar eliminando o frontmatter da Skill na lectura. Computer emprega esta metodoloxía, o que permite que a configuración se conserve no ficheiro raíz SKILL.md. Requírese unha atención coidadosamente aos detalles na lóxica de análise, e pódese desexar implementar a eliminación condicional se hai certos campos que é útil ter dentro do contexto do modelo.

Unha Skill é invocable

Unha Skill é invocable. O axente carga unha Skill en tempo de execución. É importante destacar que as Skills non sempre están agrupadas no contexto. Por defecto, a maioría dos sistemas de axentes despríganse as Skills progresivamente segundo a necesidade específica.

Hai polo menos tres niveis de custos de contexto na forma en que implementamos as Skills en Computer. Aquí está o proceso:

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

Computer copia o directorio da Skill no contorno illado de execución

Computer carga automaticamente de forma recursiva as dependencias na etiqueta "depends:"

Computer despois elimina o frontmatter e o axente, polo tanto, só ve o corpo e os ficheiros adicionais

Os diferentes sistemas de axentes poden elixir expoñer o contido da Skill de diferentes xeitos. Como exemplo, algúns sistemas poden elixir non expoñer a hierarquía de ficheiros en absoluto, deixando que o modelo descubra a hierarquía a través de operacións do sistema de ficheiros. Outros sistemas poden elixir darlle ao modelo un mapeo de toda a árbore de ficheiros ata un certo límite de truncamento e/ou profundidade. Para manter o contexto limpo, Computer omite as hierarquías de ficheiros completas do contexto de invocación; con todo, isto pódese anular por cada Skill.

Unha Skill é progresiva

As Skills son progresivas. En Computer, hai tres niveis diferentes de custos de contexto, e incorremos nos tres en varias etapas:

Os tres niveis do contexto de Skill: índice, carga completa de Skill e ficheiros de referencia en tempo de execución.

Computer constrúe un índice de Skills que ten o nome e a descrición de cada Skill dispoñible. O orzamento para isto é de ao redor de 100 tokens por Skill (máis curto é aínda mellor). É tan axustado porque estás pagando este custo en cada sesión, para cada usuario. Isto inxéctase na indicación do sistema ao comezo da conversación. O modelo ten acceso a un grupo de Skills nomeadas e descricións para que poida decidir se chamar a "load_skill()". O listón para entrar neste índice é extremadamente alto. A túa Skill debe ser moi útil, e a descrición debe ser extremadamente densa e concisa porque todos están a pagar o custo todo o tempo.

Despois de que o sistema de axentes cargue a Skill, está o corpo completo de SKILL.md. Idealmente, o texto do corpo non supera os 5.000 tokens. Mesmo entón, queres que cada frase importe porque unha vez que cargas unha Skill, o resto da conversa ten que pagar iso ata que cheges ao límite de compactación. Moitos fíos cargan entre tres e cinco Skills diferentes, multiplicando este custo. As Skills con moito recheo case con certeza degradarán outras Skills así como as capacidades de axente xerais. En resumo, se a túa Skill se carga e non fai o correcto, iso é contexto desperdiciado.

O nivel final de progresión son scripts ou casos especiais, como subskills ou formato. Aquí é onde queres poñer lóxica ramificada condicional ilimitada. O axente só o usará cando o necesite, o que significa que hai un listón moito máis baixo para o que queres poñer aquí.

No índice, cada token é importante. O corpo da Skill cargada é máis relaxado, e o tempo de execución é o máis relaxado. Isto podería ser 20.000 tokens ou cero tokens. Este é o nivel no que podes pensar en ampliar o contexto do modelo dun xeito progresivo.

Cando necesitas unha Skill?

Ao equipo de axentes pídeselle a miúdo que opine sobre se realmente se necesita unha Skill para un dominio ou caso de uso determinado. Moi raramente temos unha resposta definitiva só a partir de primeiros principios. A única forma de pescudar isto realmente é comezar co teu axente sen a Skill, executar varias consultas de heroe e despois pescudar se o axente está a facer un bo traballo.

Cando necesitas unha Skill

Hai moitas tarefas que están en distribución para modelos adestrados. Só necesitas aplicar unha Skill se queres cambiar ese comportamento dalgunha maneira específica que non podes coa túa indicación, por exemplo, cunha frase. Polo tanto, necesitas unha Skill cando o axente o fará mal sen contexto especial, ou se hai algunha inconsistencia ou non determinismo que necesites que sexa extremadamente consistente entre execucións.

Podería ser que o teu coñecemento sexa duradeiro pero non nos datos de adestramento. Podería haber límites ou fluxos de traballo específicos da empresa, ou podería ser unha cuestión de gustos. Por exemplo, temos varias Skills relacionadas co deseño en Computer escritas por Henry Modisett (o noso xefe de deseño). A razón pola que cada token existe nesas Skills é porque Henry ten moi bo gusto cando se trata de deseñar sitios web e PDFs. Henry especifica que fontes usar e que fontes non usar, como senten esas fontes, e outros asuntos de xuízo que o modelo non pode aprender só dos datos de adestramento.

Cando non necesitas unha Skill

Vemos moitas Skills nas que os enxeñeiros escribiron unha serie de comandos git que deben executarse en orde. Iso é innecesario porque o modelo xa sabe como facer iso, o que significa que é unha gran documentación pero unha mala Skill.

Vemos exemplos onde as Skills recapitulan instrucións da indicación do sistema. Non necesitas unha Skill para iso. O coñecemento relevante para a maioría das solicitudes debe incluírse no contexto global, non nunha Skill cargada condicionalmente

Se hai algo que está a cambiar máis rápido do que o podes manter, non necesitas unha Skill. Por exemplo, se estás a golpear algún extremo remoto de MCP e as súas ferramentas ou as versións desas ferramentas están a cambiar con frecuencia, non deberías inxectar iso nunha Skill. Se o fas, acabarás con desviación e o modelo cometerá erros.

Cada Skill é un imposto

Aquí tes unha proba útil que podes aplicar a cada frase da túa Skill: "Faría o axente isto mal sen esta instrución?" Se a frase non precisa estar aí, non se pode permitir estar aí porque todos están a pagar este custo cada vez. Cando esteas a decidir se engades unha Skill ou non, lembra este imposto no que cada sesión e cada usuario custan tokens.

A seguinte cita famosa, que soa moito mellor en francés, tradúcese aproximadamente como "Só fixen esta carta máis longa porque non tiven o tempo de facela máis 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

Do mesmo xeito que Pascal, necesitas investir tempo en cada Skill. É difícil escribir unha curta Skill. Se a túa Skill é doada de escribir, probablemente sexa demasiado longa ou non debería existir. Unha boa Skill é tan curta como pode ser.

Se te atopas tentando xerar unha Skill nun único intento e poñendo PRs en cinco minutos, os resultados serán case con certeza inferiores. De feito, as primeiras investigacións amosaron que se estás a usar LLMs para escribir Skills, o LLM probablemente non se beneficiará diso: "As Skills xeradas por si mesmas non ofrecen ningún beneficio de media, o que demostra que os modelos non poden autorizar de forma fiable o coñecemento procedimental do que se benefician ao consumir".

Como construír unha Skill

Posto doutro xeito, necesitas inxectar a túa opinión en calquera Skill que escribas. Siga estes pasos.

Paso 0: Escribe as avaliacións

Escribe algunhas das avaliacións primeiro. Podes obter casos de avaliación de:

Consultas de usuarios reais: mostra da produción ou do teu grupo de confianza

Fallos coñecidos: O axente fallou porque a Skill non existía

Confusión de veciños: preto do límite do teu dominio pero encamiña a outra Skill

Como mínimo, deberías asegurarte de probar que a Skill se carga cando é necesario. Idealmente, mostras algunhas destas, quizais dun contorno de produción. Tamén podes considerar casos de erro coñecidos: quizais toda a razón pola que te propuxeches escribir a Skill é debido a un fallo específico que notarías ou quizais estás a refactorizar e hai certa confusión en dous dominios próximos que están cubertos por unha Skill.

Comeza con exemplos negativos e positivos similares. Os exemplos negativos son extremadamente poderosos e poden importar máis que os exemplos positivos.

Paso 1: A descrición

Esta é a liña máis difícil da Skill. É un disparador de encamiñamento, non documentación. Para acertar co nome e a descrición, non che importa o contido da Skill. Só che importa se a Skill está cargada e inxectada nos puntos correctos e está libre de efectos secundarios fóra do obxectivo, que é o modo de fallo número un. Cada vez que engades unha Skill adicional, corres o risco de facer que cada outra Skill sexa un pouco peor, polo que debes asegurarte de minimizar a regresión.

De novo, unha mala descrición describe o que fai a Skill ou por que é útil. Unha boa descrición di cando o axente debe cargar a Skill. Por exemplo, digamos que tes algo para supervisar as solicitudes de extracción. Non escribas o que fai a Skill. Escribe o que din os enxeñeiros cando están frustrados e queren que te asegures de que o seu PR funciona, como "babysit" ou "watch CI" ou "make sure this lands".

Aquí tes unha lista de verificación rápida:

Comeza con "Load when..."

Apunta a 50 palabras ou menos

Describe a intención do usuario, idealmente a partir de consultas reais

Non resume o fluxo de traballo

As consultas reais son o que podes cubrir nun 80-20. Normalmente, dous ou tres exemplos funcionan ben. Non é doado engadir exactamente e só o que necesitas.

Paso 2: Escribe o corpo

A continuación, escribe o contido da propia Skill. Ten en conta que este non é o Paso 0 nin o Paso 1.

Comunicar fluxos de traballo a un LLM é completamente diferente de comunicar fluxos de traballo a un compañeiro, ou incluso ao teu sistema de tempo de execución. Ao aprender unha nova ferramenta de software, un enxeñeiro pode necesitar ler a documentación, obter unha guía de alguén con experiencia e aprender a usar a ferramenta. Mentres tanto, para case calquera ferramenta de software que leva polo menos un ano, só necesitas mencionar o seu nome e o LLM ten toda a información que necesita.

Cando esteas a escribir o corpo, omite as cousas obvias. Moitos enxeñeiros teñen moita experiencia escribindo ficheiros readme.md que enumeran cada comando que alguén necesita executar. É doado volver a iso cando estás a escribir unha Skill porque parece que estás a escribir documentación, pero se fas iso, a túa Skill será lixo. Polo tanto, non escribas unha serie de comandos.

Por exemplo, non necesitas escribir: "git log # find the commit; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;"

No seu lugar, escribe: "Cherry-pick o commit nunha rama limpa. Resolve os conflitos preservando a intención. Se non pode aterrar limpiamente, explica por que".

O modelo fará un traballo moito mellor co segundo que coa serie de comandos excesivamente prescriptiva do primeiro, especialmente cando as cousas van mal. Non encarriles nin sexas demasiado prescriptivo, o que é fráxil, e no seu lugar sé flexible onde múltiples enfoques poden funcionar. De novo, a boa documentación para humanos é a miúdo mala documentación para modelos.

A continuación, céntrate nos problemas ou exemplos negativos. Estes son contido de sinal extremadamente alto porque a miúdo guían ao modelo en termos do que non se debe facer. Se engades unha liña cada vez que o axente tropieza, aprenderás executándoa e os problemas crecerán organicamente.

Por último, se hai algunha porción que sexa condicional ou extremadamente pesada en contido, sácaa do SKILL.md, que é o cubo, e ponna nun dos raios. Pónna nun ficheiro accesorio que se poida cargar progresivamente, no que profundaremos a continuación.

Paso 3: Usa a hierarquía

Fai uso da hierarquía de Skills cando teñas un script, referencias, ou esteas a usar algunha ferramenta específica:

Usos suxeridos para scripts, referencias, activos e configuración dentro dun Skill.

Para calquera cousa que sexa condicional ou que se ramifique desde a Skill principal, divídea nun cartafol. Lembra tamén que a hierarquía multinivel se pode usar para Skills particularmente intrincadas. Para estas, queres pensar coidadosamente sobre se a funcionalidade debe implementarse de forma monolítica ou como unha colección de Skills (quizais con relacións de carga baseadas en depends:).

Paso 4: Itera

A continuación, fai un cheo de iteracións nunha rama. Comeza na rama principal sen ningunha Skill, fai algunhas iteracións, constrúe o teu conxunto de consultas de heroe e executa unha serie de avaliacións. Calquera que revise o teu código de Skill agradecerache que envíes un único conxunto de cambios completo cun conxunto de avaliación. Revisar cambios incrementais consecutivos (ag excepto un novo problema) é moi difícil, así que tenta minimizalo.

Probablemente farás moitos cambios pequenos de palabras. Os pequenos cambios de palabras nas descricións poden ter un impacto desproporcionado no encamiñamento (incluíndo efectos secundarios de desbordamento noutras Skills), así que fai todo ese traballo antes do Paso 5.

Paso 5: Enviar

Envíano.

Como manter unha Skill

Agora que escribiches unha Skill, tes que mantela.

O volante de inercia dos problemas

A partir deste momento, a túa lista de problemas tende a crecer ou cambiar moito. Vemos a miúdo enxeñeiros que fan PRs que non están avaliados, por exemplo, cambian a descrición. Se estás a cambiar a descrición despois de que a túa Skill fose fusionada, estás fóra do camiño. Se estás a facer cambios na cousa que decide se encamiñar a túa Skill, necesitas escribir algunhas avaliacións que admitan os cambios.

As Skills son principalmente de adición. A sección de problemas acumula o maior valor co tempo:

O axente falla en algo → Engade un problema

O axente carga a Skill fóra do obxectivo → Axusta a descrición e engade avaliacións negativas

O axente non carga a Skill cando debería → Engade palabras clave e avaliacións positivas

Cambios na indicación do sistema → Comproba se hai disputas ou duplicación

É doado notar un único caso de fallo nas probas internas ou na produción e engadir un problema. É un exemplo negativo polo que realmente non está a cambiar a orientación explícita, senón que lle fai saber ao modelo: "Ei, hai este fallo coñecido".

A medida que pasas do 80-20 a acadar unha taxa de éxito do 99,9% ou 99,99%, é doado facer crecer esta lista de problemas. A medida que vexas estes exemplos negativos, debes engadir principalmente á sección de problemas. Non debes engadir instrucións máis longas nin cambiar a descrición.

Conxuntos de avaliación

En Perplexity, executamos moitos conxuntos de avaliación para comprobar cousas diferentes. Hai carga de Skills e lecturas de ficheiros de Skills, que comproba a precisión, a recuperación e as comprobacións prohibidas da propia carga de Skills. Encamiñará o axente a túa Skill cando se supón que debe facelo? Estes garanten que as novas Skills non rompan os límites existentes.

Tamén hai avaliacións que poden comprobar a carga progresiva adecuada. O axente pode cargar a Skill, pero le o ficheiro ou ficheiros accesorios? Por exemplo, se tes unha Skill de finanzas para consultas de finanzas, le o ficheiro especial FORMATTING.md?

Tamén hai avaliacións para Skills que proban a finalización de tarefas de extremo a extremo dentro de dominios. Executamos o bucle completo do axente e usamos un xuíz LLM para cualificar os resultados en función dunha rúbrica de criterios ben definidos.

Finalmente, é importante executar estas avaliacións contra diferentes modelos. Computer admite polo menos tres familias de modelos de orquestración diferentes: GPT, Claude Opus e Claude Sonnet. Queres executar a túa carga de Skills e as Skills de dominio contra estes diferentes orquestradores de axentes para garantir que non obtens un comportamento diferente. Sonnet e GPT compórtanse de forma bastante diferente cando se trata de Skills.

Pensamentos finais e conclusións

Cantas máis Skills constrús, mellor serás construíndoas. Se non estás a automatizar ou tentar facer tarefas máis reproducibles que estás a facer no teu día a día usando Skills, comeza inmediatamente.

O acto de construír Skills fainote mellor construíndo máis Skills, pero tamén son extremadamente boas para automatizar procesos de negocio. Se podes describir algo que fas cada semana antes da túa reunión de pie, ao final de cada sprint, ou calquera cousa que fagas como enxeñeiro de forma diaria, semanal ou mesmo trimestral, deberías estar escribindo unha Skill para recuperar o teu tempo.

Podes automatizar postmortems? Podes revisar solicitudes de extracción? Calquera tarefa que poidas facer, podes polo menos ter que a primeira pasada sexa un Agent Skill. Aforrarache un tempo significativo.

Dito isto, lembra que unha Skill non é doada nin sequera necesaria sempre. Menos é máis. Algunhas outras conclusións:

Escribe avaliacións antes da Skill. Inclúe exemplos negativos e cargas prohibidas para Skills adxacentes pero distintas.

A descrición é a parte difícil. "Load when..." (cada palabra custa atención).

Os problemas son contido de valor extremadamente alto. Comeza delgado, crece a medida que o axente falla.

Lembra que é doado romper outras Skills preexistentes engadindo unha nova Skill, aínda que non a tocaras (coidado coa acción a distancia).

Usa todas as ferramentas dispoñibles cada vez que escribas e mantñas unha Skill. Se queres obter máis información, o sitio web de Agent Skills ten moitos bos exemplos, e tanto o noso repositorio interno como o ecosistema público contienen moitos exemplos de Skills ben deseñadas.

Cita

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