Diese Datei ist für Skill-Konsumenten, nicht für Mitwirkende gedacht. Siehe AGENTS.md für den Entwicklungskontext – wie dieser Skill erstellt, iteriert und getestet wird.
Dokumentationsarbeitsbereich-Bootstrap
Dieser Skill lehrt einen AI-Agenten, wie er einen Dokumentationsarbeitsbereich von Grund auf in einem leeren (oder nahezu leeren) Verzeichnis erstellt. Das Ergebnis ist eine versionierte, dateisystembasierte, vollständig eigenständige Wissensdatenbank – im Besitz des Benutzers, kostenlos, ohne Vendor-Lock-In und so strukturiert, dass der darin arbeitende Agent sich nie um Organisation, Formatierung oder Werkzeuge kümmern muss.
Die Kernidee
Ein bootstrappter Arbeitsbereich enthält seine eigene AGENTS.md – eine pro Arbeitsbereich geltende, themenspezifische „eingefrorene Minianleitung“, die der Agent beim Betreten des Arbeitsbereichs liest. AGENTS.md wird aus einer Vorlage erstellt, die dieser Skill mitliefert. Sobald der Arbeitsbereich existiert, folgt der Agent der AGENTS.md, nicht diesem Skill. Das ist der ganze Zweck: die Regeln einmal vorher festlegen und dann nie wieder Tokens für deren Neuableitung verschwenden.
Wann dieser Skill verwendet werden soll
Verwenden Sie diesen Skill nur, wenn:
- Der Benutzer explizit einen Dokumentationsarbeitsbereich, ein Docs-Verzeichnis oder eine Wissensdatenbank erstellen/einrichten/initialisieren/scaffolden möchte.
- Das Zielverzeichnis leer oder nahezu leer ist (oder der Benutzer trotz vorhandener Dateien explizit zugestimmt hat).
- Das Zielverzeichnis noch keine
AGENTS.mdenthält (was bedeuten würde, dass es bereits bootstrappt ist).
Wenn am Zielort bereits eine AGENTS.md existiert: nicht diesen Skill ausführen. Lesen Sie die vorhandene AGENTS.md und befolgen Sie sie. Der Benutzer befindet sich bereits in einem bootstrappten Arbeitsbereich.
Wann dieser Skill NICHT verwendet werden soll
- Der Benutzer möchte ein Dokument hinzufügen, bearbeiten, verlinken oder innerhalb eines bestehenden Arbeitsbereichs umorganisieren – die eigene
AGENTS.mddes Arbeitsbereichs regelt das. - Der Benutzer möchte zu GitHub pushen, den Arbeitsbereich im Browser rendern oder Hosting einrichten – andere Anliegen, andere Skills.
- Der Benutzer stellt eine allgemeine Frage zu Dokumentation, Schreiben oder Notizen – kein Skill nötig.
Was der Skill erzeugt
Bei Ausführung erstellt dieser Skill einen Arbeitsbereich mit:
| Datei / Verzeichnis | Zweck |
|---|---|
AGENTS.md | Die pro Arbeitsbereich geltende „eingefrorene Minianleitung“. 95% Regeln, 5% Themenzusammenfassung. Der Agent liest sie beim Betreten. |
README.md | Übersicht auf Arbeitsbereichsebene. Reichhaltigere Einführung, automatisch generierter Index, Verweis auf AGENTS.md. |
index.yaml | Dokumentenreihenfolge für das Stammverzeichnis. Standardmäßig leer. |
.gitignore | Sinnvolle Standardeinstellungen: Backups, Betriebssystemmüll, Editor-Dateien, Node. |
package.json | Entwicklungsabhängigkeiten: prettier, markdownlint-cli, js-yaml. npm-Skripte für Werkzeuge. |
.prettierrc | Prettier-Konfiguration: 120-Zeichen-Zeilen, proseWrap preserve. |
.markdownlint.json | markdownlint-Konfiguration mit deaktivierten nitpick-Regeln. |
scripts/ | Hilfsskripte: format.js, validate.js, hash.js, reindex.js. |
assets/ | Leeres Verzeichnis für gemeinsame Ressourcen. Wird im Arbeitsbereichs-Stammverzeichnis erstellt. |
Ein Git-Repository wird im Arbeitsbereich initialisiert, wenn git verfügbar ist. Entwicklungsabhängigkeiten werden installiert, wenn Node und npm verfügbar sind.
Bootstrap-Workflow
Führen Sie die folgenden Schritte der Reihe nach aus. Bestätigen Sie mit dem Benutzer bei jedem Schritt, an dem dies angegeben ist. Gehen Sie niemals von etwas aus.
Schritt 1 – Zielort bestätigen
Fragen Sie den Benutzer: „Ich werde den Dokumentationsarbeitsbereich in <cwd> bootstrapen. Ist das korrekt? (ja / nein / Pfad angeben)“
- Bei
ja: mit cwd als Ziel fortfahren. - Bei
nein: nach dem korrekten Pfad fragen, bestätigen und dann fortfahren. - Wenn der Benutzer „in diesem Ordner“ oder ähnlich gesagt hat: cwd annehmen, aber dennoch bestätigen.
Schritt 2 – Bestätigen, dass das Ziel leer ist (oder Zustimmung einholen)
Listen Sie den Inhalt des Zielverzeichnisses auf (ohne versteckte Dateien wie .git).
Wenn leer: mit Schritt 3 fortfahren.
Wenn nicht leer:
- Dem Benutzer zeigen, was vorhanden ist.
- Erklären: „Dieses Verzeichnis ist nicht leer. Standardmäßig weigert sich dieser Skill, in ein nicht leeres Verzeichnis zu bootstrapen. Ich kann entweder (a) abbrechen, (b) Sie bestätigen, dass ich trotzdem fortfahren soll, und ich lasse vorhandene Dateien unberührt, oder (c) Sie geben ein Unterverzeichnis an, in dem der Arbeitsbereich erstellt werden soll.“
- Auf explizite Bestätigung warten. Wenn der Benutzer keine strikte positive Bestätigung gibt, abbrechen.
- Wenn der Benutzer „los geht's“ oder „ja, fortfahren“ sagt – dies als Zustimmung vermerken und fortfahren.
Wenn AGENTS.md am Zielort bereits existiert: anhalten. Der Arbeitsbereich ist bereits bootstrappt. Den Benutzer informieren und anbieten, die vorhandene AGENTS.md zu lesen.
Wenn git am Zielort bereits initialisiert ist: den späteren Schritt git init überspringen, aber fortfahren.
Schritt 3 – Themenzusammenfassung erfassen
Fragen Sie den Benutzer: „Wofür ist dieser Dokumentationsarbeitsbereich? Beschreiben Sie das Thema in 1–2 kurzen Absätzen. Dies wird die Themenzusammenfassung in AGENTS.md und die Einleitung in README.md.“
Regeln für die Themenzusammenfassung:
- 1 Absatz (bevorzugt), maximal 2 Absätze
- Einfacher Prosatext, keine Formatierung, keine Listen
- Klare Aussage, was der Arbeitsbereich dokumentiert
Wenn der Benutzer einen einzelnen Satz angibt: das ist in Ordnung, verwenden Sie ihn. Wenn der Benutzer eine längere Beschreibung angibt: kürzen Sie sie (mit Bestätigung des Benutzers) oder verwenden Sie maximal 2 Absätze. Wenn der Benutzer „entscheide du“ oder „ich weiß noch nicht“ sagt: fordern Sie mindestens einen Satz an – die Themenzusammenfassung ist der einzige themenspezifische Teil der AGENTS.md, und der Arbeitsbereich braucht eine gewisse Verankerung.
Schritt 4 – Das Bootstrap-Skript ausführen
Sobald Sie Folgendes haben:
- Den Zielpfad
- Die Bestätigung, dass das Verzeichnis geeignet ist
- Die Themenzusammenfassung
...führen Sie das Bootstrap-Skript aus:
node /assets/skill-scripts/bootstrap.js --target --topic ""
Das Skript wird:
- Verfügbarkeit von Node.js prüfen (Node-abhängige Artefakte überspringen und warnen, wenn nicht verfügbar)
- Verfügbarkeit von git prüfen (
git initüberspringen, wenn nicht verfügbar) - Die Verzeichnisstruktur erstellen
- Alle Vorlagen aus
<skill-verz>/assets/templates/instanziieren, mit{{TOPIC_SUMMARY}}und{{CREATED}}ersetzt - Die mit dem Arbeitsbereich gelieferten Skripte (
format.js,validate.js,hash.js,reindex.js) nach<ziel>/scripts/kopieren npm installausführen (wenn Node + npm verfügbar sind)git initausführen (wenn git verfügbar ist)- Eine Zusammenfassung dessen drucken, was erstellt wurde
Wenn das Skript fehlschlägt (z. B. Berechtigungen, fehlendes Werkzeug), auf manuelle Dateierstellung unter Verwendung der Vorlagen in <skill-verz>/assets/templates/ zurückgreifen. Jede Vorlage manuell in das Ziel kopieren, Platzhalter ersetzen und das Skriptverzeichnis durch Kopieren aus <skill-verz>/assets/workspace-scripts/ erstellen.
Schritt 5 – Dem Benutzer mitteilen, was erstellt wurde
Nachdem das Skript abgeschlossen ist, zusammenfassen:
- Welche Dateien und Verzeichnisse erstellt wurden
- Ob
git initausgeführt wurde (oder übersprungen, mit einem Hinweis) - Ob
npm installausgeführt wurde (oder übersprungen, mit einem Hinweis) - Dass
AGENTS.mdnun das leitende Dokument für diesen Arbeitsbereich ist - Dass der Arbeitsbereich einsatzbereit ist
Dann fragen: „Möchten Sie mit der Arbeit an der Dokumentation beginnen, oder möchten Sie zuerst die Struktur überprüfen?“
Vorlagen
Alle Vorlagendateien befinden sich in <skill-verz>/assets/templates/. Das Bootstrap-Skript kopiert und ersetzt sie.
| Vorlage | Erzeugt |
|---|---|
AGENTS.md.template | AGENTS.md |
README.md.template | README.md |
index.yaml.template | index.yaml |
_gitignore_.template | .gitignore (Unterstrich-Umwicklung wird zu Punkt-Präfix) |
package.json.template | package.json |
_prettierrc_.template | .prettierrc |
_markdownlint.json_.template | .markdownlint.json |
Verwendete Platzhalter:
{{TOPIC_SUMMARY}}– wird durch die Themenbeschreibung des Benutzers ersetzt{{CREATED}}– wird durch das heutige Datum (JJJJ-MM-TT) ersetzt
Das Bootstrap-Skript behandelt die Unterstrich-Umwicklung automatisch (eine Datei namens _foo_.template wird im Ergebnis zu .foo).
Mit dem Arbeitsbereich gelieferte Skripte
Nach dem Bootstrap hat der Arbeitsbereich diese Hilfsskripte in scripts/:
| Skript | Zweck |
|---|---|
scripts/format.js | Führt Prettier auf allen .md/.html/.json/.yaml-Dateien aus |
scripts/validate.js | Führt markdownlint auf allen .md-Dateien aus |
scripts/hash.js | Berechnet den SHA-256-Hash einer Datei, schreibt optional in assets/ und aktualisiert das Manifest |
scripts/reindex.js | Generiert den automatischen Indexabschnitt in README.md neu |
Alle sind über npm aufrufbar:
npm run formatnpm run validatenpm run hashnpm run reindex
Referenzen
Für tiefergehende Informationen zu bestimmten Themen siehe das Verzeichnis references/:
references/asset-management.md– Wie Assets hinzugefügt, verlinkt und migriert werden (inhaltsadressierter Speicher, Manifest, pro Dokument vs. gemeinsam)references/document-promotion.md– Wie ein einzelnes Dokument in einen Ordner befördert wird, wenn es Unterdokumente erhält
Diese werden nur bei Bedarf in den Kontext geladen. Die Haupt-AGENTS.md deckt die häufigsten Fälle ab; Referenzen sind für die selteneren Fälle.
Erinnerungen für den Agenten (während des Bootstraps)
- Die Themenzusammenfassung ist der einzige themenspezifische Inhalt, den der Benutzer bereitstellt. Alles andere ist vorlagengeneriert. Fragen Sie nicht nach Dateinamen, Linkstilen, Frontmatter-Feldern, Commit-Nachrichten-Stil oder anderen Regeln – diese sind in den Vorlagen festgelegt.
- Wenn der Benutzer etwas verlangt, was die Vorlagen nicht unterstützen, sprechen Sie es an. Erfinden Sie keine neuen Konventionen stillschweigend. Der richtige Schritt ist, entweder (a) es für eine zukünftige Vorlagenrevision zu notieren oder (b) es als Ausnahme mit expliziter Bestätigung zu implementieren.
- Nach dem Bootstrap ist dieser Skill abgeschlossen. Wenn der Benutzer das nächste Mal etwas im Arbeitsbereich tun möchte, liest der Agent die
AGENTS.mdund befolgt sie. Dieser Skill wird nicht erneut ausgeführt, es sei denn, der Benutzer bittet explizit darum, einen anderen Arbeitsbereich zu bootstrapen oder den vorhandenen neu zu bootstrapen.