Designa, finjustera och underhålla agent-skills på Perplexity

Perplexitys frontieragentprodukter vilar på en grund av know-how och domänexpertis paketerad i modulära Agent Skills. Vi upprätthåller ett noggrant urval av Skills i våra tekniska miljöer. Dessa Skills inkluderar många av de generella verktyg som driver Perplexity Computer; vertikaliska funktioner inom områden som finans, juridik och hälsa; och en mycket lång svans av moduler för att tillgodose användarnas behov. Vissa Skills anropas sällan men är avgörande när de anropas. För att säkerställa en genomgående utmärkt användarupplevelse prioriterar Perplexitys agentteam Skill-kvalitet lika högt som kodkvalitet.

De intuitioner och bästa metoder som krävs för att utveckla en Skill av hög kvalitet skiljer sig avsevärt från de som krävs för att bygga traditionell mjukvara. Agentteamet granskar många pull requests från skickliga ingenjörer som utvecklar Skills i sitt arbete. Resultatet är nästan alltid ett flertal kommentarer och förslag på revideringar. Detta beror på att många användbara mönster för att skriva kod blir antipatterns vid skapandet av Skills.

Om du till exempel tar några av aforismerna från PEP20 – The Zen of Python blir det snabbt uppenbart att det skiljer sig åt att skriva bra Python-kod och att skriva bra Skills. Av de 20 visdomsorden är minst hälften helt felaktiga eller aktivt missvisande när man skriver Skills. Här är fem av dem:

Fem kontraster mellan Pythons zen och artikelns riktlinjer för att skriva Skills.

Den här guiden är det dokument som ingenjörer på Perplexity använder när de utvecklar och granskar Skills. Vi släpper också denna guide till allmänheten så att våra upptäckter och lärdomar kan komma den bredare gemenskapen till del. Oavsett om du är en ingenjör som designar produktions-Skills i ditt dagliga arbete, en Computer-användare som vill utveckla din egen Skill inom ett område du kan bäst, eller både och, är den här guiden för dig.

Vad är en Skill?

När du skriver en Skill skriver du inte vanlig gammal mjukvara (även om Skills nu är en del av de huvudsakliga logiska motorerna för agentsystem). Istället bygger du upp kontext för modeller och deras miljöer. En Skill har andra begränsningar och andra designprinciper. Om du skriver en Skill på samma sätt som du skriver kod kommer du att misslyckas.

En Skill är minst fyra saker, särskilt i kontexten av hur vi bygger dem på Perplexity.

En Skill är en katalog

En Skill är inte bara en enskild SKILL.md-fil. I många fall innehåller en Skill flera filer. Under katalogen som är uppkallad efter din Skill kan du ha:

SKILL.md: frontmatter och instruktioner

scripts/: kod som agenten kör, inte återuppfunnen

references/: tunga dokument, inlästa villkorstyrt

assets/: mallar, scheman och data

config.json: användarinstallation vid första körningen

Det här hub-and-spoke-mönstret gör att du kan hålla Skills mycket fokuserade och tajta, och man kan använda mappstrukturen på ett väldigt kreativt sätt. Ibland drar särskilt invecklade Skills nytta av flera hierarkinivåer för att hjälpa modellen att navigera bättre. Anta att en Skill kräver kunskap om 300 ämnen som kan grupperas i 20 ämnesområden. Att tillförlitligt välja rätt ämne bland 300 är en olöst utmaning även för dagens bästa frontier-modeller. Det är ett mycket enklare urvalsproblem för en modell att ringa in ett av 20 områden än att välja bland de 15 ämnena inom det området.

Som ett exempel på hur flernivåhierarki ger värde använde vårt team tre nivåer av ämnesmässig kapsling inom de Skills som drev Computers amerikanska inkomstskattefunktioner under den senaste skattesäsongen. Denna hierarki var helt oumbärlig med tanke på skattelagstiftningens komplexitet: i våra tidiga tester ledde det till sämre prestanda än att inte ladda Skillen alls när vi presenterade en enda mapp innehållande alla 1 945 avsnitt i den amerikanska skattelagen (U.S. Internal Revenue Code) för modellen. Att organisera informationen i logiska underavdelningar var oumbärligt för att säkerställa läsoperationer med hög precision.

