Zum Hauptinhalt springen

Workflow-Skills

Der CLI-Skill bringt einem Agenten bei, welche copera-Befehle es gibt. Ein Workflow-Skill bringt ihm bei, was in Ihrem Workspace zu tun ist — welches Board, welche Tabelle, welche Spalten was bedeuten, welche Schritte zu verketten sind, wie zu bestätigen ist.

Sie schreiben Workflow-Skills nicht von Hand. Sie bitten den Agenten, einen für Sie zu bauen — und er tut es, indem er interviewt, Ihren Workspace probe und eine SKILL.md-Datei ausgibt.

Wann einen Workflow-Skill bauen​

Bauen Sie einen, wenn Sie merken, dass Sie den Agenten bitten, dieselbe Prozedur mehr als einmal auszuführen. Beispiele:

  • „Triage this bug“ — Zeile anlegen, Severity setzen, nach #alerts posten, Runbook-Doc erstellen.
  • „Send the weekly engineering report“ — diese Woche aktualisierte Zeilen abfragen, zusammenfassen, in einen Channel posten.
  • „Onboard this customer“ — CRM-Zeile anlegen, Kontakt verlinken, Kickoff-Doc erzeugen.

Bauen Sie keinen für One-Shot-Tasks. Der Agent fragt, bevor er eine Anfrage in einen Skill verwandelt.

Wie der Agent ihn baut​

Wenn Sie sagen „make this a workflow“, führt der Agent die Prozedur build-workflow-skill aus. Neun Schritte:

Intent bestätigen

Prüft, ob Sie einen wiederverwendbaren Skill wollen, nicht einen One-Shot. Beendet diese Prozedur, wenn Sie es nur jetzt erledigt haben wollen.

Interview

Erfasst Workflow-Name (kebab-case), Trigger-Phrasen, Inputs, Plain-English-Schritte und gewünschtes Output. Spiegelt es zurück, damit Sie korrigieren können.

Workspace proben

Löst genannte Namen („the Bugs table“, „the runbooks doc“) in echte IDs auf, indem copera boards list / tables list / docs tree / drive tree läuft. Fragt nach Klärung, wenn mehrere Matches.

Schema snapshotten

Für jede beteiligte Tabelle: copera tables get <table-id> --board <board-id> --json und speichert das volle Spalten-Array — IDs, Typen und Options-Labels — plus einen deterministischen Fingerprint. Nur für Diagnostik, nicht für Pre-Flight-Checks.

Speicherort + OS-Baseline wählen

Fragt, wo speichern (Standard projektlokal für team-geteilte Workflows; user-global nur für persönliche Automationen) und was die OS-Baseline Ihres Teams ist. Gleiches OS für alle (macOS/Linux/WSL/Git Bash) → bash-Scripts; alles Windows-native → PowerShell; gemischt → Dual-Varianten. Standard ist bash mit Git Bash / WSL unter Windows — hält das Bundle auf einen Flavor pro Verb.

Verb-Scripts + Confirm-Haltung schreiben

Für jeden copera-Write, den der Workflow ausführt, ein kleines scripts/<verb>.sh (oder .ps1) erzeugen, das semantische Flags nimmt (--severity P1, --title "…") und sie intern in Copera-Spalten-/Options-IDs übersetzt. Hardcodierte IDs eliminieren LLM-ID-Halluzination zur Laufzeit. Scripts nutzen nur Shell + die copera-CLI — kein jq, python oder node, weil nicht jedes Teammitglied sie installiert hat.

Jedes Script bekommt außerdem ein Flag Confirm (yes / no / yes (locked) für destruktive Ops), entschieden im Build-Interview. Interne create/update defaulten auf no (einfach ausführen); extern sichtbare und Bulk-Ops defaulten auf yes; Deletes sind auf always-confirm gesperrt. Der Agent hält das per-Script-Flag zur Laufzeit ein, ohne erneut zu fragen — eliminiert die „jedes Script bestätigen“-Steuer.

