Skills

Skills sind der primäre Mechanismus, um Domänenwissen für KI-Agenten in CodeCourier zu bündeln und zu verteilen. Jeder Skill ist eine benannte Sammlung von Dateien - Markdown-Dokumente, Codebeispiele, API-Referenzen, Best-Practice-Leitfäden -, die vor dem Start des CLI-Tools in das Verzeichnis .claude/skills/ der Sandbox eingespielt werden. Wenn ein Agent diese Dateien liest, erlangt er Wissen auf Expertenniveau zu einem bestimmten Technologie- oder Praxisbereich.

Skills unterstützen mehrere Dateien, das heißt, ein einzelner Skill kann eine umfassende, mehrteilige Wissensbasis enthalten anstatt einer einzelnen monolithischen Datei. Jeder Skill ist unabhängig versioniert, sodass Sie Domänenwissen aktualisieren können, ohne unverwandte Skills zu berühren.

Was Skills sind

Stellen Sie sich Skills als die Bibliothek vor, die Sie einem KI-Agenten beim Arbeitsbeginn in die Hand drücken. Anstatt zu hoffen, dass die Trainingsdaten des Agenten die richtigen Muster für Ihren spezifischen Stack enthalten, stellen Sie zu Sitzungsbeginn kuratiertes, präzises, aktuelles Referenzmaterial bereit.

Beispiel-Skills und ihre typischen Inhalte:

Skill-Datenmodell

Skills werden über drei verwandte Tabellen in der Datenbank gespeichert:

// Core skill record
skills: {
  skillId: string       // unique identifier
  name: string          // display name (e.g., "frontend-design")
  description: string   // what this skill does and when to use it
  category: string      // grouping (e.g., "frontend", "testing", "backend", "security")
  fileCount: number     // number of files in the active version of this skill
  isEnabled: boolean    // whether this skill is selectable in the UI
}

// Individual files within a skill
skillFiles: {
  skillId: string
  path: string          // file path within the skill directory (e.g., "patterns.md")
  content: string       // full file content (markdown or code)
}

// Version history
skillVersions: {
  skillId: string
  version: number       // incrementing version number
  name: string          // name at time of publish
  description: string   // description at time of publish
  category: string      // category at time of publish
  fileCount: number     // number of files in this version
  status: "active" | "inactive"
  publishedAt: number   // Unix timestamp
  publishedBy: string   // user ID of publisher
}

Eigenen Skill anlegen

Eigene Skills werden über die Skills-Verwaltungsseite angelegt. Navigieren Sie zum Skills-Bereich Ihres Projekts oder rufen Sie die globale Skills-Bibliothek aus den Plattformeinstellungen auf.

# Convex Query Patterns

## Reading Data
Always use `useQuery` for reactive data subscriptions in React components.
Use `ctx.db.query` inside Convex server functions.

### Pagination
Never use `.collect()` on large tables. Use `.paginate()` instead:
```ts
const results = await ctx.db
  .query("posts")
  .order("desc")
  .paginate(opts); // opts.numItems controls page size
```

## Writing Data
All data mutations must go through Convex mutation functions.
Never write directly to the database from client code.

### Scheduling Background Work
Heavy operations go to `ctx.scheduler.runAfter` to avoid timeout:
```ts
await ctx.scheduler.runAfter(0, internal.tasks.processLargeDataset, {
  datasetId: args.datasetId,
});
```

## Validators
Use Convex's built-in validators for all mutation and action arguments.
Do NOT use Zod inside Convex functions.

Best Practices zur Skill-Dateiorganisation

Wie Sie Dateien innerhalb eines Skills organisieren, beeinflusst, wie leicht ein Agent durch das Wissen navigieren kann. Beachten Sie folgende Richtlinien:

• Ein Thema pro Datei - Ein overview.md für übergreifende Konzepte, ein patterns.md für Code-Patterns, ein anti-patterns.md für zu vermeidende Praktiken und ein api-reference.md für konkrete APIs. So bleibt jede Datei überschaubar, ohne den Kontext zu überfrachten.
• Wichtige Regeln zuerst - Agenten lesen Dateien sequenziell. Stellen Sie die kritischsten Einschränkungen an den Anfang jeder Datei und vergraben Sie sie nicht in der Mitte.
• Konkrete Codebeispiele verwenden - Markdown-Erklärungen sind nützlich, aber Code-Snippets, die korrekte und fehlerhafte Nutzung zeigen, sind noch wirksamer.
• Einzelne Dateien unter 500 Zeilen halten - Sehr lange Dateien sind für Agenten schwerer effektiv zu verarbeiten. Teilen Sie große Referenzdokumente auf mehrere fokussierte Dateien auf.
• Dateien sprechend benennen - Verwenden Sie Namen wie quick-reference.md, gotchas.md, examples.md, damit der Agent allein aus dem Dateinamen den Zweck ableiten kann.

Skills versionieren

Skills folgen demselben Versionierungs-Lebenszyklus wie Kontextdokumente. Das Bearbeiten der Skill-Dateien erzeugt einen Entwurf. Das Veröffentlichen erstellt eine neue Version, aktiviert sie und deaktiviert die vorherige Version.

Typische Szenarien, die eine neue Skill-Version auslösen sollten:

• Eine Bibliothek veröffentlicht eine Major-Version mit inkompatiblen API-Änderungen
• Ihr Team übernimmt eine neue Code-Konvention, die Agenten befolgen sollen
• Ein Agent hat einen systematischen Fehler gemacht, der sich durch eine neue Regel im Skill vermeiden lässt
• Sie stellen fest, dass ein bestehendes Pattern im Skill veraltet oder falsch ist

Skills an Personas zuweisen

Um Skills einer Persona zuzuweisen, navigieren Sie zur Detailseite der Persona und öffnen Sie den Skills-Tab. Der Tab zeigt alle im Projekt aktivierten Skills, organisiert in drei Bereiche:

• Skills - Die in diesem Leitfaden beschriebenen Skill-Pakete
• Befehle - Erweiterungen für Slash-Befehle in Claude Code
• Skripte - Ausführbare Shell-/Python-Skripte

Aktivieren Sie die Kontrollkästchen neben jedem Skill, den Sie für diese Persona verfügbar machen möchten. Die Auswahl wird sofort gespeichert und gilt für alle zukünftigen Sitzungen dieser Persona.

Skills an Sitzungstypen zuweisen

Die Standard-Skill-Zuweisungen für jeden Sitzungstyp werden im entsprechenden Setup-Tab innerhalb der Projekteinstellungen konfiguriert. Um beispielsweise die Standard-Skills für alle Issue-Discovery-Sitzungen zu konfigurieren, navigieren Sie zu /p/{id}/issues-setup und wählen Sie auf dieser Seite die gewünschten Skills in den Bereichen Skills, Befehle und Skripte aus.

Diese Sitzungstyp-Standards gelten für jede Sitzung dieses Typs, bei der die ausführende Persona keine eigene explizite Skill-Auswahl hat.

Skills aktivieren und deaktivieren

Skills besitzen ein Flag isEnabled. Deaktivierte Skills erscheinen weder in den Auswahl-Checkboxen auf den Skills-Tabs von Personas noch in den Projekteinstellungen. Das ist nützlich für Skills, die sich in Entwicklung befinden oder die Sie vorübergehend in der Auswahl-UI ausblenden möchten, ohne sie zu löschen.

Das Deaktivieren eines Skills entfernt ihn nicht aus Sandboxes, denen er bereits zugewiesen wurde - bestehende Zuweisungen bleiben erhalten. Die Deaktivierung verhindert lediglich, dass der Skill als wählbare Option für neue Zuweisungen erscheint.

Nächste Schritte