Claude Skills leerlijn — Deel 1: Wat zijn Claude Skills?

Claude Skills zijn het mechanisme waarmee je Claude Code uitbreidt met herbruikbare, gespecialiseerde gedragingen. Denk aan Conductions eigen /review-pr, /opsx-new of de hele hydra-gate-* familie: stuk voor stuk skills. Dit eerste deel legt in tien minuten uit wát een skill is, hoe hij geactiveerd wordt, en wanneer je beter géén skill maakt. Het is deel 1 van een leerlijn van vier; aan het eind sta je klaar om er in deel 2 zelf een te schrijven — en in deel 3 introduceren we het 7-level maturity-framework waarmee je een skill van "voelt goed" naar "gemeten goed" brengt (deel 4 gaat door op L6 en L7).

In één zin

Een Claude Skill is een mapje onder .claude/skills/<naam>/ met daarin een SKILL.md (en optioneel scripts, voorbeelden, referentiebestanden). De frontmatter van die SKILL.md vertelt Claude wanneer de skill relevant is; de inhoud is de instructie die Claude volgt zodra de skill geladen wordt.

Praktisch: een skill is een bundel-eenheid van gedrag. In plaats van duizend regels prompt-tekst in CLAUDE.md te plakken, of telkens dezelfde instructies opnieuw te typen, schrijf je het één keer als skill. Hergebruikbaar, testbaar, en deelbaar met je team.

.claude/skills/
└── review-pr/
    ├── SKILL.md          ← verplicht: de skill-logica
    ├── templates/        ← optioneel: bestanden met placeholders
    ├── references/       ← optioneel: standaarden en achtergrond
    ├── examples/         ← optioneel: voorbeelden van gewenste output
    └── scripts/          ← optioneel: shell- of Python-scripts

Hoe een skill wordt aangeroepen

Eén skill kan op twee manieren in actie komen:

1. Handmatig — je typt /review-pr in een Claude-sessie. Direct, voorspelbaar, en de skill draait precies wanneer jij dat wilt.
2. Automatisch — Claude leest de description van alle beschikbare skills mee en kiest er zelf eentje wanneer de huidige situatie matcht. Vraag bijvoorbeeld "kun je deze PR reviewen?" en Claude triggert vanzelf review-pr als die voorhanden is.

Welke mode is toegestaan, regel je in de frontmatter van de skill zelf:

• disable-model-invocation: true — alleen jij kunt 'm aanroepen via /<naam>. Gebruik dit voor skills met side-effects (/opsx-apply past code aan, /create-pr opent een PR). Claude mag dit niet zomaar uit zichzelf doen.
• user-invocable: false — alleen Claude zelf mag 'm laden. Gebruik dit voor achtergrondkennis die niet als actie zinvol is (bijvoorbeeld een legacy-system-context die alleen informeert).
• Geen van beide gezet → beide mogen. Default voor de meeste skills.

In een Hydra-pipeline draaien skills meestal automatisch: containers hebben geen toetsenbord en leunen op auto-activatie. Achter je eigen toetsenbord typ je vaker expliciet / voor controle.

De frontmatter, veld voor veld

Een minimale SKILL.md ziet er zo uit:

---
name: review-pr
description: Review a Pull Request — runs local checks, summarises the diff, and posts inline comments
metadata:
  category: Workflow
  tags: [github, review]
---

# Review PR

Korte uitleg van wat de skill doet.

**Input**: hoe je de skill aanroept en welke argumenten hij accepteert.

**Steps**

1. **Stap-naam**
   Instructies...

2. **Stap-naam**
   Instructies...

**Guardrails**
- Wat de skill nooit mag doen
- Wat hij moet checken voor destructieve acties

Drie velden vragen extra aandacht:

Waarom de description zoveel belangrijker is dan je denkt

Claude laadt skills in drie lagen:

Dat betekent: alleen je description staat altijd "aan". Is hij vaag, dan vuurt je skill nooit automatisch. Schrijf 'm in derde persoon, start met een werkwoord, en plak de meest specifieke trigger-woorden vooraan (alleen de eerste ~250 tekens zijn zichtbaar in skill-listings).

# Slecht — vaag, passief, geen trigger-woorden
description: A skill that helps with various document-related tasks

# Goed — specifiek, derde persoon, action-werkwoord vooraan
description: Create a Pull Request from the current branch — runs local checks, picks target branch, and opens the PR on GitHub

Verdiepende frontmatter-velden

Naast name, description en metadata zijn er een paar optionele velden die het gedrag van een skill subtiel sturen. Je hebt ze niet altijd nodig, maar weten dát ze bestaan helpt later:

Begin met de drie verplichte/basis-velden. Voeg de bovenstaande pas toe als je een concrete reden hebt — anders maak je je skill stiller of strikter dan nodig.

Naming convention: namespace-action

Skills heten standaard <namespace>-<action> met alleen kleine letters, cijfers en koppeltekens. Conduction gebruikt onder meer:

De mapnaam, het name-veld én de manier waarop je 'm typt (/<naam>) moeten allemaal exact gelijk zijn.

Skill vs. prompt vs. agent

Een veelgehoorde vraag: wanneer is een skill de juiste keuze, en wanneer iets anders? Drie categorieën, kort:

De pragmatische test: schrijf een skill als…

1. Het gedrag is herhaalbaar — meer dan eens nodig, op meer dan één plek.
2. Het is mechanisch beschrijfbaar — je kunt het in 1-3 alinea's instrueren, zonder dat het ontaardt in "het hangt van de context af".
3. Je teamgenoot zou hetzelfde willen doen — anders is het een persoonlijke macro, geen team-skill.

Voor één-keer-werk: gewoon prompten. Voor herhaalbaar werk: skill. Voor zware isolatie van een sub-werkstroom: subagent.

Waar skills "wonen"

Skills kunnen op drie niveaus liggen:

In Conduction-repo's leeft het overgrote deel als project-skills in <repo>/.claude/skills/. Dat zorgt dat het hele team — en Hydra's Docker-personas — exact dezelfde skills hebben.

Test jezelf

Vier korte vragen om te checken of je dit deel begrepen hebt. Vastgelopen? Klik Hint. Curieus naar het antwoord? Klik Antwoord.