Skill System Foundry

Was macht Skill System Foundry?

Meta-Skill zum Erstellen AI-agnostischer Skill-Systeme mit einer zweischichtigen Architektur (Skills und Rollen), Vorlagen, Validierungswerkzeugen und plattformübergreifenden Autorenrichtlinien basierend auf der Agent Skills Spezifikation.

Projektkontext

Dieses Repository enthält einen Skill (skill-system-foundry/) und seine Testsuite (tests/). Der Skill ist ein Meta-Skill – seine Domäne ist die Erstellung anderer Skills. Es handelt sich nicht um eine Anwendung. Es gibt keinen Server, keine Datenbank, kein Frontend.

Sprache: Python 3.12+ (nur Standardbibliothek – keine Drittanbieterimporte im Produktionscode).

Entwicklungsabhängigkeit: coverage (nur Testabdeckungsmessung; siehe requirements-dev.txt für die genaue Version).

Repository-Struktur:

.
├── AGENTS.md                        ← diese Datei
├── CLAUDE.md                        ← Symlink zu AGENTS.md
├── CONTRIBUTING.md                  ← Richtlinien für Mitwirkende
├── README.md                        ← Repository-Übersicht
├── .coveragerc                      ← Coverage-Konfiguration (70%-Schwellwert, Branch)
├── .python-version                  ← Python-Version (siehe Datei für aktuellen Wert)
├── requirements-dev.txt             ← nur coverage
├── skill-system-foundry/            ← der Meta-Skill selbst
│   ├── SKILL.md                     ← Einstiegspunkt (Router)
│   ├── README.md                    ← Skill-Dokumentation
│   ├── capabilities/                ← eigenständige Fähigkeitsmodule
│   │   ├── skill-design/
│   │   │   └── capability.md        ← Skills, Fähigkeiten, Rollen, Manifeste erstellen
│   │   ├── validation/
│   │   │   └── capability.md        ← Skills validieren, Systeme prüfen
│   │   ├── migration/
│   │   │   └── capability.md        ← Flache Skills zum Router-Muster migrieren
│   │   ├── bundling/
│   │   │   └── capability.md        ← Skills als Zip-Bündel verpacken
│   │   └── deployment/
│   │       ├── capability.md        ← Auf Tools, Wrapper, Symlinks bereitstellen
│   │       └── references/
│   │           └── symlink-setup.md ← Plattformspezifische Symlink-Befehle
│   ├── references/                  ← Bei Bedarf in den Kontext geladene Anleitungen
│   │   ├── authoring-principles.md  ← Plattformübergreifender Schreibkonsens für Skills
│   │   ├── architecture-patterns.md ← Entscheidungen zwischen eigenständigem und Router-Muster
│   │   ├── agentskills-spec.md      ← Leitfaden zur Spezifikationskonformität
│   │   ├── tool-integration.md      ← Toolspezifische Pfade und Bereitstellung
│   │   ├── directory-structure.md   ← Vollständiges Layout und Konventionen
│   │   ├── anti-patterns.md         ← Häufige Fehler
│   │   ├── claude-code-extensions.md
│   │   ├── codex-extensions.md
│   │   └── cursor-extensions.md
│   ├── assets/                      ← Vorlagen für das Gerüst
│   │   ├── skill-standalone.md
│   │   ├── skill-router.md
│   │   ├── capability.md
│   │   ├── role.md
│   │   └── manifest.yaml
│   └── scripts/                     ← Validierungs-, Gerüstbau- und Bündelungswerkzeuge
│       ├── lib/                     ← Gemeinsame Logik (eine Verantwortung pro Modul)
│       │   ├── configuration.yaml   ← Einzige Quelle der Wahrheit für alle Validierungsregeln
│       │   ├── constants.py         ← Lädt YAML, stellt als Python-Konstanten zur Verfügung
│       │   ├── validation.py        ← Gemeinsame Namens-/Feldvalidierung
│       │   ├── references.py        ← Referenzscan und Graphdurchlauf
│       │   ├── bundling.py          ← Kernlogik zum Bündeln
│       │   ├── manifest.py          ← Manifests parsen und validieren
│       │   ├── codex_config.py      ← Codex agents/openai.yaml Validierung
│       │   ├── yaml_parser.py       ← Nur-Standardbibliothek YAML-Teilparser
│       │   ├── frontmatter.py       ← YAML-Frontmatter-Extraktion
│       │   ├── reporting.py         ← Formatierung strukturierter Ausgaben
│       │   └── discovery.py         ← Erkennung von Skill-Verzeichnissen
│       ├── validate_skill.py        ← Einen einzelnen Skill validieren
│       ├── audit_skill_system.py    ← Gesamtes Skill-System prüfen
│       ├── scaffold.py              ← Neue Komponenten aus Vorlagen erstellen
│       └── bundle.py                ← Für die Verteilung bündeln (zip)
├── tests/                           ← Umfassende Testsuite (siehe tests/ für aktuelle Dateien)
│   ├── helpers.py                   ← Gemeinsame Test-Hilfsprogramme
│   └── test_*.py                    ← Eine Testdatei pro Quellmodul
├── .agents/                         ← Interne Entwicklungsskills (nicht verteilt)
│   └── skills/
│       ├── commit-conventions/       ← Commit-Nachrichtenformat und Konventionen
│       ├── critique/                ← Konstruktive Kritik an Plänen und Lösungen
│       ├── git-release/             ← Leitfaden zum Release-Lebenszyklus
│       ├── github-actions/          ← CI/CD-Workflow-Erstellung und -Überprüfung
│       ├── local-code-review/       ← Lokale automatisierte Prüfungen und Diff-Analyse
│       ├── markdown-docs/           ← Durchsetzung der Dokumentationsqualität
│       ├── python-scripts/          ← Python-Code-Qualitätskonventionen
│       ├── review/                  ← Leitfaden zum menschlichen PR-Review-Prozess
│       ├── shell-scripts/           ← Shell-Skript-Sicherheit und -Konsistenz
│       ├── skill-authoring/         ← Konsistenz der Meta-Skill-Struktur
│       ├── solution-design/         ← Lösungsplanung vor der Implementierung
│       ├── validate-skill-spec/     ← Validierung der Skill-Struktur und Spezifikationskonformität
│       └── yaml-config/             ← Governance für configuration.yaml
├── .claude/                         ← Claude Code Konfiguration und Skill-Symlinks
│   └── skills/                      ← Symlinks zu .agents/skills/ für Claude Code
├── .claude-plugin/                  ← Claude Code Plugin-Marktplatzkonfiguration
│   ├── plugin.json
│   └── marketplace.json
└── .github/
    ├── codex/                       ← Codex-Review-Konfiguration
    │   └── review-reference.md      ← Repository-spezifische Review-Anleitung
    ├── scripts/                     ← CI-Hilfsskripte (Bash + Python)
    ├── workflows/                   ← GitHub Actions CI/CD
    │   ├── python-tests.yaml        ← Tests + Abdeckung + Badge-Aktualisierung (Ubuntu + Windows)
    │   ├── shellcheck.yaml          ← Lintet .github/scripts/*.sh
    │   ├── codex-code-review.yaml   ← Codex PR Review via codex-ai-code-review-action
    │   └── release.yml              ← Bündelt zip + lädt Release-Asset hoch
    ├── instructions/                ← Review-Regeln für Copilot/Codex
    │   ├── markdown.instructions.md ← Gilt für **/*.md
    │   └── scripts.instructions.md  ← Gilt für scripts/**/*.py
    ├── copilot-instructions.md      ← Übergeordnete Review-Anleitung
    └── CODEOWNERS                   ← Erfordert Code-Owner-Genehmigung für .github/

