Skill Chunk MD

Wandeln Sie Markdown in CtxFST-Dokumente mit semantischen <Chunk>-Tags, strukturierter Frontmatter und einer expliziten Entitätsschicht um.

Ziel

Verwenden Sie diese Fähigkeit, um Dokumente zu erstellen, die beides unterstützen:

Chunk-Retrieval für detaillierten Kontext
Entity-Retrieval für Navigation, Grapherweiterung und Entdeckung verwandter Konzepte

Zerteilen Sie Text nicht nur. Extrahieren Sie auch die wichtigen Domain-Entitäten, normalisieren Sie sie und verknüpfen Sie jeden Chunk mit den Entitäten, die er tatsächlich behandelt.

Layout-Auswahl

Entscheiden Sie frühzeitig, ob die Quelle notizförmig oder gedächtnisförmig ist:

Notizförmig (ein Profil, ein Benchmark, ein Meeting-Log): Verwenden Sie das unten beschriebene Standard-Layout mit mehreren Entitäten pro Datei.
Gedächtnisförmig (eine Wissensdatenbank, die im Laufe der Zeit wächst, entitätsspezifische Dossiers, Agentengedächtnis): Verwenden Sie die Entity-Centric-Konvention – eine Datei pro Entität, Dateiname entity-<id-suffix>.ctxfst.md, entities: mit genau einem Eigentümer, jeder Chunk referenziert den Eigentümer. Querverweise verwenden Entitäts-IDs und lösen sich zu anderen Dateien auf.

Entity-Centric ist eine Konvention, keine Schemaänderung. Dieselben Frontmatter-Regeln gelten; der Unterschied ist, dass len(entities) == 1 und der Dateiname den Eigentümer trägt. Siehe assets/examples/entity-centric/ für ein ausgearbeitetes Beispiel und validieren Sie mit python3 scripts/validate_chunks.py <path> --entity-centric.

Zielformat

CtxFST-Dokumente sollten enthalten:

YAML-Frontmatter
Dokumentweiten entities-Katalog
Dokumentweiten chunks-Katalog
Textkörper, umschlossen von <Chunk>-Tags

---
title: "Dokumenttitel"
entities:
  - id: entity:python
    name: Python
    type: skill
    aliases: [python3]
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []
chunks:
  - id: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "Python-Backend-Arbeit mit Fokus auf APIs, die mit FastAPI erstellt wurden"
---

<Chunk id="skill:python-api">
## Python-API-Arbeit
Ich verwende Python und FastAPI, um REST-APIs zu erstellen...
</Chunk>

Kernprinzip

Verwenden Sie Chunks als Inhaltscontainer und Entitäten als semantischen Index.

Chunks beantworten: "Welche genaue Passage soll abgerufen werden?"
Entitäten beantworten: "Zu welchem Konzept gehört diese Passage?"

Tags sind nützlich für breite Filterung. Entitäten sind die kanonischen Graphknoten.

Kern-Workflow

Schritt 1: Dokumentstruktur analysieren

Identifizieren Sie semantische Grenzen im Quell-Markdown:

Überschriften (##, ###), die ein neues Thema einführen
Thematische Verschiebungen innerhalb langer Abschnitte
Listen, die ein zusammenhängendes Konzept beschreiben
Codeblöcke plus deren Erklärung, wenn sie zusammenbleiben sollen

Schritt 2: Chunk-Grenzen bestimmen

Jeder Chunk sollte sein:

In sich geschlossen: verständlich, wenn er allein abgerufen wird
Fokussiert: auf ein Hauptthema oder einen eng verwandten Unterthema zentriert
Abrufbar: nützlich als eigenständiges Antwortfragment

Größenrichtlinien:

Minimum: ~100 Tokens
Ziel: 300-800 Tokens
Maximum: ~1500 Tokens

Teilen Sie überdimensionierte Chunks, wenn sich das Thema ändert. Fügen Sie unterdimensionierte Chunks zusammen, wenn sie nicht für sich allein stehen können.

Schritt 3: Kandidaten-Entitäten extrahieren

Bevor Sie die Frontmatter schreiben, extrahieren Sie die domänenspezifischen Entitäten aus dem Dokument.

Achten Sie auf:

Hard Skills
Tools und Bibliotheken
Frameworks
Plattformen
Datenbanken
Protokolle und Standards
Architekturen und Design Patterns
Benannte Produkte oder Systeme

Machen Sie nicht jedes Substantiv zu einer Entität. Bevorzugen Sie Begriffe, die als Knoten in einem Wissensgraphen sinnvoll wären.

Schritt 4: Entitäten normalisieren und deduplizieren

Wandeln Sie rohe Erwähnungen in kanonische Entitäten um.

Normalisierungsregeln:

Verwenden Sie den am besten wiedererkennbaren kanonischen Namen: PostgreSQL, nicht postgres
Führen Sie Aliase zu einer Entität zusammen: JS -> JavaScript, K8s -> Kubernetes
Behalten Sie Akronym + Vollnamen nur dann, wenn beide tatsächlich als Aliase verwendet werden
Entfernen Sie generische Begriffe wie System, Projekt, Tool, Computer, Arbeit
Entfernen Sie beiläufige Erwähnungen, die semantisch nicht wichtig für den Abruf sind

Wenn Sie unsicher sind, ob etwas eine Entität ist, fragen Sie:

Würde dies helfen, verwandtes Wissen zu navigieren?
Würde dies einen eigenen Knoten in einem Skills-Graphen verdienen?
Würde das Abrufen von Chunks nach diesem Begriff sinnvolle Ergebnisse liefern?

Wenn die Antwort nein ist, lassen Sie es aus der Entitätenliste heraus.

Schritt 5: Entitäts-IDs generieren

Verwenden Sie das Format: entity:{kanonischer-name}

Beispiele:

entity:python
entity:fastapi
entity:postgresql
entity:event-driven-architecture

IDs müssen nach dem Präfix in Kleinbuchstaben und Kebab-Schreibweise sein.

Schritt 6: Chunk-IDs generieren

Verwenden Sie das Format: {kategorie}:{thema}[-{unterthema}]

Kategorie	Anwendungsfall	Beispiele
`skill:`	Technische Fähigkeiten	`skill:python`, `skill:react-hooks`
`about:`	Persönliche oder Organisationsinfo	`about:background`, `about:mission`
`project:`	Projektbeschreibungen	`project:graphrag`, `project:api-v2`
`principle:`	Richtlinien und Werte	`principle:security-first`
`workflow:`	Prozesse	`workflow:deployment`, `workflow:review`
`reference:`	Referenzmaterial	`reference:api-auth`, `reference:schema`

Schritt 7: YAML-Frontmatter erstellen

Definieren Sie sowohl entities als auch chunks.

---
title: "Mein Fähigkeitsdokument"
entities:
  - id: entity:python
    name: Python
    type: skill
    aliases: [python3]
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []
  - id: entity:pandas
    name: Pandas
    type: library
    aliases: []
chunks:
  - id: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "Python-Backend-Fähigkeiten mit Fokus auf REST-APIs und Service-Implementierung"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: []
  - id: skill:python-data
    tags: [Python, Data]
    entities: [entity:python, entity:pandas]
    context: "Python-Datenverarbeitungsfähigkeiten mit Fokus auf tabellarische Analyse und ETL-Arbeit"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: medium
    dependencies: []
---

Schritt 8: Chunks mit Entitäten verknüpfen

Jeder Chunk sollte die kanonischen Entitäten auflisten, die er tatsächlich behandelt.

Verknüpfungsregeln:

Fügen Sie Entitäten hinzu, die zentral für den Chunk sind
Überspringen Sie Entitäten, die nur beiläufig erwähnt werden
Bevorzugen Sie 1-6 Entitäten pro Chunk
Kopieren Sie nicht alle Dokumententitäten in jeden Chunk
Wenn zwei Chunks dieselbe Entität aus unterschiedlichen Gründen erwähnen, differenzieren Sie dies in context

Schritt 9: Inhalt mit `<Chunk>`-Tags umschließen

Wenden Sie <Chunk>-Tags an, die mit den Chunk-IDs der Frontmatter übereinstimmen.

<Chunk id="skill:python-api">
## Python-API-Arbeit

Ich verwende Python und FastAPI, um REST-APIs und interne Dienste zu erstellen.
</Chunk>

Schritt 10: Validieren und exportieren

Verwenden Sie die enthaltenen Skripte:

python3 scripts/validate_chunks.py document.md
python3 scripts/export_to_lancedb.py document.md --output chunks.json
python3 scripts/diagnose_chunks.py document.md --level suggest

Entitätsregeln

Was als Entität zählt

Bevorzugen Sie Entitäten, die:

Spezifisch sind
über mehrere Dokumente hinweg wiederverwendbar sind
als Graphknoten sinnvoll sind
nützlich für den Abruf oder die Erweiterung sind

Gute Beispiele:

Python
FastAPI
Docker
Kubernetes
CI/CD
Event-Driven Architecture
JWT

Normalerweise keine Entitäten:

Erfahrung
Technologie
Feature
Anwendung
Computer
Problem
Aufgabe

Entitätstypen

Verwenden Sie einen dieser Standardtypen:

skill
tool
library
framework
platform
database
architecture
protocol
concept
domain
product

Wenn keiner gut passt, verwenden Sie concept, anstatt viele benutzerdefinierte Typen zu erfinden.

Weltmodell-Entitätstypen

Wenn Sie Dokumente erstellen, die an einem Weltmodell oder Agenten-Loop teilnehmen, stehen diese zusätzlichen Typen zur Verfügung:

state — Weltzustandsknoten (z.B. entity:resume-parsed)
action — ausführbare Aktion (z.B. entity:analyze-resume)
goal — Aufgabenobjektiv (z.B. entity:learn-kubernetes-path)
agent — Akteur oder Benutzer (z.B. entity:ian-chou)
evidence — Beobachtungsergebnis (z.B. entity:docker-3yr-experience)

Weltmodell-YAML-Felder

SKILL.md-Dateien, die an einem Weltmodell teilnehmen, können diese optionalen YAML-Frontmatter-Felder enthalten:

---
name: analyze-resume
description: "Analysiere rohen Lebenslauf und extrahiere Fähigkeitsnachweise"
# === Weltmodell-Felder (alle optional) ===
preconditions:
  - "entity:has-raw-resume"
  - "NOT entity:has-parsed-resume"
postconditions:
  - "entity:has-parsed-resume"
  - "entity:has-skill-evidence"
related_nodes:
  - "entity:resume-parsing"
  - "entity:skill-extraction"
related_skills:
  - "career-mapping"
  - "skill-gap-analysis"
cost: low
idempotent: true
---

Feld	Typ	Beschreibung
`preconditions`	`string[]`	Zustandsentitäten, die existieren müssen, bevor diese Fähigkeit ausgeführt werden kann
`postconditions`	`string[]`	Zustandsentitäten, die nach der Ausführung erstellt oder aktualisiert wurden
`related_nodes`	`string[]`	Ankerpunkte im semantischen Graphen
`related_skills`	`string[]`	Aufeinanderfolgende oder komplementäre Fähigkeitsnamen
`cost`	`enum`	`low`, `medium`, `high` — geschätzte Ausführungskosten
`idempotent`	`bool`	Ob es sicher ist, ohne Nebenwirkungen erneut auszuführen

Vorbedingungen verwenden das NOT-Präfix für Negation (z.B. "NOT entity:has-parsed-resume" bedeutet, dass dieser Zustand nicht existieren darf).

Tags vs. Entitäten

Verwenden Sie Tags für:

breite Klassifikation
Filterung
Dokumentenorganisation

Verwenden Sie Entitäten für:

kanonische Konzeptidentität
Chunk-zu-Graph-Verknüpfung
Ähnlichkeits- und Traversal-Workflows
konzeptübergreifende Wiederverwendung in Dokumenten

Beispiel:

Tag: Backend
Entität: entity:fastapi

Frontmatter-Schema

Entitätsschema

entities:
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []

Erforderliche Felder:

id
name
type

Optionales Feld:

aliases

Chunk-Schema

chunks:
  - id: skill:python-api
    tags: [Python, Backend, API]
    entities: [entity:python, entity:fastapi]
    context: "Python-Backend-Fähigkeiten mit Fokus auf REST-APIs, die mit FastAPI erstellt wurden"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: []

Empfohlene Felder:

id
entities
context

Optionale Felder:

tags
created_at
version
type
priority
dependencies

Kontext-Schreibregeln

Jeder Chunk-context sollte:

die Rolle des Chunks im Dokument erklären
den unterscheidenden Anwendungsfall erwähnen
die verknüpften Entitäten natürlich widerspiegeln
vermeiden, den ersten Satz wörtlich zu kopieren

Gut:

"Python-Backend-Fähigkeiten mit Fokus auf REST-APIs, asynchrone Dienste und FastAPI-basierte Implementierung"

Schwach:

"Dieser Chunk spricht über Python"

Beispiel-Transformation

Vorher

## Über mich

Ich bin ein Backend-Ingenieur mit Fokus auf APIs und verteilte Systeme.

## Python

Ich verwende Python für REST-APIs und interne Tools.

### Wichtige Bibliotheken
- FastAPI für Webdienste
- Pandas für Datenverarbeitung

Nachher

---
title: "Profil"
entities:
  - id: entity:python
    name: Python
    type: skill
    aliases: [python3]
  - id: entity:fastapi
    name: FastAPI
    type: framework
    aliases: []
  - id: entity:pandas
    name: Pandas
    type: library
    aliases: []
chunks:
  - id: about:background
    tags: [About, Erfahrung]
    entities: []
    context: "Beruflicher Hintergrund als Backend-Ingenieur, der an APIs und verteilten Systemen arbeitet"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: medium
    dependencies: []
  - id: skill:python
    tags: [Python, Backend]
    entities: [entity:python, entity:fastapi, entity:pandas]
    context: "Python-Fähigkeiten für API-Entwicklung, Service-Arbeit und Datenverarbeitung"
    created_at: "2026-03-08"
    version: 1
    type: text
    priority: high
    dependencies: [about:background]
---

<Chunk id="about:background">
## Über mich

Ich bin ein Backend-Ingenieur mit Fokus auf APIs und verteilte Systeme.
</Chunk>

<Chunk id="skill:python">
## Python

Ich verwende Python für REST-APIs und interne Tools.

### Wichtige Bibliotheken
- FastAPI für Webdienste
- Pandas für Datenverarbeitung
</Chunk>

GraphRAG-Anleitung

Bereiten Sie Dokumente für graphorientierten Abruf vor:

Behandeln Sie entities als den kanonischen Knotenbestand
Behandeln Sie Chunk-entities-Arrays als Chunk-zu-Entität-Kanten
Behandeln Sie dependencies als Chunk-zu-Chunk-Voraussetzungsverknüpfungen
Halten Sie Tags breit und Entitäten präzise

Verlassen Sie sich nicht allein auf Tags, wenn das Ziel die entitätsbasierte Navigation ist.

Wann nicht viele Entitäten extrahiert werden sollten

Seien Sie konservativ, wenn:

das Dokument sehr kurz ist
das Dokument überwiegend erzählerisch ist und wenige Domänenbegriffe enthält
dasselbe Konzept ohne nützliche Unterscheidungen wiederholt wird
die Quelle verrauscht ist und die Entitätsextraktion Junk-Knoten erzeugen würde

Geben Sie in diesen Fällen einen kleineren, saubereren Entitätssatz zurück.

Validierung

Überprüfen Sie nach der Konvertierung:

Jede <Chunk>-ID existiert in chunks
Jeder chunks[].entities-Verweis existiert in entities
Entitäts-IDs sind eindeutig und kanonisch
Chunk-IDs sind eindeutig
Es gibt keine verschachtelten Chunks
Kontextfelder unterscheiden ähnliche Chunks
Generische oder verrauschte Entitäten wurden entfernt

python3 scripts/validate_chunks.py path/to/document.md

Diagnose

Wenn der Benutzer um eine Diagnose bittet, überprüfen Sie sowohl die Chunk-Qualität als auch die Entitätsqualität.

Prüfkategorien

Chunk-Ähnlichkeit
- Markieren Sie Chunks, die zu ähnlich sind, um sie beim Abruf zu unterscheiden
Kontextqualität
- Markieren Sie vage, sich wiederholende oder übermäßig kurze Kontextfelder
Tag-Überlappung
- Markieren Sie Tags, die überall vorkommen und nicht mehr helfen, zu filtern
Entitätsrauschen
- Markieren Sie generische oder minderwertige Entitäten
Entitätsduplizierung
- Markieren Sie Aliase, die in einen kanonischen Knoten zusammengeführt werden sollten
Chunk-zu-Entität-Verknüpfung
- Markieren Sie Chunks mit fehlenden, übermäßigen oder irrelevanten Entitätsverknüpfungen

Diagnose-Prompts

Nur Diagnose:

Überprüfen Sie dieses Dokument auf Probleme mit Chunk- und Entitätsqualität

In Ihrer bevorzugten KI fragen

Dokumentation