Ändå kom denna hierarki inte gratis. Ökande hierarkinivåer kräver ökande nivåer av kurering över informationsarkitekturen för att hantera den resulterande indirektionen. Vi tog fram snabbguider, anpassade sökverktyg och andra verktyg för att stödja modellen i att lokalisera information med ett minimum av indirektion. I det här fallet gav det tunga kureringsarbetet slutligen ett positivt slutresultat: en Skill som tillät modeller att utföra skatterelaterade uppgifter mycket skickligare än genom att enbart använda generella verktyg.

Förstora

En Skill är ett format

En Skill är ett format. Den grundläggande rotfilen SKILL.md måste ha både ett namn och en beskrivning. Dessutom måste Skillen exakt matcha det katalognamn där Skillen är placerad. Namnet får endast bestå av gemener, inte innehålla några mellanslag, och kan använda bindestreck. Beskrivningen är routingsutlösaren. Detta är en vanlig felpunkt: beskrivningen är inte intern dokumentation för vad Skillen gör. Den motsvarar instruktioner till modellen för när Skillen ska laddas. Därför kommer du ofta att se "Load when" (Ladda när) snarare än "This Skill does" (Denna Skill gör). Detta är viktigt på grund av det sätt på vilket de flesta implementationer injicerar beskrivningen i modellkontexten.

Inne i frontmatter finns även "depends:", som gör att du kan skapa hierarkiska Skill-beroenden, och "metadata:", som används för granskningar och utvärderingar. Olika agentsystem kan till och med definiera sina egna frontmatter-fält för att användas på ett sätt som är specifikt för dessa system. Alternativt kan Skill-specifik metadata paketeras i en extra JSON- eller YAML-konfigurationsfil. Detta är önskvärt när man bygger agentsystem som behöver underlätta olika typer av körtidsbeteende per Skill utan att förorena modellens kontext med detaljer. Slutligen kan ett liknande beteende uppnås genom att rensa bort Skill-frontmatter vid inläsning. Computer tillämpar denna metod, vilket gör att konfigurationen kan bevaras i rotfilen SKILL.md. Noggrann uppmärksamhet på detaljer krävs i tolkningslogiken, och man kanske vill implementera villkorlig rensning om det finns vissa fält som är användbara att ha inom modellkontexten.

En Skill är anropbar

En Skill är anropbar. Agenten laddar en Skill vid körtid. Det är viktigt att notera att Skills inte alltid är hopbakade i kontexten. Som standard fäller de flesta agentsystem ut Skills progressivt utifrån specifika behov.

Det finns minst tre nivåer av kontextkostnader på det sätt som vi har implementerat Skills i Computer. Här är processen:

Computer anropar load_skill(name="...")

Computer kopierar Skill-katalogen till den isolerade exekveringssandlådan

Computer autoladdar rekursivt beroenden i taggen "depends:"

Computer rensar sedan bort frontmatter och agenten ser därmed endast brödtexten och de extra filerna

Olika agentsystem kan välja att exponera Skill-innehåll på olika sätt. Vissa system kan till exempel välja att inte exponera filhierarkin över huvud taget, utan lämna det åt modellen att upptäcka hierarkin genom filsystemsoperationer. Andra system kan välja att ge modellen en mappning av hela filträdet upp till en viss trunkerings- och/eller djupgräns. För att hålla kontexten ren utelämnar Computer fullständiga filhierarkier från anropskontexten; detta kan dock åsidosättas per Skill.

En Skill är progressiv

Skills är progressiva. I Computer finns det tre olika nivåer av kontextkostnader, och vi ådrar oss alla tre i olika skeden:

De tre nivåerna av Skill-kontext: index, fullständig Skill-inläsning och referensfiler vid körning.