Einschränkungen

Diese Einschränkungen sind für die gesamte Codebasis nicht verhandelbar:

• Nur Standardbibliothek — keine pip install-Abhängigkeiten im Produktionscode. Skripte müssen überall ausführbar sein, wo Python 3.12+ verfügbar ist.
• Python 3.12-Kompatibilität — Verwenden Sie keine Funktionen aus 3.13+.
• Validierungsregeln in YAML — Limits, Muster und reservierte Wörter befinden sich in scripts/lib/configuration.yaml. Hartcodieren Sie Validierungsregeln niemals in Python.
• Nur os.path — Verwenden Sie nicht pathlib. Mischen Sie die beiden nicht.
• Typhinweise auf allen Funktionssignaturen — Verwenden Sie integrierte Generika (list, dict, tuple) und X | None.
• encoding="utf-8" bei allen open()-Aufrufen.
• Fehlerstufen aus Konstanten — Verwenden Sie LEVEL_FAIL, LEVEL_WARN, LEVEL_INFO aus lib/constants.py, niemals hartcodierte Zeichenketten.
• Validierungsfunktionen geben (errors, passes)-Tupel zurück — Lösen Sie niemals Ausnahmen für Validierungsfehler aus.
• Shell-Skripte verwenden set -euo pipefail und validieren Umgebungsvariablen oben mit ${VAR:?}.
• Actions auf Commit-SHAs festgelegt — nicht auf Tags.
• Alle Skripteinstiegspunkte unterstützen --json — maschinenlesbare Ausgabe über to_json_output() aus lib/reporting.py.

Entwicklungsworkflow

