agentskills.io implementation

Tools zijn atomair. Skills zijn recepten. Een tool leest een file, runt een query, fetcht een URL. Skills zijn benoemde multi-step procedures die meerdere tools combineren met reasoning-stappen in een vaste volgorde. De agentskills.io standaard legt vast hoe een skill eruitziet, en het inbouwen in een tool-using agent is een kleine wijziging die zich snel terugbetaalt.

Waarom een skills-laag boven tools

Na 50 turns met een tool-using LLM merk je een patroon: dezelfde multi-tool workflows worden elke keer opnieuw verzonnen, met kleine variaties. "Morning status" roept dezelfde vijf tools aan in ongeveer dezelfde volgorde, maar de formattering drift. "Weekly recap" is een vergelijkbare vorm maar erger — meer tools, meer plekken om af te wijken.

De oplossing: een skills-laag. Elke terugkerende workflow wordt een benoemd recept; de LLM zoekt het recept op in plaats van elke keer opnieuw te plannen.

Drie concrete wins:

1. Consistentie. Dezelfde soort request geeft dezelfde vorm output. Belangrijk voor dingen die je herhaaldelijk leest (daily briefings, rapporten).
2. Minder reasoning per turn. De LLM hoeft een bekende workflow niet te herplannen; ze volgt de stappen. Goedkoper, sneller.
3. Onderhoudbaarheid. Wil je "hoe morning briefings werken" wijzigen? Edit één file, niet de prompt van het model.

SKILL.md format

De agentskills.io-spec is minimaal. Een skill is een directory met een SKILL.md-file (optioneel met subfolders voor scripts, references, assets). De SKILL.md heeft YAML-frontmatter en een Markdown-body:

---
name: daily-status-report
description: "Compile yesterday's commits, today's calendar, open
nudges into a single morning briefing. Use when Nathan asks for a
status report or starts a new conversation after >6h silence."
---

# Daily status report

Run the tools below in order, then synthesise the markdown summary at
the bottom.

## Steps

1. Call `commit_log` for yesterday's commits across all projects
2. Call `calendar_today` for events
3. Call `nudges_open` for pending review items
4. Format the output as:
   - "Yesterday: <commits>"
   - "Today: <events>"
   - "Awaiting review: <nudges>"

Twee verplichte frontmatter-velden: name (komt overeen met de directory-naam) en description (max 1024 tekens — dit is wat de LLM ziet bij het kiezen van een skill).

Progressive disclosure

De key design-keuze: alleen de metadata (frontmatter) wordt bij startup in de LLM-context geladen. De volledige body wordt pas geladen als de LLM besluit een specifieke skill aan te roepen. Twee tools ondersteunen dat:

def list_skills() -> list[dict]:
    """Cheap: returns name + description for all skills."""
    return [parse_frontmatter(p) for p in glob("memory/_skills/*/SKILL.md")]

def run_skill(name: str) -> dict:
    """Loads full SKILL.md body. ~5000 token budget per spec."""
    return read_skill(name)

list_skills kost ~100 tokens per skill — goedkoop genoeg om elke turn aan te roepen of in de system-prompt te zetten. run_skill is de dure operatie, alleen gecalled als de LLM een specifieke skill heeft gekozen.

Dit patroon houdt de context-grootte beheersbaar, ook als je 50+ skills beschikbaar hebt.

Hoe de LLM het gebruikt

In de praktijk wordt de prompt-loop:

1. User: "geef me een morning status"
2. LLM (met list_skills al in context): herkent dat dit matcht met de description van daily-status-report
3. LLM roept run_skill("daily-status-report") aan
4. LLM krijgt de volledige body, volgt de stappen, callt de tools in de juiste volgorde
5. LLM formatteert volgens de template in de skill

De LLM doet nog wel reasoning (welke skill matcht, hoe omgaan met edge-cases), maar het plan is canoniek. Zelfde request, zelfde vorm output.

Wanneer je een skill toevoegt

Heuristiek: zodra je drie keer dezelfde multi-step workflow naar de LLM uitschrijft, maak er een skill van. Authoring kost ~15 minuten; de opbrengst is permanent.

Slechte kandidaten voor een skill:

• One-off requests (laat de LLM gewoon plannen)
• Single-tool calls (skill is overkill)
• Heel variabele workflows (elke invocatie heeft andere stappen)

Goede kandidaten:

• Status / briefing / recap rapporten
• Multi-tool diagnostics ("check waarom X faalt")
• Onboarding-sequences ("zet een nieuw project op")
• Alles wat op een schedule draait

Auto-tracking van gebruik

De frontmatter kan invocation-counts en success-rates over tijd opslaan. Elke run_skill-call appendt een teller onderaan de frontmatter:

total_invocations: 47
total_successes: 45
success_rate: 0.957
last_used: "2026-06-02T08:30:22Z"

Slow telemetry — file-based, geen aparte database. Maar genoeg om te zien welke skills gewicht trekken en welke nooit gebruikt worden. Onbenutte: weggooien. Populaire: verdiepen.

Waarom specifiek agentskills.io

Het is de spec die Anthropic heeft aangenomen voor Claude Skills. Gebruik ervan betekent dat je skills portable zijn: ze werken in je lokale orchestrator, ze werken in Claude.ai, ze werken in elke tool-using agent die de standaard ondersteunt. Je kunt ook community-skills lenen zonder ze te herschrijven.

De standaard is klein genoeg om in 10 minuten door te lezen. De investering om 'm te adopteren is klein genoeg om een één-middag-refactor te zijn. De payoff is permanent.