Skip to content

Commit 0f73d57

Browse files
dvhdvh
committed
fixes 630
1 parent cb0967f commit 0f73d57

File tree

3 files changed

+220
-3
lines changed

3 files changed

+220
-3
lines changed

‎blog/authors.yml‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ floris-deutekom:
1818
github: Fdeutekom
1919
email: f.deutekom@geonovum.nl
2020

21-
Jan Klopper:
21+
jan-klopper:
2222
name: Jan Klopper
2323
title: Implementatie ondersteuner - developer.overheid.nl
2424
image_url: https://developer.overheid.nl/img/team/jan-klopper.png
@@ -27,7 +27,7 @@ Jan Klopper:
2727
linkedin: janklopper
2828
github: underdarknl
2929
email: j.klopper@geonovum.nl
30-
30+
3131
dimitri-van-hees:
3232
name: Dimitri van Hees
3333
title: Product Owner - developer.overheid.nl
@@ -200,4 +200,15 @@ jan-vlug:
200200
henry-fidder:
201201
name: Henry Fidder
202202
title: Product Manager - Justitiële Informatiedienst
203-
page: true
203+
page: true
204+
205+
anne-schuth:
206+
name: Anne Schuth
207+
title: Staff Engineer - Bureau Architectuur BZK
208+
page: true
209+
image_url: https://media.licdn.com/dms/image/v2/C4D03AQE0RSflUrQPyg/profile-displayphoto-shrink_400_400/profile-displayphoto-shrink_400_400/0/1596035901458?e=1776297600&v=beta&t=QfxZIuAKQ0Krk32sYS8qsPgUzcPpCmisemJG-DmEH8g
210+
socials:
211+
linkedin: https://www.linkedin.com/in/anneschuth/
212+
github: anneschuth
213+
bluesky: anneschuth.nl
214+
email: anne.schuth@rijksoverheid.nl

‎blog/draft/img/matrix.png‎

532 KB
Loading

