Das Problem: Überlange Kontext-Dateien

Claude Code verwendet CLAUDE.md Dateien, um projektspezifischen Kontext bereitzustellen. Bei komplexen Infrastruktur-Projekten wie matzka.cloud wächst diese Datei schnell auf über 1000 Zeilen an:

• Server-Konfigurationen
• Service-spezifische Befehle
• Troubleshooting-Anleitungen
• Environment Variables
• Netzwerk-Topologie
• Deployment-Prozesse

Die Lösung: Skills

Claude Code unterstützt Skills — modulare Markdown-Dateien, die nur bei Bedarf geladen werden. Statt alles in einer monolithischen CLAUDE.md zu halten, lagern wir service-spezifische Details in separate Skill-Dateien aus.

Vorher vs. Nachher

Metrik	Vorher	Nachher
CLAUDE.md Zeilen	1425	248
Immer geladener Kontext	100%	~17%
Service-Details	In CLAUDE.md	In Skills
Abruf	Automatisch	On-demand via /skillname

Implementierung

Schritt 1: Skills-Verzeichnis erstellen

Skills werden in ~/.claude/skills/ als Markdown-Dateien gespeichert:

mkdir -p ~/.claude/skills

Schritt 2: Inhalte identifizieren und auslagern

Wir haben folgende Kategorien identifiziert:

Skill	Inhalt	Zeilen
/mailcow	Mail server, SMTP, Autodiscover	92
/nextcloud	Cloud storage, SSO, occ commands	48
/authentik	SSO config, User management	78
/wazuh	SIEM, Fail2ban, Trivy, Custom Rules	197
/monitoring	Prometheus, Grafana, Umami	117
/n8n	Workflows, Qdrant, Docling	90
/updates	Watchtower, Diun, Dockge, Watchdog	122
/backup	Volumes, Restore-Prozess	123
/blog	Blog-Post Erstellung (MD + HTML)	165

Schritt 3: CLAUDE.md auf Kern-Kontext reduzieren

Die neue CLAUDE.md enthält nur noch:

• Project Overview — Was ist matzka.cloud?
• Repository Structure — Wo liegt was?
• Network Topology — Wie hängen Services zusammen?
• SSH Commands — Grundlegende Server-Befehle
• Common Tasks — Deployment, SSL, Routing
• Security Considerations — Kritische Hinweise
• Skill-Übersicht — Welche Skills gibt es?

Skill-Struktur

Jeder Skill folgt einem einheitlichen Format:

# Service Name

**Location:** /path/to/service
**Domain:** subdomain.matzka.cloud
**Version:** X.Y.Z

## Components

- Component 1 - Beschreibung
- Component 2 - Beschreibung

## Useful Commands

```bash
ssh root@ssh2.matzka.cloud "docker logs -f service"
```

## Environment Variables

```bash
SERVICE_PASSWORD=<base64_32_chars>
```

## Troubleshooting

### Problem 1
**Symptom:** ...
**Lösung:** ...

## Related Documentation

- `DEPLOYMENT_GUIDE.md` - Deployment details

Verwendung

Skill laden

/mailcow

Claude Code lädt dann den Inhalt von ~/.claude/skills/mailcow.md und hat alle Mailcow-spezifischen Informationen verfügbar.

Mehrere Skills kombinieren

Bei komplexen Aufgaben können mehrere Skills geladen werden:

/wazuh
/monitoring

Erstellte Skills für matzka.cloud

Infrastructure Skills

Skill	Beschreibung
/mailcow	Mailcow Mail Server (mail.matzka.cloud)
/nextcloud	Nextcloud Cloud Storage (next.matzka.cloud)
/authentik	Authentik SSO (auth.matzka.cloud)
/n8n	n8n Workflow Automation (n8n.matzka.cloud)

Operations Skills

Skill	Beschreibung
/monitoring	Prometheus, Grafana, Umami Analytics
/updates	Watchtower, Diun, Dockge, Watchdog
/backup	Docker Volume Backups
/wazuh	Wazuh SIEM Security Monitoring

Utility Skills

Skill	Beschreibung
/blog	Blog-Post Erstellung (MD + HTML Templates)

Best Practices

1. Skill-Größe begrenzen

Ein Skill sollte 200-300 Zeilen nicht überschreiten. Wenn ein Skill zu groß wird, aufteilen:

/wazuh → /wazuh-rules, /wazuh-alerts, /wazuh-agent

2. Selbsterklärende Namen

Skill-Namen sollten sofort klar machen, worum es geht:

• ✓ /mailcow — Klar: Mailcow Mail Server
• ✓ /backup — Klar: Backup-System
• ✗ /misc — Unklar: Was ist drin?

3. Konsistente Struktur

Alle Skills sollten die gleiche Grundstruktur haben:

1. Header mit Location, Domain, Version
2. Components/Services
3. Useful Commands
4. Environment Variables
5. Troubleshooting
6. Related Documentation

4. Querverweise

Skills können auf andere Skills verweisen:

## Related Skills

- `/authentik` - SSO-Konfiguration für diesen Service
- `/monitoring` - Prometheus-Metriken

Ergebnis

Kontextreduktion

Vorher:  1425 Zeilen immer geladen
Nachher:  248 Zeilen Basis + Skills on-demand

Reduktion: 83% weniger Basis-Kontext

Flexibilität

• Mailcow-Problem? → /mailcow laden
• Security-Audit? → /wazuh laden
• Blog schreiben? → /blog laden

Nur der relevante Kontext wird geladen.

Wartbarkeit

• Änderungen an einem Service? → Nur einen Skill aktualisieren
• Neuer Service? → Neuen Skill erstellen
• CLAUDE.md bleibt stabil

Fazit

Die Aufteilung in Skills bringt mehrere Vorteile:

Für komplexe Infrastruktur-Projekte ist diese modulare Dokumentation ein Game-Changer für die Arbeit mit Claude Code.

Nächste Schritte

• Skill-Dokumentation in Directus CMS integrieren
• Automatische Skill-Generierung aus Docker Compose Files
• Skill-Versionierung mit Git Tags