plugin-dev

1. Mission

Dieses Meta-Skill gewährleistet die vollständige technische Governance des KI-Ökosystems: die Konzeption, Erstellung und kontinuierliche Verfeinerung von geteilten Skills (.agents/skills/), den Goldenen Regeln und dauerhaften Richtlinien (.agents/rules/) sowie die kontinuierliche Kapitalisierung von Paketwissen ([PkgName]_IA_CONTEXT.md).

Unverletzliche Grundprinzipien:

• Single Source of Truth (SSOT): Jede Regel, Spezifikation oder Richtlinie muss an genau einem autoritativen Ort liegen. Die Duplizierung von Anweisungen über mehrere Dateien hinweg ist strengstens untersagt.
• DRY (Don't Repeat Yourself): Niemals eine bestehende Anweisung umschreiben oder duplizieren. Jeder Skill oder jedes Dokument muss die bestehende Regel durch einfache Referenz oder Verlinkung nutzen.
• Es wendet systematisch die Referenzmuster von Anthropic an (feature-dev, claude-code-setup, pr-review-toolkit), achtet auf die Widerspruchsfreiheit der Regeln, dokumentiert neue Arbeitsabläufe und hält Rückmeldungen in YAML-Vorfallberichten fest.

2. Auslösung & Grenzen

• Wann aktivieren:
  • Gesprächsende / Sitzungsrückblick: Wird durch /plugin-dev aufgerufen, um einen Anreicherungsplan für die Datei [PkgName]_IA_CONTEXT.md des bearbeiteten Pakets und der eingesetzten Skills vorzuschlagen, in dem Entdeckungen, Fallstricke und erlernte Mechanismen der Sitzung festgehalten werden.
  • Anfrage zur Erstellung eines neuen Skills („Erstelle einen Skill zur Verwaltung automatisierter Tests“, „Füge einen Skill zur Architekturkonzeption hinzu“).
  • Verfeinerung oder Korrektur eines bestehenden Skills aufgrund von Erfahrungsrückmeldungen („Ändere den Skill feature-dev, um X zu verbieten“).
  • Erstellung, Aktualisierung oder Audit einer Verhaltensregel („Füge eine Regel hinzu, die die verwendeten Skills anzeigt“, „Ändere die kritische Regel zu Migrationen in critical-rules.md“).
  • Dokumentation eines neuen Arbeitsablaufs.
  • Konformitätsaudit von Skills, Konsistenz der Richtlinien, Beseitigung von Duplikaten (DRY/SSOT) und SemVer-Kontrolle.
• Wann NICHT aktivieren:
  • Verfassen oder Vereinfachen von Tutorials ➔ tutorial-writer verwenden.
  • Entwicklung von Jekyll-Komponenten oder -Stilen ➔ dev-jekyll verwenden.
  • Synchronisation der gemeinsamen technischen Basis (Core Theme) ➔ sync-theme verwenden.
  • Agenteninitialisierung oder Projektdiagnose ➔ project-setup verwenden.

3. Eingänge & zu ladende Ressourcen

• Priorität 1: .agents/skills/plugin-dev/resources/anthropic-skill-patterns.md (Offizielle gekapselte Anthropic-Muster).
• Priorität 2: Regeldateien:
  • .agents/rules/critical-rules.md (Unveränderliche kritische Regeln).
  • .agents/rules/*.md (Ausführungs- und Stilrichtlinien).
• Priorität 3: .agents/templates/generic-skill.md (Vorlage mit 10 Rubriken) und .agents/templates/workflow-blueprint.md (Ablaufmodell).
• Priorität 4: Register catalog.yaml und CHANGELOG.md des Globalen Hubs.

4. Einschränkungen & Unverletzliche Regeln

• Kardinalprinzipien SSOT (Single Source of Truth) & DRY:
  • Jede Konvention, Richtlinie oder Spezifikation muss an genau einem Ort existieren.
  • Verhaltensregeln befinden sich in .agents/rules/[name].md. Skills dürfen den Text dieser Regeln niemals duplizieren, sondern müssen sie direkt referenzieren.
• Normiertes Format der Paketkontextdateien:
  • Jede Paketkontextdatei muss zwingend modules/[PkgName]/[PkgName]_IA_CONTEXT.md heißen (z.B. PkgRealisationTache_IA_CONTEXT.md).
• Strikter Minimalismus von .agents/references/ (Ein-Skill-Kapselung):
  • Das querschnittliche Verzeichnis .agents/references/ darf nur das absolute Minimum an Dateien enthalten, ausschließlich reserviert für Konventionen und Standards, die von mindestens 2 Skills gemeinsam genutzt werden.
  • Jede methodologische Datei, Anleitung, Katalog oder Vorlage, die von nur einem Skill verwendet wird, MUSS ZWINGEND in <skill>/resources/ verschoben und gekapselt werden (Prinzip der schrittweisen Offenlegung von Anthropic).
• inspiration-Block Pflicht: Jeder erstellte oder geänderte Skill MUSS zwingend die Metadaten inspiration: im YAML-Frontmatter mit seiner Quelle, seinem Referenz-Plugin und seinem Muster enthalten.
• Strikte Einhaltung der 10 Rubriken: Kein Skill darf veröffentlicht werden, wenn eine der 10 normierten Rubriken fehlt.
• Hierarchie und Widerspruchsfreiheit der Regeln:
  • Eine lokale Regel (.agents/rules/) hat Vorrang vor einer allgemeinen Empfehlung, darf aber niemals eine kritische Sicherheitsregel (critical-rules.md) ohne explizite Abwägung verletzen.
  • Jede Regel muss präzise, eindeutig sein und einen expliziten Auslöser enthalten (trigger: always_on oder bedingt).
• Automatisierte Validierung: Jede Skill-Änderung muss durch node scripts/validate-skills.js validiert werden.
• YAML-Vorfallbericht: Jede Korrektur aufgrund eines Agentenfehlers muss einen Bericht in tests/feedbacks/INC-xxx.yaml erzeugen.

5. Schritt-für-Schritt-Verfahren (Workflow für Design & Verfeinerung)

Pfad A: Erstellung eines neuen Skills

1. Schritt 1: Bedarfsanalyse & Anthropic-Muster:
   • resources/anthropic-skill-patterns.md konsultieren, um das nächstgelegene Muster auszuwählen (feature-dev, setup, review, usw.).
2. Schritt 2: Erstellung der SKILL.md:
   • Die Vorlage mit 10 Rubriken ausfüllen.
   • Beschreibung in der 3. Person formulieren, die die Aktivierungs- und Ausschlussfälle klar angibt.
   • YAML-Block inspiration ausfüllen.
   • Eventuelle zum Skill gehörende Begleitressourcen in seinem Unterordner resources/ kapseln.
3. Schritt 3: Deterministische Kontrolle:
   • node scripts/validate-skills.js ausführen.
4. Schritt 4: Eintragung im Katalog:
   • Eintrag in catalog.yaml hinzufügen und in CHANGELOG.md dokumentieren.

Pfad B: Verfeinerung eines bestehenden Skills

1. Schritt 1: Diagnose & YAML-Bericht:
   • tests/feedbacks/INC-[NUM].yaml mit Kontext, beobachtetem Verhalten und angestrebter Korrektur erstellen.
2. Schritt 2: Chirurgische Korrektur:
   • Regel in Rubrik #4 (Einschränkungen) oder einen binären Test in Rubrik #8 (Checkliste) hinzufügen.
3. Schritt 3: SemVer-Erhöhung:
   • Version aktualisieren (z.B. 1.0.1) und in CHANGELOG.md eintragen.

Pfad C: Erstellung oder Änderung einer Regel (Rules)

1. Schritt 1: Qualifikation des Regel-Niveaus:
   • Globale Engineering-/Sicherheitsregel ➔ Hinzufügen in .agents/rules/critical-rules.md oder .agents/rules/general-principles.md.
   • Verhaltensregel für einen Projektagenten ➔ Hinzufügen in .agents/rules/[regel-name].md.
2. Schritt 2: Präzise & unverletzliche Formulierung:
   • Klare Imperative formulieren („Der Agent muss...“, „Striktes Verbot von...“).
   • Ein direktes Beispiel des erwarteten Formats geben.
   • SSOT-Prinzip beachten: Wenn die Regel bereits existiert, niemals duplizieren.
3. Schritt 3: Synchronisation & Benachrichtigung:
   • Die Änderung im Hub oder lokalen Projekt nachvollziehen und die Entwicklung in CHANGELOG.md festhalten.

Pfad D: Kontinuierliche Kapitalisierung am Gesprächsende (/plugin-dev)

1. Schritt 1: Rückblick & Identifikation der Entdeckungen:
   • Das/die in der letzten Sitzung bearbeiteten Pakete identifizieren.
   • Die spezifischen Mechanismen extrahieren, die der Agent untersuchen oder ableiten musste:
     • Beteiligte Tabellen und Modelle, Beziehungen und Geschäftshooks.
     • Besonderheiten des ViewStateService oder der Tabellenfilter.
     • Neu eingeführte Zeitdienste, Jobs oder Observer.
     • Gelöste Fallstricke oder Randfälle (z.B. durch Weglassen von Elternfiltern verfälschte Berechnungen).
2. Schritt 2: Bewertung der Dokumentationslücken:
   • Diese Entdeckungen mit dem bestehenden Inhalt von modules/[PkgName]/[PkgName]_IA_CONTEXT.md vergleichen.
   • Prüfen, ob Skills (feature-dev) oder Regeln von einer zusätzlichen Richtlinie profitieren würden.
3. Schritt 3: Vorschlag eines Anreicherungsplans:
   • Dem Entwickler einen klaren und strukturierten Plan vorlegen, der die vorgeschlagenen Ergänzungen detailliert:
     • Für [PkgName]_IA_CONTEXT.md (neue Dienste, Schlüsselfilter, Abschnitt Fallstricke & Empfehlungen).
     • Für Skills, falls zutreffend.
4. Schritt 4: Ausführung nach Validierung:
   • Nach der Validierung die Datei [PkgName]_IA_CONTEXT.md anreichern, damit jede zukünftige Wartungssitzung sofort über dieses kapitalisierte Wissen verfügt.

6. Umgang mit Unklarheiten & Entscheidungen

• Entscheidung zum Ressourcenort (Skill vs. Agent):
  • Wenn die Ressource ausschließlich von einem bestimmten Skill genutzt wird (z.B. redaktionelle Vorlagen eines Redakteurs, eigener technischer Katalog) ➔ Pflichtort: <skill>/resources/[datei].md (bei Bedarf in Abschnitt 3 des Skills geladen).
  • Wenn die Ressource einen querschnittlichen Engineering-Standard definiert, der von 2 oder mehr Skills geteilt wird ➔ Ort: .agents/references/conventions/ oder .agents/references/architecture/.
• Entscheidung Skill vs. Regel:
  • Wenn die Anweisung eine dauerhafte Einschränkung oder eine querschnittliche Schutzmaßnahme darstellt (z.B. Anzeige der Skills, Antwortstil, Migrationsverbot) ➔ Regel erstellen (.agents/rules/).
  • Wenn die Anweisung einen ausgestatteten Ablauf mit bedarfsgesteuerter Auslösung, Eingaben, Schritt-für-Schritt-Logik und Liefergegenständen beschreibt ➔ Skill erstellen (SKILL.md).
• Wenn die angeforderte Regel exklusiv für Solicode LMS gilt: nicht den Standard des globalen Hubs ändern, sondern in .agents/rules/ und .agents/references/conventions/project-conventions.md eintragen.

7. Ausgabeformat & Liefergegenstände

• Die vollständige Datei SKILL.md oder die Regeldatei (.agents/rules/*.md).
• Die Aktualisierung von catalog.yaml und CHANGELOG.md.
• Das Ergebnis der Ausführung des Skripts validate-skills.js (0 Fehler).

8. Qualitätskontrolle (Binäre Checkliste)

• Enthält das YAML-Frontmatter des Skills den vollständigen inspiration-Block (Quelle, Plugin, Muster)?
• Ist die Beschreibung in der 3. Person und gibt sie an, wann aktiviert und wann nicht aktiviert werden soll?
• Sind alle 10 normierten Rubriken vorhanden und ausgefüllt?
• Wird das SSOT-Prinzip (Single Source of Truth) und die DRY-Regel eingehalten (keine duplizierte Anweisung zwischen Dateien)?
• Ist das Verzeichnis .agents/references/ minimal und frei von Ein-Skill-Ressourcen?
• Sind Ein-Skill-Ressourcen streng in <skill>/resources/ gekapselt?
• Handelt es sich um eine Regel, ist sie präzise, nicht widersprüchlich zu critical-rules und mit einem klaren Beispiel versehen?
• Läuft das Skript node scripts/validate-skills.js erfolgreich?

9. Umgang mit häufigen Fehlern

Typischer Fehler	Ursache	Sofortlösung
Ablegen einer spezifischen Ressource auf Agentenebene	Mangelnde Granularität bei der Kapselung	Die Datei unter <skill>/resources/ verschieben und als interne Ressource referenzieren
Erstellen eines Skills für eine einfache passive Regel	Verwechslung zwischen Regel und ausgestattetem Ablauf	Die Anweisung nach .agents/rules/ verschieben
Vergessen der inspiration-Metadaten	Unachtsamkeit	Systematisch den inspiration-Block im Frontmatter hinzufügen
Lokale Regel im Konflikt mit dem Hub-Standard	Fehlendes vorheriges Audit	.agents/rules/critical-rules.md auditieren, bevor die Regel formalisiert wird

10. Konkrete Beispiele (Few-Shot)

Beispielaufruf A (Skill): „Erstelle den Skill tutorial-writer, inspiriert von content-authoring.“ Verhalten: Der Agent lädt anthropic-skill-patterns.md, extrahiert das Muster für strukturiertes Schreiben, verfasst die 10 Rubriken mit inspiration: { plugin: "content-authoring" }, isoliert die didaktischen Vorlagen in tutorial-writer/resources/ und trägt den Skill in catalog.yaml ein.

Beispielaufruf B (Regel): „Füge eine Regel hinzu, die die Anzeige der verwendeten Skills am Ende jeder Nachricht vorschreibt.“ Verhalten: Der Agent wendet Pfad C von plugin-dev an, erstellt .agents/rules/affichage-skills.md, aktualisiert .agents/rules/critical-rules.md und wendet sofort das erforderliche Format an.