Zum Hauptinhalt springen

Skill nutzen

Einmal installiert, ist der Copera-CLI-Skill von jedem Agenten ladbar, der den Agent-Skills-Standard unterstützt. Wie Sie ihn aufrufen, hängt vom Agenten ab.

Aufruf pro Agent​

AgentAufruf
Claude Code/copera:cli (explizit) oder jeder Prompt, der Copera erwähnt (Auto-Trigger).
Cursor/copera-cli (explizit) oder beschreiben, was Sie wollen — der Skill wird description-matched.
OpenCodeDiscovery läuft automatisch über das Tool skill; einfach eine Copera-Aufgabe stellen.
Codex / Windsurf / Cline / Aider / ContinueAmbient — der Skill-Inhalt wird als Teil des Agenten-Kontexts geladen. Aufgabe beschreiben.

Sie müssen den Skill fast nie explizit aufrufen. Beschreiben Sie einfach, was in Copera erledigt werden soll, und der Agent lädt die passende Referenz und führt aus.

First-Run-Konventionen​

Der Skill erzwingt einige Regeln, die Agent-Läufe vorhersehbar machen. Sie zu kennen hilft zu verstehen, warum Agenten pausieren oder vor dem Handeln fragen.

Discovery before writes​

Bevor etwas in einem Board angelegt oder aktualisiert wird, das der Agent in dieser Session noch nicht gesehen hat, führt er aus:

copera boards list --json
copera tables list --board <board-id> --json
copera tables get <table-id> --board <board-id> --json

Das ist nicht der Agent, der schwatzhaft ist — Spaltentypen und Options-Labels sind nicht erratbar. Das Schema-Lesen zu überspringen ist die häufigste Ursache still abgelehnter Zeilen-Writes. Der Skill macht diese Regel verpflichtend.

Bestätigung, wenn es zählt​

Der Agent urteilt, wann er pausieren und fragen soll. Der Default ist nicht „jeden Write bestätigen“ — das wäre Confirmation-Theater. Stattdessen:

  • Reads — still ausführen und zusammenfassen.
  • Routine-Writes (rows create, rows update, interne Kommentare und Nachrichten, docs update, drive upload auf einen frischen Pfad) — wenn Ihre Anfrage eindeutig ist, führt der Agent sie einfach aus und meldet, was sich geändert hat. Keine Wiederholung.
  • Der Agent pausiert und fragt, wenn:
    1. Er einen Wert inferieren musste, den Sie nicht angegeben haben (z. B. Severity fehlt, muss raten).
    2. Die Operation den Workspace verlässt (extern sichtbare Kommentare, kundenorientierte Channels, Massen-Uploads).
    3. Sie in der Unterhaltung explizit gesagt haben „frag mich vor jedem Schritt“.
  • Destruktive Operationen (rows delete, docs delete, Force-Delete, Massen-Overwrite) — immer bestätigen, auch wenn Sie vorautorisiert haben.

Bei Workflow-Skills (siehe Workflow-Skills) wird die Confirm-Haltung zur Skill-Build-Zeit pro Script entschieden — als Spalte Confirm in der Scripts-Tabelle des Skills. Der Agent hält sich daran, ohne erneut zu fragen. Destruktive Scripts sind auf always-confirm gesperrt; nicht-destruktive defaulten auf „einfach ausführen“.

JSON-first​

Wenn der Agent auf Copera-Output handeln muss, übergibt er immer --json. Human-formatierte CLI-Ausgabe ist für Sie, nicht für den Parser des Agenten.

Beispiel-Sessions​

Boards listen​

Sie: Welche Boards habe ich in Copera?

Agent: (führt copera boards list --json aus) Sie haben drei Boards: Engineering (66ab…), CRM (66cd…), Marketing (66ef…). Soll ich in eines eintauchen?

Zeile anlegen (mit Discovery)​

Sie: Lege einen Bug in der Bugs-Tabelle an mit Titel „Login button broken on Safari“, Severity P1.

