Vai al contenuto principale

Workflow Skills

La skill CLI insegna a un agente quali comandi copera esistono. Una workflow skill gli insegna cosa fare nel tuo workspace — quale board, quale table, cosa significano le colonne, quali passi concatenare, come confermare.

Non scrivi le workflow skill a mano. Chiedi all'agente di costruirne una per te, e lo fa — intervistando, sondando il workspace ed emettendo un file SKILL.md.

Quando costruire una workflow skill​

Costruiscine una quando ti accorgi di chiedere all'agente di fare la stessa procedura più di una volta. Esempi:

  • "Fai triage di questo bug" — archivia una riga, imposta severity, pubblica su #alerts, crea un runbook doc.
  • "Invia il report engineering settimanale" — interroga le righe aggiornate questa settimana, riassumi, pubblica su un channel.
  • "Fai onboarding di questo cliente" — crea una riga nel CRM, collega a un contatto, genera un kickoff doc.

Non costruirne una per task one-shot. L'agente chiederà prima di trasformare una richiesta in skill.

Come l'agente la costruisce​

Quando dici "fanne un workflow", l'agente esegue la procedura build-workflow-skill. Nove passi:

Conferma l'intento

Verifica che vuoi una skill riutilizzabile, non un one-shot. Esce da questa procedura se vuoi solo che sia fatto adesso.

Intervista

Cattura il nome del workflow (kebab-case), le frasi trigger, gli input, i passi in linguaggio naturale e l'output desiderato. Te lo ripete così puoi correggere.

Sonda il workspace

Risolve i nomi che hai menzionato ("la table Bugs", "il doc runbooks") a ID reali eseguendo copera boards list / tables list / docs tree / drive tree. Chiede chiarimenti se più cose corrispondono.

Snapshot dello schema

Per ogni table coinvolta, esegue copera tables get <table-id> --board <board-id> --json e salva l'intero array colonne — ID, tipi e etichette opzioni — più un fingerprint deterministico. Usato solo per diagnostica, non per check pre-flight.

Scegli dove salvare la skill + la baseline OS

Chiede dove salvare (default project-local per workflow condivisi dal team; user-global solo per automazioni personali) e qual è la baseline OS del team. Stesso OS per tutti (macOS/Linux/WSL/Git Bash) → script bash; tutti Windows-native → PowerShell; misto → opt-in a dual variant. Il default è bash con Git Bash / WSL su Windows — tiene il bundle a un solo flavor per verbo.

Scrive gli script verbo + postura di conferma

Per ogni scrittura copera che il workflow esegue, genera un piccolo scripts/<verb>.sh (o .ps1) che prende flag semantici (--severity P1, --title "…") e li traduce internamente in column / option ID di Copera. Gli ID hardcoded eliminano l'allucinazione di ID da parte dell'LLM a runtime. Gli script usano solo la shell + la copera CLI — niente jq, python o node, perché non ogni teammate li avrà installati.

Ogni script ottiene anche un flag Confirm (yes / no / yes (locked) per ops distruttive) deciso durante l'intervista di build. Create/update interni di default no (esegui e basta); ops a visibility external e bulk di default yes; le delete sono bloccate su always-confirm. L'agente rispetta il flag per-script a runtime senza richiedere di nuovo — elimina la tassa "approva ogni chiamata di script".

Emette SKILL.md e fingerprint.md

Compila il workflow-skill-template in due file markdown. SKILL.md è snello (procedura + tabella scripts + un paragrafo "on error"). fingerprint.md contiene lo snapshot di schema e la procedura completa di gestione drift — caricato solo quando qualcosa va storto.

Dry-run + itera

Esegue ogni script end-to-end sul workspace reale. Durante questo passaggio di validazione a tempo di build, l'agente si ferma prima di ogni scrittura indipendentemente dal flag Confirm — l'obiettivo è catturare bug e input sbagliati prima di chiudere la skill. Itera con te. Si ferma quando confermi che il workflow si comporta correttamente. Dopo la build, le invocazioni a runtime rispettano il flag Confirm per-script senza richiedere di nuovo.

L'output è un bundle directory — SKILL.md, fingerprint.md e una cartella scripts/ di piccoli script bash. Portabile, rigenerabile, committabile e leggibile da ogni agente che supporta lo standard Agent Skills.

nota

Gli script sono bash di default — funzionano out of the box su macOS / Linux / WSL / Git Bash. La convenzione di default è "se sei su Windows, installa Git Bash o WSL". L'agente genera variant PowerShell solo quando il team è pienamente Windows-native, o dual .sh + .ps1 quando il team è misto e opt-in esplicitamente (più manutenzione).

nota

Gli script generati evitano deliberatamente jq, python e node — qualsiasi cosa che non sia shell + la copera CLI stessa. Una dipendenza mancante è un failure mode peggiore per un teammate di un payload leggermente verboso costruito con parameter expansion.

Come appare una workflow skill​

Un bundle semplificato triage-bug:

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 (estratto — snello, senza rumore di schema):

---
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 (estratto — caricato solo quando serve):

# 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 (estratto):

#!/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

L'agente chiama bash scripts/triage.sh --severity P1 --title "Login broken" — mai copera rows create direttamente. Column ID e option ID non sono affatto nel prompt dell'agente.

Il template completo è nel repo skills.

Schema drift — reattivo, non pre-flight​