‎blog/draft/skills.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
draft: true
3+
authors: [anne-schuth, dimitri-van-hees]
4+
tags:
5+
- ai
6+
- llm
7+
- adr
8+
- open-source
9+
- forum-standaardisatie
10+
- developer.overheid.nl
11+
image: ./img/matrix.png
12+
description: |
13+
"I know kung fu." In The Matrix downloadt Neo een vechtkunst in zijn hoofd en is
14+
klaar om te gaan. In het echt werkt het anders. Als developer moet je allerlei
15+
standaarden en protocollen kennen, en dat kost uren lezen en uitzoeken. Maar je
16+
AI-assistant kan die kennis wel gewoon ingeladen krijgen. Op
17+
developer.overheid.nl experimenteren we met skills die overheidsstandaarden
18+
inladen in je AI-assistant.
19+
---
20+
21+
# Wat als je standaarden kon downloaden in je AI-assistant?
22+
23+
![Plaatje van een matrix](./img/matrix.png)
24+
25+
"I know kung fu." In The Matrix downloadt Neo een vechtkunst in zijn hoofd en is
26+
klaar om te gaan. In het echt werkt het anders. Als developer moet je allerlei
27+
standaarden en protocollen kennen, en dat kost uren lezen en uitzoeken. Maar je
28+
AI-assistant kan die kennis wel gewoon ingeladen krijgen. Op
29+
developer.overheid.nl experimenteren we met skills die overheidsstandaarden
30+
inladen in je AI-assistant.
31+
32+
<!-- truncate -->
33+
34+
De Nederlandse overheid heeft tientallen standaarden voor softwareontwikkeling.
35+
API Design Rules, Digikoppeling, OAuth NL-profielen, DMARC, DNSSEC, en zo door.
36+
Ze zijn publiek beschikbaar en goed gedocumenteerd. Toch kent bijna niemand ze
37+
allemaal. Er zijn er gewoon te veel, en de afstand tussen een standaarddocument
38+
en je dagelijkse werk is groot. Skills maken die afstand kleiner.
39+
40+
:::warning[Verantwoord experimenteren]
41+
42+
We noemen dit bewust een experiment. Alle skills dragen een CONCEPT-label. De
43+
beschrijvingen zijn informatieve samenvattingen; de
44+
[officiële bronnen](https://www.forumstandaardisatie.nl/open-standaarden) zijn
45+
leidend.
46+
47+
We hebben het experiment getoetst aan de
48+
[Overheidsbrede handreiking voor de verantwoorde inzet van generatieve AI](https://open.overheid.nl/documenten/9c273b71-cebb-4e11-b06f-fa20f7b4b90e/file).
49+
In het
50+
[verantwoordingsdocument](https://github.com/developer-overheid-nl/skills-marketplace/blob/main/docs/verantwoording.md)
51+
staat hoe we omgaan met risico's. Om vendor lock-in te voorkomen testen we
52+
skills met meerdere AI-assistants, waarvan minimaal een open source.
53+
54+
:::
55+
56+
## Wat zijn skills?
57+
58+
Een skill is een Markdown-bestand met instructies en referentiemateriaal voor
59+
een AI-assistant. Denk aan de checklist die een piloot doorloopt voor vertrek.
60+
De piloot kan vliegen, maar de checklist zorgt dat er niets wordt overgeslagen.
61+
62+
Er zit geen code in en je hoeft niets te finetunen. Het is gewoon een
63+
Markdown-bestand met gestructureerde kennis.
64+
65+
Skills activeren op basis van context. Als je een REST API bouwt, laadt je
66+
assistant de API Design Rules. Configureer je een mailserver, dan komen de
67+
DMARC- en DKIM-richtlijnen erbij. Je hoeft als developer niet eens te weten dat
68+
een bepaalde standaard bestaat.
69+
70+
Meerdere skills vormen samen een plugin, en plugins zijn vindbaar via een
71+
marketplace. Het formaat is een [open standaard](https://agentskills.io/home)
72+
die inmiddels door meer dan dertig tools wordt ondersteund, waaronder Claude
73+
Code, Opencode, Cursor, GitHub Copilot en Gemini CLI.
74+
75+
```mermaid
76+
flowchart TD
77+
A[Overheid marketplace] --> B[Logius standaarden]
78+
A --> C[developer.overheid.nl tools]
79+
B --> D[API Design Rules]
80+
B --> E[Logboek Dataverwerking]
81+
C --> F[Publiceer blogpost]
82+
C --> G[Generate publiccode.yml]
83+
```
84+
85+
_Voorbeeldhiërarchie. Meerdere skills vormen samen een plugin. Plugins kunnen
86+
gevonden worden via marketplaces._
87+
88+
## In actie: de API Design Rules
89+
90+
Je bouwt een REST API voor een overheidsorganisatie en vraagt je AI-assistant om
91+
een opzet. Zonder skill krijg je een generieke API die niet voldoet aan de
92+
[API Design Rules](https://gitdocumentatie.logius.nl/publicatie/api/adr/2.1.0/)
93+
van Logius. Endpoints in camelCase in plaats van kebab-case, foutmeldingen als
94+
vrije tekst in plaats van `problem+json`, geen versienummer in het pad.
95+
96+
Met de `/ls-api` skill zit dat er anders uit:
97+
98+
**Prompt:**
99+
100+
```md
101+
Maak een OAS die voldoet aan de ADR en verifieer of deze valid is. Het betreft
102+
een CRUD API waarmee men bieren, bierstijlen en brouwerijen kan ophalen. Een
103+
brouwerij heeft een naam, en adres. Een bier heeft een alcoholpercentage,
104+
gekoppelde bierstijl en gekoppelde brouwerij.
105+
```
106+
107+
**Zonder skill:**
108+
109+
```bash
110+
● Write(openapi.yaml)
111+
● Bash(npx @stoplight/spectral-cli lint /openapi.yaml \
112+
--ruleset https://static.developer.overheid.nl/adr/ruleset.yaml 2>&1)
113+
⎿ 16 errors, 1 warning found!
114+
⎿  (timeout 30s)
115+
116+
● De spec is niet ADR-compliant — 16 errors, 1 warning.
117+
```
118+
119+
**Met skill:**
120+
121+
```bash
122+
● Skill(standaarden:ls-api)
123+
⎿  Successfully loaded skill · 7 tools allowed · claude-sonnet-4-6
124+
● Write(openapi.yaml)
125+
● Bash(npx @stoplight/spectral-cli lint /openapi.yaml \
126+
--ruleset https://static.developer.overheid.nl/adr/ruleset.yaml 2>&1)
127+
⎿  No results with a severity of 'error' found!
128+
⎿  (timeout 30s)
129+
130+
● De spec is ADR-compliant — 0 errors, 0 warnings.
131+
```
132+
133+
Dit soort details bepalen of je API voldoet aan de standaard op de
134+
['pas toe of leg uit'-lijst](https://www.forumstandaardisatie.nl/open-standaarden/rest-api-design-rules).
135+
De skill bevat verder naamconventies (kebab-case paden, camelCase parameters),
136+
de verplichte OpenAPI-specificatie op `/openapi.json`, security headers, en een
137+
implementatiechecklist van veertien punten. Of, zoals de AI-assistant zelf
138+
aangeeft op de vraag wat het verschil is tussen het uitvoeren van de prompt mét
139+
en zonder skill:
140+
141+
```bash
142+
De skill zorgt ervoor dat ik de ADR-specifieke regels (zoals de verplichte
143+
API-Version header en de problem+json foutstructuur) direct goed toepas,
144+
in plaats van terug te vallen op gangbare REST-conventies die net niet aan
145+
de Nederlandse standaard voldoen.
146+
147+
Wat ik zonder skill fout deed:
148+
149+
┌────────────────────┬──────────────────────────┬──────────────────────────────────┐
150+
│ADR-regel │Fout zonder skill │Wat de skill wist │
151+
├────────────────────┼──────────────────────────┼──────────────────────────────────┤
152+
│API-Version header │Vergeten op alle responses│Verplichte header op elke response│
153+
├────────────────────┼──────────────────────────┼──────────────────────────────────┤
154+
│Versie in server URL│/api/v1/... in paden │Linter checkt server URL │
155+
├────────────────────┼──────────────────────────┼──────────────────────────────────|
156+
│Problem details │Eigen Error schema │RFC 9457 │
157+
├────────────────────┼──────────────────────────┼──────────────────────────────────┤
158+
│Query parameters │brewery_id (snake_case) │camelCase: brouwerijId │
159+
└────────────────────┴──────────────────────────┴──────────────────────────────────┘
160+
161+
```
162+
163+
De API Design Rules skill is een van tien skills in de
164+
[standaarden-plugin](https://github.com/developer-overheid-nl/skills-standaarden),
165+
die samen 77 GitHub-repositories en negen domeinen afdekt. Er zijn ook plugins
166+
voor
167+
[internetstandaarden](https://github.com/developer-overheid-nl/skills-internet)
168+
(internet.nl),
169+
[geo-standaarden](https://github.com/developer-overheid-nl/skills-geo)
170+
(Geonovum) en
171+
[NeRDS-richtlijnen](https://github.com/developer-overheid-nl/developer-overheid-nl-agent-skills).
172+
173+
## Waarom standaarden zich hier goed voor lenen
174+
175+
Overheidsstandaarden beschrijven regels en vereisten. Dat soort gestructureerde
176+
kennis past goed in een skill. Ze zijn publiek en open, en veelal met licenties
177+
die dit toestaan. En ze veranderen niet elke week, waardoor skills actueel
178+
blijven. En als ze wel veranderen, dan weten we dat direct omdat we de bronnen
179+
monitoren.
180+
181+
Daarnaast lossen skills een praktisch probleem op. De meeste developers kennen
182+
een handjevol standaarden, terwijl er tientallen relevant zijn voor hun werk.
183+
Met skills zit die kennis in het gereedschap zelf.
184+
185+
## Meedoen
186+
187+
De
188+
[skills marketplace](https://github.com/developer-overheid-nl/skills-marketplace)
189+
is openbaar en bruikbaar. Installeren kan in Claude Code of Cursor, zie de
190+
instructies in de repository.
191+
192+
Feedback is welkom via GitHub issues, zeker als een skill een standaard verkeerd
193+
samenvat. We passen skills aan op basis van feedback.
194+
195+
Je kunt ook zelf skills schrijven. Je hoeft geen developer te zijn; als je de
196+
kennis hebt over een standaard of richtlijn, kun je die structureren in een
197+
Markdown-bestand. De
198+
[handleiding](https://github.com/developer-overheid-nl/skills-marketplace/blob/main/docs/plugin-maken.md)
199+
beschrijft hoe.
200+
201+
## Wat we hopen
202+
203+
We hebben nu zes plugins en tientallen skills, en dat groeit. We willen dat
204+
standaarden beschikbaar zijn in je terminal en editor, terwijl je code schrijft.
205+
206+
De repositories zijn open. Probeer het uit en laat weten wat je ervan vindt!

0 commit comments

Comments
 (0)