developer.overheid.nl

Ontwikkelaarsportaal van de Nederlandse overheid

Ga naar hoofdinhoud

Bouw zelf een AI-plugin

Beheer je een standaard, richtlijn of werkwijze die vaak verkeerd wordt toegepast? Dan is een plugin een manier om die kennis bij de ontwikkelaar te krijgen op het moment dat hij code schrijft, in plaats van in een document dat hij achteraf moet opzoeken.

In deze tutorial bouw je een werkende plugin met één skill, test je hem lokaal en meld je hem aan voor de catalogus. Reken op ongeveer een uur.

Lees eerst Skills, plugins en marketplaces als die termen nog door elkaar lopen.

Wat je nodig hebt​

  • Claude Code of Cursor, lokaal geïnstalleerd
  • Python 3, voor het script dat de manifesten genereert
  • Een publieke repository met een opensourcelicentie
  • De standaard of richtlijn die je wilt ontsluiten

Stap 1: Bepaal wat de skill moet doen​

Begin niet bij de tekst maar bij de fout. Welke vergissing maken mensen steeds opnieuw?

Een goede skill beantwoordt een concrete vraag: "voldoet dit endpoint aan de API Design Rules?" of "hoe schrijf ik een publiccode.yml voor dit project?" Een skill die "alles over onze standaard" bevat, wordt nooit op het goede moment ingezet, omdat de assistent niet kan bepalen wanneer hij relevant is.

Schrijf één zin op: deze skill helpt bij X, en moet aanslaan wanneer iemand Y vraagt. Die zin wordt straks je description.

Stap 2: Zet de structuur op​

mijn-plugin/
├── .plugin/
│   └── plugin.json          # de bron, die schrijf je zelf
├── .claude-plugin/
│   └── plugin.json          # gegenereerd voor Claude Code
├── .cursor-plugin/
│   └── plugin.json          # gegenereerd voor Cursor
├── scripts/
│   └── generate_plugin.py   # genereert de twee bestanden hierboven
├── skills/
│   └── mijn-skill/
│       └── SKILL.md
├── README.md
├── DISCLAIMER.md
└── LICENSE

.plugin/plugin.json is de bron. De platformspecifieke varianten voor Claude Code en Cursor genereer je daaruit met scripts/generate_plugin.py, zodat je ze niet met de hand synchroon hoeft te houden. Het script haal je uit skills-standaarden; het gebruikt alleen de standaardbibliotheek van Python.

mkdir -p scripts
curl -o scripts/generate_plugin.py \
  https://raw.githubusercontent.com/developer-overheid-nl/skills-standaarden/main/scripts/generate_plugin.py
.plugin/plugin.json
{
  "name": "mijn-plugin",
  "description": "Korte beschrijving van wat de plugin doet",
  "version": "1.0.0"
}

De name wordt de namespace van je skills: gebruikers roepen ze aan als /mijn-plugin:mijn-skill. Kies kebab-case en iets dat uniek genoeg is.

Stap 3: Schrijf de skill​

skills/mijn-skill/SKILL.md
---
name: mijn-skill
description: >-
  Controleert of een OpenAPI-beschrijving voldoet aan de API Design Rules.
  Gebruik bij vragen over API design rules, ADR, OAS-validatie of
  overheids-API's.
allowed-tools:
  - Read
  - Grep
---

## Wanneer je deze skill gebruikt

Als de gebruiker een OpenAPI-bestand laat zien en vraagt of het klopt, of
expliciet naar de API Design Rules verwijst.

## Wat je controleert

| Regel                     | Wat je nagaat                                 |
| ------------------------- | --------------------------------------------- |
| `/core/no-trailing-slash` | Paden eindigen niet op een slash              |
| `/core/http-methods`      | Alleen standaard HTTP-methods                 |
| `/core/uri-version`       | Major versie in de URI, voorafgegaan door `v` |

## Hoe je rapporteert

Noem per bevinding de regel, de plek in het bestand en wat er anders moet.
Zeg het ook expliciet als je niets hebt gevonden.

Vier dingen bepalen of een skill werkt:

De description is het belangrijkst. Die bepaalt of de assistent de skill inzet. Zet er de woorden in waarmee mensen het onderwerp aanduiden, in het Nederlands én het Engels, inclusief afkortingen.

Schrijf instructies, geen encyclopedie. De assistent moet iets kunnen dóen. Tabellen, beslisbomen en codevoorbeelden werken beter dan lopende tekst.

Houd het onder de 500 regels. Langere referentie hoort in een apart bestand in dezelfde map, dat de assistent erbij pakt als het nodig is.

Beperk allowed-tools. Geef alleen wat de skill nodig heeft. Een skill die alleen leest, hoeft niet te kunnen schrijven.

Stap 4: Genereer de manifesten​

python scripts/generate_plugin.py

Dit maakt .claude-plugin/plugin.json en .cursor-plugin/plugin.json aan. Sla deze stap niet over: Claude Code leest .plugin/plugin.json niet, alleen .claude-plugin/plugin.json. Zonder dat bestand komen de naam en de versie uit je manifest niet bij de assistent aan, en hangt de namespace van je skills af van de mapnaam in plaats van de name.

Draai het script opnieuw na elke wijziging in .plugin/plugin.json. Met --check controleer je of de bestanden nog gelijk lopen, bijvoorbeeld in CI:

python scripts/generate_plugin.py --check

Stap 5: Test lokaal​

claude --plugin-dir ./mijn-plugin

Stel nu vragen die de skill zouden moeten activeren, en vooral ook vragen die dat níét zouden moeten doen. Die tweede categorie wordt vaak vergeten en is precies waar het misgaat: een te ruime description zorgt dat de skill overal aanslaat en de assistent afleidt.

Loopt het niet zoals verwacht, dan zit de oorzaak bijna altijd in de description, niet in de inhoud.

Stap 6: Voeg een disclaimer toe​

Een skill is een samenvatting, geen standaard. Zet in DISCLAIMER.md wat de plugin wel en niet is, en waar de officiële tekst staat. Voor opname in onze catalogus is dat een voorwaarde.

Zie de verantwoording voor de voorbehouden die wij hanteren.

Stap 7: Meld hem aan​

Voldoet je plugin aan de eisen, dan kun je hem aanmelden:

  • een opensourcelicentie (EUPL-1.2, Apache-2.0, MIT of vergelijkbaar)
  • een publieke repository
  • een geldige .plugin/plugin.json
  • minimaal één werkende skill, commando of agent
  • Nederlandstalige of tweetalige documentatie
  • een DISCLAIMER.md

Aanmelden gaat via de marketplace-repository.

Beschrijft je plugin een standaard met een eigen beheerorganisatie, dan beoordeelt die beheerder hem. Pas daarna krijgt hij in de catalogus de status goedgekeurd, met vermelding van die partij.

Verder lezen​