Een eigen skill voor Claude schrijven en delen

Een skill maakt van instructies die je steeds plakt een bestand dat Claude zelf laadt. Waar je de map zet, bepaalt wie hem gebruikt: jij, je team of iedereen.

Wie Claude een tijd gebruikt, plakt steeds dezelfde instructies in het gesprek. Hoe wij release notes schrijven. Waar we op letten bij de review van een pull request. Welke woorden niet in onze teksten mogen. Elke nieuwe sessie begint met hetzelfde blok tekst, en wie het een keer vergeet, krijgt output die net niet klopt.

Een skill maakt van dat blok een bestand dat Claude zelf laadt wanneer de taak opduikt. Je schrijft de instructies één keer, Claude herkent wanneer ze van toepassing zijn, en je collega's werken met dezelfde versie in plaats van elk met hun eigen kopie in een notitiebestand.

Wat een skill precies is

Een skill is een map met daarin een bestand SKILL.md. Bovenaan dat bestand staat een korte YAML-header, daaronder volgen de instructies in Markdown. Naast SKILL.md kan de map extra referentiebestanden of scripts bevatten, bijvoorbeeld een voorbeeld van een geslaagde tekst of een script dat gegevens ophaalt.

release-notes/
├── SKILL.md
└── style.md

Hoe Claude een skill laadt, bepaalt hoe je hem schrijft. Bij de start ziet Claude van elke skill enkel de naam en de description. De body van SKILL.md leest hij pas wanneer de skill nodig is, en extra bestanden pas wanneer SKILL.md ernaar verwijst. Scripts worden uitgevoerd en niet gelezen, dus ze kosten geen context.

Daaruit volgt dat de description het deel is waar je de meeste tijd in steekt. Claude legt de taak naast die paar regels en beslist op basis daarvan of hij de rest opent. Een vage description levert een skill op die niet geladen wordt, hoe goed de instructies eronder ook zijn.

De description is het enige deel van je skill dat Claude altijd leest. Al de rest hangt ervan af.

Een skill voor release notes

Als voorbeeld nemen we een skill met de naam release-notes. Die zet de git-commits sinds de laatste release om in release notes voor klanten: geen commitberichten als 'fix typo in handler', maar zinnen die een gebruiker begrijpt en waar hij iets aan heeft. Voor de header en de body gelden een paar vaste regels.

name: kleine letters, cijfers en koppeltekens, maximaal 64 tekens
description: maximaal 1024 tekens, met wat de skill doet en wanneer hij gebruikt moet worden
de belangrijkste toepassing als eerste in de description
body: een korte genummerde procedure, geen essay
SKILL.md onder ongeveer 500 regels

---
name: release-notes
description: Writes customer-facing release notes from the git commits since the last tag. Use when asked for release notes, a changelog entry, or what changed since the last release.
---

# Release notes

1. Find the last release tag: `git describe --tags --abbrev=0`
2. List the commits since then: `git log <tag>..HEAD --oneline --no-merges`
3. Group the changes under New, Improved and Fixed. Skip refactors, tests and dependency updates.
4. Write one plain sentence per change, for a customer rather than a developer. No commit hashes.
5. Follow the tone and examples in [style.md](style.md).

De description begint met het geval dat het vaakst voorkomt: release notes opstellen voor een nieuwe versie. Andere aanleidingen, zoals een changelog bijwerken, komen daarna. De body zelf is een reeks stappen die Claude afloopt: de laatste release vinden, de commits sinds dan verzamelen, interne wijzigingen weglaten, de rest groeperen en herschrijven in klanttaal. Een procedure laat minder ruimte voor interpretatie dan een uitleg over wat goede release notes zijn.

Detail dat niet bij elke run nodig is, hoort in een apart bestand. Denk aan een stijlgids voor klantgerichte teksten of een lijst met officiële productnamen. SKILL.md verwijst ernaar en zegt er telkens bij wat elk bestand bevat, zodat Claude weet wanneer het de moeite loont om het te openen. Zo blijft de skill licht in de gevallen waarin dat detail niet nodig is.

In Claude Code hoef je niet te wachten tot Claude de skill zelf oppikt. Typ /release-notes en de skill wordt rechtstreeks aangeroepen. Dat is handig tijdens het testen, en voor taken waarvan je op voorhand weet dat ze deze skill nodig hebben.

Waar je de skill plaatst

Waar de map staat, bepaalt wie de skill kan gebruiken. Er zijn vier mogelijkheden, en ze verschillen in meer dan het pad: ook in hoe wijzigingen bij anderen terechtkomen en wat er gebeurt als twee skills dezelfde naam dragen.

Alleen voor jezelf, in Claude Code

Zet de map in ~/.claude/skills/ in je thuismap. De skill werkt dan in al je projecten, maar alleen op je eigen machine. Dit is de plek voor persoonlijke werkgewoontes, en voor een skill die je eerst zelf wilt uitproberen voor je hem met anderen deelt.

Gedeeld met je team, in Claude Code

Zet de map in .claude/skills/ binnen de projectrepository en commit hem. Iedereen die in die repository werkt, krijgt de skill, en wijzigingen gaan door dezelfde review en versiegeschiedenis als code. Wie de release-notes-skill aanpast, doet dat dus in een pull request dat een collega kan tegenhouden. Let wel op namen: hebben een persoonlijke en een projectskill dezelfde naam, dan wint de persoonlijke, en dan zie je zelf iets anders dan de rest van het team.

Publiek of over veel repositories

Wil je een skill in veel repositories gebruiken of publiek delen, verpak hem dan in een plugin en publiceer die in een plugin-marketplace. Zo'n marketplace is gewoon een git-repository. Anderen voegen hem toe met /plugin marketplace add, gevolgd door de repository, en installeren daarna met /plugin install. Skills uit een plugin krijgen de pluginnaam als namespace, zodat jouw release-notes nooit botst met die van iemand anders.

In de Claude-apps

Op claude.ai zip je de map en upload je hem via Settings, Features. Geüploade skills zijn persoonlijk: elke collega uploadt zijn eigen kopie, en ze synchroniseren niet met Claude Code. Een aanpassing moet je dus zelf aan iedereen bezorgen. De apps aanvaarden bovendien maar een handvol headervelden, waaronder name en description, dus een skill die in beide omgevingen moet werken, houdt het best bij die twee.

Nagaan of een skill werkt

Het formaat volgt een open standaard, Agent Skills. Anthropic biedt daarnaast een skill-creator-plugin die helpt bij het schrijven, testen en bijstellen van een skill. Die neemt een deel van het eerste werk uit handen, maar of je skill de output beter maakt, moet je nog altijd zelf nagaan.

Voer daarvoor dezelfde taak uit in een nieuwe sessie, één keer met en één keer zonder de skill, en leg de resultaten naast elkaar. Dat Claude de skill oppikt, bewijst alleen dat hij hem gevonden heeft, niet dat hij geholpen heeft. Levert de versie met skill dezelfde release notes op als die zonder, dan voegt de skill nog niets toe, en daar begint de volgende ronde.