SKILL.md und fingerprint.md ausgeben

Füllt das workflow-skill-template in zwei Markdown-Dateien. SKILL.md ist schlank (Prozedur + Scripts-Tabelle + ein Absatz „on error“). fingerprint.md hält den Schema-Snapshot und die volle Drift-Handling-Prozedur — nur geladen, wenn etwas schiefgeht.

Dry-Run + iterieren

Führt jedes Script end-to-end gegen Ihren echten Workspace aus. Während dieses Build-Time-Validation-Passes pausiert der Agent vor jedem Write unabhängig vom Confirm-Flag — Ziel ist, Bugs und schlechte Inputs zu fangen, bevor der Skill gelockt wird. Iteriert mit Ihnen. Stoppt, wenn Sie bestätigen, dass der Workflow korrekt läuft. Nach dem Build halten Runtime-Aufrufe das per-Script-Confirm-Flag ein, ohne erneut zu fragen.

Das Output ist ein Verzeichnis-Bundle — SKILL.md, fingerprint.md und ein Ordner scripts/ mit kleinen bash-Scripts. Portabel, regenerierbar, committbar und lesbar von jedem Agenten, der den Agent-Skills-Standard unterstützt.

hinweis

Scripts sind standardmäßig bash — funktioniert out of the box unter macOS / Linux / WSL / Git Bash. Die Default-Konvention ist „unter Windows Git Bash oder WSL installieren“. Der Agent erzeugt PowerShell-Varianten nur, wenn das Team voll Windows-native ist, oder duale .sh + .ps1-Varianten, wenn das Team gemischt ist und explizit opt-in (mehr Maintenance).

hinweis

Generierte Scripts vermeiden bewusst jq, python und node — alles, was nicht Shell + die copera-CLI selbst ist. Eine fehlende Dependency ist ein schlechterer Failure-Mode für ein Teammitglied als eine etwas verbose Payload mit Parameter-Expansion.

Wie ein Workflow-Skill aussieht​

Ein vereinfachtes triage-bug-Bundle:

triage-bug/
├── SKILL.md            # always loaded
├── fingerprint.md      # only loaded on script error or manual refresh
└── scripts/
    ├── triage.sh       # file a triage row
    └── notify.sh       # post to #alerts

SKILL.md (Auszug — schlank, kein Schema-Rauschen):

---
name: triage-bug
description: File a triage row in Engineering > Bugs from a free-text bug report. Trigger on "triage this bug" or pasted Sentry links.
---

# Triage Bug

When the user pastes a bug report, run scripts/triage.sh; if severity is P0 or P1,
also run scripts/notify.sh.

## Scripts
| Script | Purpose | Required flags | Confirm |
|---|---|---|---|
| `scripts/triage.sh` | File a triage row | `--title`, `--severity` (P0|P1|P2|P3) | no |
| `scripts/notify.sh` | Alert #alerts on P0/P1 | `--severity`, `--row-id` | yes |

## Procedure
1. Parse the user's input for severity hints. Confirm with user.
2. `bash scripts/triage.sh --title "<title>" --severity <P0|P1|P2|P3>` — confirm first.
3. If severity is P0 or P1: `bash scripts/notify.sh --severity <S> --row-id <id-from-step-2>`.

## On copera error or schema-refresh request
If a `bash scripts/<verb>.sh` call exits non-zero, load and follow `./fingerprint.md`
before retrying or surfacing the error.

fingerprint.md (Auszug — nur geladen bei Bedarf):

# Schema fingerprint & drift handling — triage-bug

> You only read this file when a script in ./scripts/ failed and you need to
> decide whether the error is schema drift, OR the user explicitly asked to
> refresh the schema. Never on successful runs.

## Metadata
profile: triage
schema_snapshot_date: 2026-05-09
schema_fingerprints:
  66bg…: a4f291c0e7d83b12

