scaccogatto/okf-skills

Open Knowledge Format (OKF) Skill

OKF repräsentiert Wissen als Verzeichnis von Markdown-Dateien mit YAML-Frontmatter. Es ist bewusst minimalistisch gehalten: kein Schema-Register, keine Laufzeit, kein SDK. Ihre Aufgabe ist es, OKF-Bündel konform zur Spezifikation zu erstellen, zu verwalten und zu konsumieren – nicht aus dem Gedächtnis.

Lesen Sie vor nicht-trivialen Arbeiten immer die kanonische Spezifikation: reference/SPEC.md. Sie ist die wörtliche OKF v0.1 Spezifikation und die Quelle der Wahrheit für jede der folgenden Regeln.

Die eine harte Regel

Ein Bündel ist konform (§9) genau dann, wenn: jede nicht-reservierte .md-Datei einen parsbaren YAML-Frontmatter-Block hat, und jeder solche Block ein nicht leeres type-Feld besitzt. Alles andere ist weiche Richtlinie. Konsumenten MÜSSEN fehlende optionale Felder, unbekannte Typen und defekte Links tolerieren – ein Bündel niemals deswegen ablehnen.

Anzuwendende Konventionen

• Ein Konzept = eine Datei. Der Dateipfad (ohne .md) ist die Konzept-ID.
• Frontmatter: type ist erforderlich. Fügen Sie title, description, tags, timestamp (ISO 8601) hinzu, wenn sie die Nutzung unterstützen; fügen Sie resource (ein kanonischer URI) nur für Konzepte hinzu, die an ein reales Asset gebunden sind – weglassen für abstrakte Konzepte.
• Textkörper: bevorzugen Sie strukturelles Markdown (Überschriften, Tabellen, Listen, Codeblöcke). Übliche Überschriften: # Schema, # Beispiele, # Zitate.
• Querverweise: Standard-Markdown-Links; bevorzugen Sie die absolute Bündel-relative Form (/services/auth-api.md). Ein Link behauptet eine Beziehung; seine Art lebt im umgebenden Text, nicht im Link.
• Reservierte Dateien: index.md (Verzeichnisliste, kein Frontmatter – außer dem Stammverzeichnisindex, der nur okf_version enthalten darf) und log.md (ISO-datierte Änderungshistorie, neueste zuerst). Verwenden Sie diese Namen niemals für Konzepte.

Vorlagen zum Kopieren: Konzept, Index, Log.

Standard-Bündelspeicherort

Verwenden Sie .okf/ im Repository-Stammverzeichnis, es sei denn, das Projekt verwendet bereits einen anderen Ort. Committen Sie es zusammen mit dem Code, den es beschreibt – Wissen als Code.

Modi

produce — ein Bündel erstellen oder erweitern

1. Lesen Sie reference/SPEC.md.
2. Wählen Sie die Quelle(n): Code (Konzepte aus Quellcode, READMEs, Docstrings, Konfiguration ableiten), Dokumentation/Wiki (Seiten zu Konzepten destillieren, die Originale unter # Zitate verlinken), Manuell (Entscheidungen, Playbooks, Metriken).
3. Wählen Sie eine Verzeichnisstruktur nach Domäne (z. B. services/, datasets/, decisions/). Ein Konzept pro Datei.
4. Schreiben Sie jedes Konzept aus templates/concept.md: setzen Sie einen beschreibenden type, füllen Sie empfohlene Felder aus, verlinken Sie verwandte Konzepte.
5. Fügen Sie index.md pro Verzeichnis hinzu/aktualisieren Sie es (und okf_version: „0.1“ im Stamm- Index). Fügen Sie einen datierten Eintrag in log.md an.
6. Validieren Sie (siehe unten). Beheben Sie jeden Fehler vor dem Abschluss.

maintain — ein Bündel mit der Realität synchron halten

1. Identifizieren Sie, welche Konzepte die Änderung betrifft (Suche nach resource, Pfad oder Thema). Diese Buchhaltung ist genau das, worin Agenten gut sind – bearbeiten Sie alle betroffenen Dateien in einem Durchlauf.
2. Aktualisieren Sie den Textkörper und timestamp; korrigieren oder fügen Sie Querverweise hinzu; erstellen Sie neue Konzepte für neue Assets; markieren Sie entfernte Assets (**Deprecation**), anstatt stillschweigend Kontext zu löschen.
3. Aktualisieren Sie die relevanten index.md-Dateien und fügen Sie einen datierten log.md-Eintrag an, der beschreibt, was sich geändert hat.
4. Validieren Sie.

consume — ein Bündel als Kontext nutzen

1. Lesen Sie zuerst das Stamm-index.md für progressive Offenlegung, folgen Sie dann Links nur zu den für die Aufgabe relevanten Konzepten.
2. Behandeln Sie defekte Links als noch nicht geschriebenes Wissen, nicht als Fehler.
3. Wenn Sie während der Arbeit etwas Dauerhaftes lernen, wechseln Sie zu maintain und schreiben Sie es zurück.

Validierung (vor dem Abschluss durchführen)

Überprüfen Sie die Konformität niemals manuell – führen Sie den deterministischen Prüfer aus. Rufen Sie den begleitenden validate-Skill (/okf:validate <bundle-dir> --strict) auf, der den Prüfer enthält. Wenn dieser Skill nicht installiert ist, führen Sie ihn direkt aus:

uv run "${CLAUDE_SKILL_DIR}/../validate/scripts/okf_validate.py" <bundle-dir> --strict

Beheben Sie jeden ERROR (harte §9-Fehler). Warnungen sind weich; beheben Sie sie, wenn es günstig ist, sie blockieren jedoch nie.