Computer bygger ett Skill-index som har namnet och beskrivningen för varje tillgänglig Skill. Budgeten för detta är cirka 100 tokens per Skill (kortare är ännu bättre). Det är så snävt eftersom du betalar denna kostnad i varje session, för varje användare. Detta injiceras i systemprompten i början av konversationen. Modellen har tillgång till ett gäng namngivna Skills och beskrivningar så att den kan avgöra om den ska anropa "load_skill()". Tröskeln för att komma med i detta index är extremt hög. Din Skill måste vara mycket användbar, och beskrivningen måste vara extremt kompakt och koncis eftersom alla betalar kostnaden hela tiden.

Efter att agentsystemet har laddat Skillen finns den fullständiga SKILL.md-brödtexten. Helst ska brödtexten inte överstiga 5 000 tokens. Även då vill du att varje mening ska spela roll, för när du väl har laddat en Skill måste resten av konversationen betala det tills du når komprimeringsgränsen. Många trådar laddar allt mellan tre och fem olika Skills, vilket multiplicerar denna kostnad. Skills med mycket fluff kommer nästan oundvikligen att försämra andra Skills såväl som de övergripande agentkapaciteterna. Kort sagt, om din Skill laddas och den inte gör rätt sak är det bortkastad kontext.

Den sista nivån av progression är skript eller specialfall, som subskills eller formatering. Det är här du vill placera obegränsad villkorlig förgrenad logik. Agenten kommer bara att använda den när den behöver det, vilket innebär att det är en mycket lägre tröskel för vad du vill stoppa in här.

I indexet är varje token viktig. Den inlästa Skill-brödtexten är mer avslappnad, och körtiden är den mest avslappnade. Detta kan vara 20 000 tokens eller noll tokens. Detta är den nivå på vilken du kan överväga att utöka modellens kontext på ett progressivt sätt.

När behöver du en Skill?

Agentteamet ombes ofta att uttala sig om huruvida en Skill verkligen behövs för en given domän eller ett givet användningsfall. Mycket sällan har vi ett definitivt svar enbart baserat på grundprinciper. Det enda sättet att verkligen ta reda på detta är att starta din agent utan Skillen, köra ett antal hero-frågor och sedan ta reda på om agenten gör ett bra jobb.

När du behöver en Skill

Det finns många uppgifter som ligger inom distributionen för tränade modeller. Du behöver bara tillämpa en Skill om du vill ändra det beteendet på något specifikt sätt som du inte kan med till exempel en mening i din prompt. Du behöver därför en Skill när agenten gör fel utan särskild kontext, eller om det finns någon inkonsekvens eller icke-determinizm som du behöver göra extremt konsekvent över körningar.

Det kan vara så att din kunskap är beständig men inte finns med i träningsdata. Det kan finnas brytpunkter eller företagspecifika arbetsflöden, eller så kan det vara en smaksak. Vi har till exempel flera designrelaterade Skills i Computer skrivna av Henry Modisett (vår designchef). Anledningen till att varje token existerar i dessa Skills är att Henry har väldigt god smak när det gäller att designa webbplatser och PDF:er. Henry anger vilka typsnitt som ska användas och inte användas, hur dessa typsnitt känns, och andra bedömningsfrågor som modellen inte kan lära sig enbart från träningsdata.

När du inte behöver en Skill

Vi ser många Skills där ingenjörer har skrivit en serie git-kommandon som måste köras i ordning. Det är onödigt eftersom modellen redan vet hur man gör det, vilket innebär att det blir bra dokumentation men en dålig Skill.

Vi ser exempel där Skills upprepar instruktioner från systemprompten. Du behöver inte en Skill för det. Kunskap som är relevant för majoriteten av förfrågningar bör inkluderas i den globala kontexten, inte i en villkorligt inläst Skill

Om det är något som förändras snabbare än du kan underhålla det behöver du inte en Skill. Om du till exempel anropar någon fjärransluten MCP-slutpunkt och dess verktyg eller versionerna av dessa verktyg ändras ofta, bör du inte injicera dem i en Skill. Om du gör det kommer du bara att få drift och modellen kommer att göra misstag.

Varje Skill är en skatt