Gli admin del workspace che modificano colonne o etichette di opzione possono rompere in silenzio le workflow skill che avevano hardcoded lo schema. Le workflow skill gestiscono questo in modo reattivo: non rifetchano lo schema a ogni invocazione (il tuo PAT ha un budget di rate limit basso; lo bruceresti senza motivo). La detection del drift gira solo quando una chiamata di script fallisce in un modo che suggerisce che lo schema si è mosso.

Lo snapshot di schema e la procedura completa di gestione drift vivono in fingerprint.md, un file sibling che l'agente carica solo quando serve. Tenerlo fuori da SKILL.md significa che il contesto di lavoro dell'agente resta piccolo sul 99% delle esecuzioni in cui non è andato storto niente.

  1. L'agente esegue bash scripts/<verb>.sh …. Lo script fallisce — exit code non zero, JSON di errore copera su stderr.

  2. L'agente carica fingerprint.md (solo ora, non prima) e segue la classificazione:

    • Schema-flavored — invalid column, unknown columnId, invalid option, 400/422 inattesi da una scrittura. Continua al passo 3.
    • Non drift — auth_required, rate_limit, network/5xx. Propaga l'errore e ferma. Non sonda lo schema.

  3. Solo per errori schema-flavored, l'agente dice:

    Lo script triage.sh è fallito con <error.message>. Sembra che lo schema di Bugs possa essere cambiato. Vuoi che recuperi lo schema attuale e aggiorni questa skill?

  4. Con il tuo OK, l'agente esegue copera tables get <table-id> --board <board-id> --json per la table interessata, fa diff rispetto allo snapshot salvato in fingerprint.md, aggiorna la sezione Schema (frozen) in fingerprint.md E le mappature case rilevanti dentro lo script, aggiorna schema_snapshot_date e riesegue la chiamata fallita.

  5. Con "no", l'agente esce. Non ritenti mai in silenzio contro uno schema che sospetti obsoleto.

La ricetta del fingerprint è deterministica: SHA-256 su columnId:type di ogni colonna (più option ID ordinati per le colonne choice), uniti newline-separated, primi 16 caratteri hex. È salvata per-table in fingerprint.md così l'agente ha qualcosa su cui fare diff — non perché giri a ogni chiamata.

Puoi anche forzare un refresh manuale in qualsiasi momento: di' all'agente "refresh the schema for <workflow-name>" e carica fingerprint.md ed esegue lo stesso percorso di update senza un trigger di errore.

nota

La detection del drift non può dire quando una colonna LINK è stata retargetata a una table collegata diversa — lo schema Copera non porta quell'informazione. Le workflow skill catturano il nome della table collegata dall'intervista originale e lo documentano come limitazione nota.

Condividere le workflow skill​

Una workflow skill è solo una directory di file. La suddivisione consigliata:

  • La skill CLI (le fondamenta Tier A) — installa globalmente, una volta per macchina sviluppatore. Vedi Installazione.
  • Workflow skill — commitale project-local, dentro il repo del team che le eseguirà. Referenziano board / table / column ID specifici del workspace, quindi sono project-shaped, non user-shaped.

Per un workflow di team:

  • Team-wide (default) — salva in .claude/skills/<name>/ (o l'equivalente del tuo agente) dentro il repo del progetto e committa. L'agente di ogni teammate la prende non appena fa pull.
  • Personale — salva in ~/.claude/skills/<name>/. Ti segue tra i progetti, non condivisa.
  • Pubblica — pusha il bundle su un repo GitHub pubblico. Chiunque può installare via npx skills add owner/repo. Usalo solo per esempi generici non specifici del workspace.

Allinea i nomi dei profili tra i teammate​

Gli script bundlati hardcodano un nome di profilo Copera di default (COPERA_PROFILE="${COPERA_PROFILE:-<name>}"). Per un workflow condiviso dal team, ogni teammate ha bisogno di una entry [profiles.<name>] con lo stesso nome nel proprio ~/.copera.toml — altrimenti la CLI cercherà il profilo sbagliato e lo script fallirà.

Quando l'agente costruisce una workflow skill condivisa, ti chiede di scegliere il nome del profilo (default al nome kebab-case del workflow) e scrive una sezione Setup nel SKILL.md generato così i nuovi teammate sanno esattamente cosa aggiungere:

# ~/.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…"

I token restano per-teammate; solo il nome del profilo e gli ID board/table sono condivisi.

I teammate che preferiscono non aggiungere un secondo profilo possono fare override per invocazione:

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

— ma la convenzione con nome scala meglio. Documenta il nome di profilo atteso nell'onboarding del team insieme alla skill stessa.

suggerimento

Evita di committare skill che hardcodano channel ID privati, row ID specifici di clienti o altri identificatori secret del workspace se il repo è pubblico. L'agente lo segnala durante il passo 7 della procedura di build.

Quando rigenerare​

Di solito non serve. Il drift-check gestisce i cambi di schema in-place. Rigenera da zero quando:

  • La procedura stessa cambia ("ora notifichiamo anche Slack").
  • Cambiano le frasi trigger.
  • Hai rinominato il workflow.
  • Vuoi puntarlo a una board/table del tutto diversa.

In tutti quei casi, chiedi all'agente di "rebuild the triage-bug workflow" e rifai l'intervista.

La skill CLI

Le fondamenta su cui si appoggiano le workflow skill.

Riferimento CLI

I comandi a cui farà riferimento la sezione procedura.