Skills via de API¶

Het concept achter agents staat in Agents.

Op deze pagina upload je een skill met de API en bied je hem aan in een beurt. Een skill bundelt herbruikbare instructies voor een taak, zoals release notes schrijven of tickets beoordelen. Je slaat het pakket één keer op en biedt het aan in de beurten die het nodig hebben. Moet het model een actie uitvoeren, gebruik dan tools.

Je sleutel heeft de capability skills nodig. Hetzelfde doe je met de muis in Skills in de console.

Pakketformaat¶

Core ondersteunt het Agent Skills-formaat. Een pakket bevat SKILL.md en optionele ondersteunende tekstbestanden. Zet in SKILL.md de velden name en description in een metadatablok tussen ----regels, gevolgd door Markdown-instructies.

---
name: release-notes
description: Schrijf release notes voor één versie op basis van een lijst gemergede wijzigingen.
---

Groepeer de wijzigingen onder Toegevoegd, Gewijzigd, Opgelost. Eén regel per stuk, in de
verleden tijd, die noemt wat een lezer nu kan. Noem nooit een intern ticketnummer.

Zie `examples.md` voor twee notes die zo geschreven zijn.

Een skill uploaden¶

curl -s -X POST "$CORE_URL/skills" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d @- <<'JSON'
{
  "skill_md": "---\nname: release-notes\ndescription: Schrijf release notes...\n---\n\nGroepeer de wijzigingen...",
  "resources": [{ "path": "examples.md", "content": "## 2.4.0\n\n### Toegevoegd\n..." }]
}
JSON

Lijsten bevatten resourcepaden en bestandsgroottes. Haal een resource apart op als je de inhoud nodig hebt.

Een resourcepad is relatief en mag / bevatten om bestanden in mappen te zetten, zoals templates/summary.md; haal het op met het pad zoals het is: GET /skills/{skill_id}/resources/templates/summary.md. Een pad bestaat uit letters, cijfers, ., _, - en /, tot 200 tekens; het mag niet met / beginnen of een ..-segment bevatten, en elk pad is uniek binnen een skill. Schrijf elk pad in zijn eenvoudige vorm, zonder //, ./ of een / aan het eind: de API normaliseert de URL waarmee je het ophaalt, dus een resource onder zo'n pad is via dat pad niet op te halen.

DELETE geeft 409 zolang de laatste versie van een agent de skill koppelt met haar id of haar naam; de fout noemt de agents in conflicts, hoogstens de eerste twintig, en telt de agents die je sleutel niet mag lezen in withheld (de velden). Een agent wordt ook geweigerd, met een 422 op de regel, als hij een skill noemt die je organisatie niet heeft.

PUT vereist de bestaande pakketnaam; een andere naam geeft 409. Maak voor hernoemen een nieuwe skill aan, werk verwijzingen bij en verwijder de oude zodra deze niet meer wordt gebruikt.

Elke PUT schrijft de volgende versie van de skill. Een beheerder kan er ook een als concept opslaan, in de console of de API ervan: je sleutel ziet een concept niet. GET geeft de gepubliceerde versie, een skill met alleen een concept bestaat niet voor je sleutel, en een verwijzing release-notes@3 naar een conceptnummer geeft 404, zoals bij een versie die nooit is geschreven. Het concept geldt zodra het gepubliceerd is.

Onbekende metadatavelden, ontbrekende name of description, absolute resourcepaden en paden met .. geven 422 met het betrokken veld.

Een skill aanbieden¶

{
  "model": "<een model-id>",
  "skills": ["release-notes"],
  "input": "Schrijf de notes voor 2.4.0 op basis van deze gemergede wijzigingen: ..."
}

Geef maximaal 32 skillnamen of skill_-id’s op in skills. Een niet-beschikbare verwijzing of uitgeschakelde capability geeft 404. Controleer bij problemen GET /key en de skillnaam of het id.

Het beleid van je sleutel bepaalt welke skills je bereikt. Een skill die het beleid niet noemt, staat niet in GET /skills, geeft 404 op zijn id en telt niet mee bij het laden — ook niet bij retrieval. Een pakket opslaan onder een naam die het beleid niet noemt, geeft 403.

Skills laden¶

De sleutelconfiguratie bepaalt welke van deze twee laadmethoden wordt gebruikt:

• Door het model gekozen (de standaard) — Core biedt een tool builtin__load_skill aan die alleen de skills van dit verzoek noemt, met elk hun eigen omschrijving. Het model leest een skill als het besluit er een nodig te hebben, en kan een ingepakte resource op pad opvragen. Skills koppelen is wat de tool aanbiedt: een verzoek dat hem in tools[] noemt, krijgt 400.
• Door zoeken gekozen — Core vergelijkt de laatste gebruikerstekst van de beurt met de omschrijving van elke genoemde skill en voegt de beste matches direct toe, voordat het model draait: die met een score van minstens min_score, hooguit retrieval_top_k. Een passende skill valt nooit af om de lengte van zijn tekst; de trace van de beurt laat zien hoeveel het aantal er wegliet en wat de toegevoegde teksten kosten. Er wordt geen builtin__load_skill aangeboden; de keuze is al gemaakt.

In beide modi is de skilltekst een vertrouwde instructie met dezelfde autoriteit als instructions. Sla alleen instructies op die dat niveau mogen krijgen.

Auditregistraties¶

De auditgeschiedenis registreert wijzigingen (skill.created, skill.replaced, skill.deleted) en gebruik (skill.loaded, skill.injected) met het oorspronkelijke request-id. Hiermee controleer je welke instructies een beurt heeft geladen.