Agent: (führt copera tables list --board 66ab… --json aus) Ich sehe zwei Tabellen in Engineering: Bugs (66bg…) und Releases (66rl…). Ich nutze Bugs.

(führt copera tables get 66bg… --board 66ab… --json aus) Schema hat Status, Severity, Title, Description.

(führt copera rows create --board 66ab… --table 66bg… --data '{…}' --json aus) Zeile #142 (66r1…) angelegt — Titel „Login button broken on Safari“, Severity P1, Status Triage.

Der Agent wiederholt den Aufruf nicht vor dem Ausführen — Ihre Anfrage war eindeutig und das Anlegen ist nicht destruktiv. Hätten Sie einen vom Agenten inferierten Wert spezifiziert (z. B. „leg irgendeinen Bug für mich an“), oder wäre es ein rows delete, würde der Agent pausieren und bestätigen.

Workflow erfassen​

Sie: Jedes Mal, wenn ich dir einen Sentry-Link schicke, lege eine Triage-Zeile in Bugs an und poste eine Benachrichtigung nach #alerts.

Agent: Das klingt nach einem Workflow, den du wiederholen wirst. Soll ich ihn als wiederverwendbaren Workflow-Skill speichern, damit jede künftige Session ihn identisch ausführen kann?

(setzt mit dem build-workflow-skill-Interview fort)

Profile sparen Wiederholung​

Wenn der Agent wiederholt auf dasselbe Board+Tabelle wirken soll, konfigurieren Sie ein Copera-Profil, damit die IDs vorab aufgelöst sind:

# ~/.copera.toml
default_profile = "bugs"

[profiles.bugs]
token    = "cp_pat_…"
board_id = "66ab…"
table_id = "66bg…"

Dann kann der Agent copera rows create --data '{…}' ohne Flags --board / --table ausführen. Siehe CLI-Konfiguration für das volle Profil-Schema und Workflow-Skills dafür, wie der Agent Ihnen hilft, das automatisch einzurichten.

Was zu erwarten ist, wenn sich das Schema ändert​

Workspace-Admins, die eine Spalte oder ein Options-Label ändern, können Workflow-Skills brechen, die das Schema hardcodiert haben. Die Erkennung ist reaktiv, nicht Pre-Flight — der Skill holt das Schema nicht bei jedem Lauf (das würde unnötig Rate-Limit-Budget verbrauchen). Stattdessen:

  1. Der Agent ruft ein gebündeltes Script des Workflows auf. Das Script liefert einen copera-Fehler (z. B. invalid option ID).
  2. Der Agent lädt die fingerprint.md des Workflows (erst jetzt, nicht vorher), klassifiziert den Fehler als schema-bezogen und pausiert.
  3. Er meldet, dass das Schema für <table> sich geändert haben könnte, und fragt, ob das aktuelle Schema geholt und der Skill aktualisiert werden soll.
  4. Bei OK diffed er gegen den gespeicherten Snapshot, schreibt betroffene Abschnitte um, bumpt das Snapshot-Datum und führt den fehlgeschlagenen Aufruf erneut aus.
  5. Bei „nein“ beendet er sauber — nie still gegen ein Schema retryen, das er für veraltet hält.

Sie können jederzeit einen Refresh erzwingen: „refresh the schema for <workflow-name>“. Siehe Workflow-Skills → Schema-Drift für den vollen Mechanismus.

Einschränkungen​

  • Der Skill lehrt CLI-Nutzung; er ersetzt nicht die CLI-Binary. Installieren Sie die copera-CLI auf derselben Maschine.
  • Docs-Befehle erfordern ein Personal Access Token (cp_pat_…). Integration Keys (cp_key_…) funktionieren für Boards und Channels, liefern aber Auth-Fehler auf Docs-Endpunkten.
  • LINK-Spalten-Ziele stehen nicht im Schema — der Agent muss Sie fragen, welche Tabelle am anderen Ende liegt. Workflow-Skills mit LINK-Spalten erfassen das aus dem Interview.