## Schema (frozen — diagnostic reference)
### Table: 66bg… — Bugs
- col_title     Title     TEXT
- col_severity  Severity  DROPDOWN  [opt_p0: P0, opt_p1: P1, …]
…

## Step 1 — Classify the error
…schema-flavored vs auth/rate-limit/network…

## Step 2 — Ask the user, then update on confirmation
…fetch tables get, recompute fingerprint, diff, update both files, retry…

scripts/triage.sh (Auszug):

#!/usr/bin/env bash
set -euo pipefail
# Hardcoded IDs — the agent never types these.
BOARD_ID="66ab…"; TABLE_ID="66bg…"
# semantic → option ID
case "$severity" in
  P0) sev_opt="opt_p0" ;;
  P1) sev_opt="opt_p1" ;;
  P2) sev_opt="opt_p2" ;;
  P3) sev_opt="opt_p3" ;;
esac
copera rows create --board "$BOARD_ID" --table "$TABLE_ID" \
  --data "{\"columns\":[…]}" --json

Der Agent ruft bash scripts/triage.sh --severity P1 --title "Login broken" auf — nie copera rows create direkt. Spalten- und Options-IDs stehen überhaupt nicht im Prompt des Agenten.

Das volle Template liegt im skills-Repo.

Schema-Drift — reaktiv, nicht Pre-Flight​

Workspace-Admins, die Spalten oder Options-Labels editieren, können Workflow-Skills still brechen, die das Schema hardcodiert haben. Workflow-Skills handhaben das reaktiv: sie refetchen das Schema nicht bei jedem Aufruf (Ihr PAT hat ein knappes Rate-Limit-Budget; das würde es grundlos verbrennen). Drift-Erkennung läuft nur, wenn ein Script-Aufruf scheitert in einer Weise, die auf Schema-Bewegung hindeutet.

Der Schema-Snapshot und die volle Drift-Handling-Prozedur leben in fingerprint.md, einer Sibling-Datei, die der Agent nur bei Bedarf lädt. Sie aus SKILL.md herauszuhalten hält den Working Context des Agenten auf den 99 % der Läufe klein, bei denen nichts schiefgeht.

  1. Der Agent führt bash scripts/<verb>.sh … aus. Das Script scheitert — Exit-Code non-zero, copera-Fehler-JSON auf stderr.

  2. Der Agent lädt fingerprint.md (erst jetzt, nicht vorher) und folgt der Klassifikation:

    • Schema-flavored — invalid column, unknown columnId, invalid option, unerwartetes 400/422 von einem Write. Weiter zu Schritt 3.
    • Kein Drift — auth_required, rate_limit, Netzwerk/5xx. Melden und stoppen. Schema nicht proben.

  3. Nur bei schema-flavored Fehlern sagt der Agent:

    The script triage.sh failed with <error.message>. This looks like the schema for Bugs may have changed. Want me to fetch the current schema and update this skill?

  4. Bei OK führt der Agent copera tables get <table-id> --board <board-id> --json für die betroffene Tabelle aus, diffed gegen den gespeicherten Snapshot in fingerprint.md, aktualisiert den Abschnitt Schema (frozen) in fingerprint.md UND die relevanten case-Mappings im Script, bumpt schema_snapshot_date und führt den fehlgeschlagenen Aufruf erneut aus.

  5. Bei „nein“ beendet der Agent. Sie retryen nie still gegen ein Schema, das Sie für veraltet halten.

Das Fingerprint-Rezept ist deterministisch: SHA-256 über columnId:type jeder Spalte (plus sortierte Options-IDs bei Choice-Spalten), newline-getrennt gejoint, erste 16 Hex-Zeichen. Es wird pro Tabelle in fingerprint.md gespeichert, damit der Agent etwas zum Diffen hat — nicht damit es bei jedem Aufruf läuft.

Sie können jederzeit einen manuellen Refresh erzwingen: sagen Sie dem Agenten „refresh the schema for <workflow-name>“, und er lädt fingerprint.md und denselben Update-Pfad ohne Error-Trigger.