Här är ett användbart test som du kan tillämpa på varje mening i din Skill: "Skulle agenten göra fel på det här utan den här instruktionen?" Om meningen inte behöver vara där har den inte råd att vara där eftersom alla betalar denna kostnad varje gång. När du bestämmer dig för om du ska lägga till en Skill eller inte, kom ihåg denna skatt där varje session och varje användare kostar tokens.

Följande berömda citat, som låter mycket bättre på franska, översätts ungefär till "Jag har bara gjort det här brevet längre eftersom jag inte har haft tid att göra det kortare."

« 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

Precis som Pascal måste du lägga tid på varje Skill. Det är svårt att skriva en kort Skill. Om din Skill är enkel att skriva är den förmodligen för lång eller borde inte finnas. En bra Skill är så kort som den kan vara.

Om du märker att du försöker generera en Skill i en enda vändning och lägga upp PR:ar på fem minuter kommer resultaten nästan helt säkert att bli undermåliga. Faktum är att tidig forskning har visat att om du använder LLM:er för att skriva Skills kommer LLM:en förmodligen inte att ha nytta av det: "Självgenererade Skills ger ingen nytta i genomsnitt, vilket visar att modeller inte tillförlitligt kan författa den procedurkunskap de har nytta av att konsumera."

Hur man bygger en Skill

Uttryckt på ett annat sätt måste du injicera din åsikt i varje Skill som du skriver. Följ dessa steg.

Steg 0: Skriv utvärderingarna (Evals)

Skriv några av utvärderingarna först. Du kan hämta utvärderingsfall från:

Verkliga användarfrågor: samla in ett urval från produktionen eller din kompetenspool

Kända misslyckanden: Agenten misslyckades eftersom Skillen inte fanns

Grannförvirring: Nära din domängräns men routas till en annan Skill

Åtminstone bör du se till att du testar att Skillen laddas när det behövs. Helst samlar du in ett urval av dessa, kanske från en produktionsmiljö. Du kan också överväga kända felaktiga fall: kanske är hela anledningen till att du satte igång med att skriva Skillen ett specifikt misstag du upptäckte, eller så håller du på med refaktorisering och det råder viss förvirring mellan två näraliggande domäner som täcks av en enda Skill.

Börja med liknande negativa och positiva exempel. Negativa exempel är extremt kraftfulla och kan spela större roll än positiva exempel.

Steg 1: Beskrivningen

Detta är den svåraste raden i Skillen. Det är en routingsutlösare, inte dokumentation. För att få namnet och beskrivningen rätt bryr du dig inte om innehållet i Skillen. Du bryr dig bara om huruvida Skillen laddas och injiceras vid rätt punkter och är fri från oönskade sidoeffekter, vilket är det vanligaste felet. Varje gång du lägger till ytterligare en Skill riskerar du att göra varje annan Skill något sämre, så du måste se till att du minimerar regression.

Återigen, en dålig beskrivning beskriver vad Skillen gör eller varför den är användbar. En bra beskrivning anger när agenten ska ladda Skillen. Anta till exempel att du har något för övervakning av pull requests. Skriv inte vad Skillen gör. Skriv vad ingenjörer säger när de är frustrerade och vill att du ska se till att deras PR fungerar, som "babysit" (passa upp), "watch CI" (övervaka CI) eller "make sure this lands" (se till att detta går igenom).

Här är en snabb checklista:

Börjar med "Load when..."

Sikta på 50 ord eller färre

Beskriver användarens avsikt, helst från verkliga frågor

Sammanfattar inte arbetsflödet

Verkliga frågor är vad du kan täcka in i en 80/20-regel. Vanligtvis fungerar två eller tre exempel bra. Det är inte lätt att lägga till exakt och enbart så mycket som du behöver.

Steg 2: Skriv brödtexten

Härnäst skriver du själva innehållet i Skillen. Observera att detta inte är Steg 0 eller Steg 1.