Tests ausführen

python -m coverage run -m unittest discover -s tests -p "test_*.py" -v
python -m coverage report

Abdeckungsschwellwert: 70% Branch-Abdeckung (konfiguriert in .coveragerc). CI führt Tests sowohl auf ubuntu-latest als auch auf windows-latest mit Python 3.12 aus.

Meta-Skill validieren

cd skill-system-foundry
python scripts/validate_skill.py . --allow-nested-references --verbose
python scripts/audit_skill_system.py .

Das Flag --allow-nested-references wird benötigt, weil dieser Meta-Skill absichtlich verschachtelte Referenzen verwendet. Eine Warnung über ein fehlendes skills/-Verzeichnis von der Prüfung ist in diesem Distributionsrepository zu erwarten.

Shell-Skripte linten

shellcheck .github/scripts/*.sh

Commit-Nachrichtenformat

<Komponente> und <Komponente> aktualisieren
<Neues> zu <Ort> hinzufügen
<Problem> in <Komponente> beheben

Architekturregeln

Das Skill-System hat genau zwei Schichten:

• Skills — kanonisches, AI-agnostisches Wissen. Eigenständig für fokussierte Aufgaben, Router für komplexe Domänen.
• Rollen — Orchestrierungsverträge, die 2+ Skills mit Verantwortung, Autorität, Einschränkungen und Übergaberegeln kombinieren.

Abhängigkeiten fließen streng nach unten: Rollen → Skills → Fähigkeiten. Niemals umgekehrt. Fähigkeiten sind optional und nur gerechtfertigt, wenn 3+ unterschiedliche Operationen sich gegenseitig ausschließende Auslöser haben.

Code-Organisation

• Einstiegspunkte (scripts/*.py) — dünne Wrapper: Argumentparsing, Ausgabeformatierung, sys.exit(). Delegieren Sie alles an scripts/lib/.
• Bibliotheksmodule (scripts/lib/*.py) — Domänenlogik. Kein print() oder sys.exit() außer in dedizierten Ausgabe-Hilfsprogrammen (reporting.py).
• Konstanten (scripts/lib/constants.py) — Strukturelle Konstanten in Python, Validierungsregeln geladen aus configuration.yaml. Alle YAML-Werte werden vom benutzerdefinierten Parser als Zeichenketten zurückgegeben – konvertieren Sie mit int() in constants.py.
• Tests (tests/) — eine Testdatei pro Quellmodul. unittest.TestCase mit beschreibenden Klassennamen, gruppiert nach Feature. Abschnittstrennzeichen (# ===...) für visuelle Klarheit.

Dokumentationsstandards

• Prägnanz zuerst — fügen Sie nur Kontext hinzu, den das Modell noch nicht hat.
• Dritte Person in Skill-Beschreibungen — „Validiert Skills“ nicht „Ich validiere Skills“.
• Ein Begriff pro Konzept — keine Synonymvermischung innerhalb oder zwischen Dateien.
• Progressive Offenlegung — SKILL.md unter 500 Zeilen, Details in references/, Querverweise eine Ebene tief.
• Frontmatter — Gefalteter Blockskalar (>) für mehrzeilige Beschreibungen, Sonderzeichen zitieren.
• Fehlerstufen-Tagging — [spec] für Spezifikationsregeln, [platform: X] für Plattformbeschränkungen, [foundry] für Konventionen.

Review-Anleitung

Detaillierte Review-Regeln befinden sich in .github/instructions/:

Datei	Gilt für	Schwerpunkt
.github/copilot-instructions.md	Alle Dateien	Agent Skills Spezifikationskonformität, Architektur
.github/instructions/markdown.instructions.md	**/*.md	Dokumentationsqualität, Beschreibungsauslöser
.github/instructions/scripts.instructions.md	scripts/**/*.py	Codequalität, nur Standardbibliothek, Typhinweise

Automatisierte Validierung (validate_skill.py, audit_skill_system.py) behandelt viele Frontmatter-, Namens-, Zeilenanzahl- und Strukturprüfungen. Die manuelle Überprüfung stellt weiterhin sicher: Markdown-Datei-Referenzkonventionen (einschließlich Skill-Root-relativer Pfade), Pfadgültigkeit, progressive Offenlegung, Beschreibungsqualität, Architekturbegründung und semantische Konsistenz.

Release-Prozess

Die Version befindet sich im Frontmatter von skill-system-foundry/SKILL.md (metadata.version). Tags spiegeln dies als vX.Y.Z wider. Der Workflow release.yml bündelt automatisch ein Zip und lädt es als Release-Asset hoch. Führen Sie vor dem Taggen eine vollständige Validierung und Tests durch.