hinweis

Drift-Erkennung kann nicht erkennen, wenn eine LINK-Spalte auf eine andere verknüpfte Tabelle umgezielzt wurde — das Copera-Schema trägt diese Information nicht. Workflow-Skills erfassen den Namen der verknüpften Tabelle aus dem Original-Interview und dokumentieren das als bekannte Einschränkung.

Workflow-Skills teilen​

Ein Workflow-Skill ist nur ein Verzeichnis von Dateien. Die empfohlene Aufteilung:

  • Der CLI-Skill (die Tier-A-Basis) — global installieren, einmal pro Entwicklermaschine. Siehe Installieren.
  • Workflow-Skills — projektlokal committen, im Repo des Teams, das sie ausführt. Sie referenzieren die spezifischen Board-/Tabellen-/Spalten-IDs Ihres Workspace, sind also projekt- und nicht benutzerförmig.

Für einen Team-Workflow:

  • Team-weit (Standard) — speichern unter .claude/skills/<name>/ (oder dem Equivalent Ihres Agenten) im Projekt-Repo und committen. Der Agent jedes Teammitglieds greift ihn beim Pull.
  • Persönlich — speichern unter ~/.claude/skills/<name>/. Folgt Ihnen über Projekte, nicht geteilt.
  • Öffentlich — Bundle in ein öffentliches GitHub-Repo pushen. Jeder kann via npx skills add owner/repo installieren. Nur für generische, nicht-workspace-spezifische Beispiele.

Profilnamen über Teammitglieder abstimmen​

Die gebündelten Scripts hardcoden einen Default-Copera-Profilnamen (COPERA_PROFILE="${COPERA_PROFILE:-<name>}"). Für einen team-geteilten Workflow braucht jedes Teammitglied einen Eintrag [profiles.<name>] mit demselben Namen in der eigenen ~/.copera.toml — sonst schlägt die CLI das falsche Profil nach und das Script scheitert.

Wenn der Agent einen geteilten Workflow-Skill baut, bittet er Sie, den Profilnamen zu wählen (Standard: kebab-case-Name des Workflows) und schreibt einen Abschnitt Setup in die generierte SKILL.md, damit neue Teammitglieder genau wissen, was hinzuzufügen ist:

# ~/.copera.toml
[profiles.triage-bug]      # name agreed at workflow-generation time
token    = "cp_pat_…"      # each teammate uses their OWN token
board_id = "66ab…"
table_id = "66bg…"

Tokens bleiben pro Teammitglied; nur der Profil-Name und die Board-/Tabellen-IDs werden geteilt.

Teammitglieder, die lieber kein zweites Profil anlegen, können pro Aufruf überschreiben:

COPERA_PROFILE=my-existing-profile bash scripts/triage.sh --severity P1 --title "…"

— die Named-Convention skaliert aber besser. Dokumentieren Sie den erwarteten Profilnamen im Team-Onboarding neben dem Skill selbst.

tipp

Vermeiden Sie, Skills zu committen, die private Channel-IDs, kundenspezifische Zeilen-IDs oder andere workspace-geheime Kennungen hardcoden, wenn Ihr Repo öffentlich ist. Der Agent markiert das in Schritt 7 der Build-Prozedur.

Wann regenerieren​

Normalerweise müssen Sie das nicht. Der Drift-Check handhabt Schema-Änderungen in-place. Von Grund auf regenerieren, wenn:

  • Die Prozedur selbst sich ändert („we now also notify Slack“).
  • Die Trigger-Phrasen sich ändern.
  • Sie den Workflow umbenannt haben.
  • Sie ihn auf ein anderes Board/Tabelle umbiegen wollen.

In all diesen Fällen den Agenten bitten, „rebuild the triage-bug workflow“ und das Interview erneut durchlaufen.

Der CLI-Skill

Die Basis, auf der Workflow-Skills sitzen.

CLI-Referenz

Die Befehle, die der Prozedur-Abschnitt referenziert.