Att kommunicera arbetsflöden till en LLM skiljer sig helt från att kommunicera arbetsflöden till en kollega, eller ens till ditt körtidssystem. När en ingenjör lär sig ett nytt mjukvaruverktyg kan de behöva läsa dokumentationen, få en genomgång av någon med erfarenhet och lära sig att använda verktyget. Samtidigt, för nästan alla mjukvaruverktyg som har funnits i minst ett år, behöver du bara nämna dess namn och LLM:en har all information den behöver.

När du skriver brödtexten ska du hoppa över det uppenbara. Många ingenjörer har gott om erfarenhet av att skriva readme.md-filer som räknar upp varje kommando som någon behöver köra. Det är lätt att falla tillbaka på det när man skriver en Skill eftersom det känns som att man skriver dokumentation, men om du gör det kommer din Skill att bli skräp. Skriv därför inte ut en serie kommandon.

Du behöver till exempel inte skriva: "git log # find the commit; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;"

Skriv istället: "Cherry-picka commiten till en ren gren. Lös konflikter och bevara avsikten. Om den inte kan gå igenom rent, förklara varför."

Modellen kommer att göra ett mycket bättre jobb med det senare alternativet än med det förstnämndas alltför föreskrivande serie kommandon, särskilt när saker och ting går fel. Kör inte över, eller var alltför föreskrivande, vilket är skört, utan var istället flexibel där flera tillvägagångssätt kan fungera. Återigen, bra dokumentation för människor är oftast dålig dokumentation för modeller.

Fokusera sedan på fallgropar eller negativa exempel. Dessa är innehåll med extremt högt signalvärde eftersom de ofta vägleda modellen om vad den inte ska göra. Om du lägger till en rad varje gång agenten snubblar till kommer du att lära dig genom att köra den och fallgroparna kommer att växa organiskt.

Slutligen, om det finns någon del som är villkorlig eller extremt tung på innehåll, ta ut den ur SKILL.md, som är navet, och lägg den i en av ekrarna. Placera den i en tillbehörsfil som kan laddas progressivt, vilket vi kommer att fördjupa oss i härnäst.

Steg 3: Använd hierarkin

Använd dig av Skill-hierarkin när du har ett skript, referenser eller använder ett specifikt verktyg:

Föreslagna användningsområden för skript, referenser, resurser och konfiguration inom en Skill.

För allt som är villkorligt eller förgrenar sig från huvud-Skillen, bryt ut det i en mapp. Kom också ihåg att flernivåhierarki kan användas för särskilt invecklade Skills. För dessa vill du noga överväga om funktionaliteten ska implementeras monolitiskt eller som en samling Skills (kanske med depends:-baserade inläsningsrelationer).

Steg 4: Iterera

Gör sedan ett gäng iterationer på en gren. Börja på main-grenen utan någon Skill, gör några iterationer, bygg din uppsättning med hero-frågor och kör en rad utvärderingar. Alla som granskar din Skill-kod kommer att tacka dig för att du skickar in en enda ändringsuppsättning komplett med en utvärderingsuppsättning. Att granska efterföljande inkrementella ändringar (förutom en ny fallgrop) är väldigt svårt, så försöka att minimera det.

Du kommer sannolikt att göra många små ordändringar. Små ordändringar i beskrivningar kan ha en oproportionerligt stor inverkan på routing (inklusive spillover-effekter på andra Skills), så gör allt det arbetet före Steg 5.

Steg 5: Publicera

Publicera den.

Hur man underhåller en Skill

Nu när du har skrivit en Skill måste du underhålla den.

Fallgropssvänghjulet (The Gotchas Flywheel)

Från och med denna punkt tenderar din lista med fallgropar att växa eller förändras mycket. Vi ser ofta ingenjörer som skickar in PR:ar som saknar utvärderingar, till exempel ändrar beskrivningen. Om du ändrar beskrivningen efter att din Skill har mergats är du fel ute. Om du gör ändringar i den mekanism som avgör om din Skill ska routas måste du skriva några utvärderingar som stöder ändringarna.

Skills är i huvudsak tilläggsbara (append-mostly). Fallgropssektionen samlar på sig mest värde över tid:

Agenten misslyckas med något → Lägg till en fallgrop

