Agent Skills

Progressive disclosure

Drie lagen, dezelfde drie die de specificatie beschrijft:

• De catalogus. Bij elke beurt bevat de prompt van de agent een menu van de skills die relevant lijken: titel, beschrijving van één regel, slug. Nooit de tekst. Standaard drie skills per beurt, maximaal zes.
• Activering. De agent roept de tool load_playbook aan met een slug om de volledige stappen te lezen. Het slug-argument is per beurt gebonden aan een enum van precies de slugs in het menu van die beurt – een verzonnen naam wordt vóór verzending geweigerd in plaats van de agent een roundtrip te kosten. Als er geen menu is, wordt de tool helemaal niet geregistreerd.
• Resources. Nog niet. Een skill is hier één enkel SKILL.md; meegeleverde mappen scripts/, references/ en assets/ worden geparsed en genegeerd in plaats van half ondersteund.

Zodra een skill is geladen, blijft hij geladen. Agent-runs comprimeren oudere toolresultaten om de kosten te drukken, en geactiveerde skills zijn daarvan uitgezonderd: hun instructies blijven woordelijk behouden voor de rest van de run, hoe lang die ook duurt. Een skill die midden in een taak stilletjes verdampt is erger dan een skill die nooit is geladen.

Welke skills in het menu komen

Twee rondes. Triggerwoorden worden hoofdletterongevoelig als deelstrings met de beurt vergeleken; daarna vult een semantische ronde de lijst aan op basis van een embedding van de titel, beschrijving, triggers en het begin van de tekst van elke skill, alleen toegelaten boven een gekalibreerde gelijkenisdrempel. Een skill zonder triggers staat altijd aan en wordt altijd aangeboden. Het model beslist wat het activeert – niets hier dwingt het een skill op.

Een skill binnenhalen

• De bibliotheek. Samengestelde pakketten, met één klik op een agent geïnstalleerd. Dit is het ontdekkingsoppervlak dat de meeste mensen gebruiken.
• Zelf schrijven. Titel, beschrijving, triggerwoorden en de stappen, in het tabblad Playbooks van de agent.
• De API. POST /api/agents/:id/playbooks/import accepteert { files: [{ name, content }] } en importeert elk bestand onafhankelijk – één fout bestand mislukt alleen, de rest komt toch binnen. Elk bestand wordt op veiligheid gescand voordat er iets wordt opgeslagen, en een import overschrijft nooit een bestaande skill: een slug-botsing komt terug als overgeslagen.
• Een skill samenstellen uit een document. POST /api/agents/:id/playbooks/generate accepteert { artifactId } – een document dat al in de workspace staat – of { content, sourceName }, en schrijft een procedure op basis van wat het document leert: wanneer die van toepassing is, de stappen, de beslisregels, het vocabulaire. Dit is niet de uploadpijplijn, die een document omzet in passages die een agent kan opzoeken; dit maakt er iets van dat de agent doet. De procedure wordt nieuw geschreven, nooit geciteerd: de bron kan de auteursrechtelijk beschermde handleiding van iemand anders zijn, en een playbook dat eruit citeert zou er een kopie van zijn. Lange documenten worden vanaf het begin tot een limiet gelezen, en het antwoord meldt wanneer er is afgekapt. Het resultaat komt inactief binnen: niemand heeft die woorden geschreven, dus een mens leest het concept en zet het aan, of het draait nooit.

Er is bewust geen uploadknop in de interface. Een SKILL.md wordt een blijvende instructie voor een agent die de tools van een workspace beheert, dus een willekeurig geüpload bestand is een prompt-injectievector en geen gemak. De API-route hierboven, alleen voor eigenaren, is de bewuste uitzondering.

Een skill meenemen

Elke skill exporteert als zip met <name>/SKILL.md – de mapstructuur die de specificatie beschrijft, geen los bestand. Pak hem uit in ~/.agents/skills/ of .claude/skills/ en hij laadt in die client zonder iets te hernoemen, en skills-ref validate slaagt erop zoals hij is. API-aanroepers die alleen het losse bestand willen, kunnen in plaats daarvan text/markdown opvragen.

De frontmatter bevat name en description. Onze eigen uitbreidingen – triggerwoorden, volgorde en een markering dat het bestand van hier komt – zitten onder metadata, omdat de referentievalidator van de specificatie onbekende sleutels op het hoogste niveau afwijst en een export van ons nooit het bestand mag zijn waarop hij faalt.

Wat we weigeren over te nemen

• allowed-tools wordt altijd weggelaten. De specificatie definieert het als tools die vooraf voor een skill worden goedgekeurd, precies het verkeerde om te accepteren uit een bestand dat via een API of uit een gedeeld pakket binnenkomt: geïmporteerde inhoud zou zijn eigen toolrechten kunnen verruimen. Welke tools een agent mag aanroepen is een eigenschap van de rol van die agent, nooit van een bestand dat hij heeft gelezen.
• compatibility wordt weggelaten om een saaiere reden: het beschrijft de omgeving waarvoor de skill is geschreven, en dat zegt niets over de onze.
• Alles buiten de gedocumenteerde frontmatter wordt genegeerd in plaats van geraden. De parser accepteert de kleine, vaste vorm die de specificatie definieert en niets exotisch.

Limieten

Dertig skills per agent, 64 kB per geïmporteerd bestand en een begrensde tekst – een skill die niet meer in dat budget past, zijn twee skills. Namen bestaan uit kleine letters, cijfers en enkele koppeltekens: de specificatie staat meer toe, maar de naam is hier ook een URL.

Elders

De specificatie is gezaghebbend voor het formaat. Voor de HTTP-API waarmee agents op het netwerk handelen, zie de API-documentatie.