Agenten laddar Skillen felaktigt → Skärp beskrivningen och lägg till negativa utvärderingar

Agenten laddar inte Skillen när den borde → Lägg till nyckelord och positiva utvärderingar

Systemprompten ändras → Leta efter konflikter eller duplicering

Det är lätt att upptäcka ett enskilt fel i intern testning eller i produktion och lägga till en fallgrop. Det är ett negativet exempel så det ändrar egentligen inte explicita riktlinjer, men det låter modellen veta: "Hej, det här kända felet existerar."

När du går från 80/20 till att uppnå en framgångsgrad på 99,9 % eller 99,99 % är det lätt att denna lista med fallgropar växer. När du ser dessa negativa exempel bör du i huvudsak lägga till dem i fallgropssektionen. Du ska inte lägga till längre instruktioner eller ändra beskrivningen.

Utvärderingssviter (Eval Suites)

På Perplexity kör vi många utvärderingssviter för att kontrollera olika saker. Det finns Skill-inläsning och inläsning av Skill-filer, vilket kontrollerar precision, återkallelse (recall) och förbjudna kontroller för själva Skill-inläsningen. Kommer agenten att roura din Skill när den förväntas göra det? Detta säkerställer att nya Skills inte bryter mot befintliga gränser.

Det finns också utvärderingar som kan kontrollera korrekt progressiv inläsning. Agenten kanske laddar Skillen, men läser den tillbehörsfilen eller filerna? Om du till exempel har en finans-Skill för finansfrågor, läser den den speciella filen FORMATTING.md?

Det finns även utvärderingar för Skills som testar slutförande av uppgifter från ände till ände (end-to-end) inom domäner. Vi kör hela agentloopen och använder en LLM-domare för att bedöma resultaten baserat på en bedömningsmall med väldefinierade kriterier.

Slutligen är det viktigt att köra dessa utvärderingar mot olika modeller. Computer stöder minst tre olika modelfamiljer för orkestrering: GPT, Claude Opus och Claude Sonnet. Du vill köra din Skill-inläsning och domän-Skills mot dessa olika agentorkestrerare för att säkerställa att du inte får olika beteenden. Sonnet och GPT beter sig ganska annorlunda när det kommer till Skills.

Slutliga tankar och lärdomar

Ju fler Skills du bygger, desto bättre blir du på att bygga dem. Om du inte automatiserar eller försöker göra mer reproducerbara uppgifter som du utför till vardags med hjälp av Skills, bör du börja omedelbart.

Själva handlingen att bygga Skills gör dig bättre på att bygga fler Skills, men de är dessutom extremt bra på att automatisera affärsprocesser. Om du kan beskriva något du gör varje vecka före din standup, i slutet av varje sprint, eller vad som helst som du gör som ingenjör på daglig, veckovis eller till och med kvartalsvis basis, bör du skriva en Skill för att köpa tillbaka din tid.

Kan du automatisera postmortems? Kan du granska pull requests? Vilken uppgift som helst som du kan utföra, kan du åtminstone låta ha en första genomkörning som en Agent Skill. Det kommer att spara dig avsevärd tid.

Med det sagt, kom ihåg att en Skill inte är enkel eller ens alltid nödvändig. Mindre är mer. Några andra lärdomar:

Skriv utvärderingar före Skillen. Inkludera negativa exempel och förbjudna inläsningar för närliggande men distinkta Skills.

Beskrivningen är den svåra delen. "Load when..." (varje ord kostar uppmärksamhet).

Fallgropar är innehåll med extremt högt värde. Börja tunt, väx allteftersom agenten misslyckas.

Kom ihåg att det är lätt att förstöra andra redan existerande Skills genom att lägga till en ny Skill, även om du inte rörde den (var uppmärksam på fjärreffekter).

Använd alla tillgängliga verktyg varje gång du skriver och underhåller en Skill. Om du vill veta mer har webbplatsen för Agent Skills gott om bra exempel, och både vårt interna arkiv och det offentliga ekosystemet innehåller många exempel på väldesignade Skills.

Citat

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