Vai al contenuto principale

Usare la skill

Una volta installata, la skill Copera CLI è caricabile da qualsiasi agente che supporta lo standard Agent Skills. Come la invochi dipende dall'agente.

Invocazione per agente​

AgentInvocation
Claude Code/copera:cli (explicit) or any prompt mentioning Copera (auto-trigger).
Cursor/copera-cli (explicit) or describe what you want — the skill is description-matched.
OpenCodeDiscovery is automatic via the skill tool; just ask for a Copera task.
Codex / Windsurf / Cline / Aider / ContinueAmbient — the skill content is loaded as part of the agent's context. Just describe the task.

Quasi mai serve invocare la skill esplicitamente. Descrivi semplicemente cosa vuoi fare in Copera, e l'agente caricherà la reference giusta ed eseguirà.

Convenzioni al primo avvio​

La skill impone alcune regole che rendono prevedibili le esecuzioni degli agenti. Conoscerle ti aiuta a capire perché gli agenti si fermano o chiedono prima di agire.

Discovery prima delle scritture​

Prima di creare o aggiornare qualsiasi cosa in una board che l'agente non ha visto in questa sessione, eseguirà:

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

Questo non è l'agente chiacchierone — i tipi di colonna e le etichette delle opzioni non si possono indovinare. Saltare la lettura dello schema è la causa più comune di scritture di riga rifiutate in silenzio. La skill rende questa regola obbligatoria.

Conferma quando conta​

L'agente usa il giudizio su quando fermarsi e chiedere. Il default non è "conferma ogni scrittura" — quello è teatro della conferma. Invece:

  • Letture — esegui silenziosamente e riassumi.
  • Scritture di routine (rows create, rows update, commenti e messaggi interni, docs update, drive upload su un path nuovo) — quando la tua richiesta è non ambigua, l'agente le esegue e basta e riporta cosa è cambiato. Nessuna riformulazione.
  • L'agente si ferma e chiede quando:
    1. Ha dovuto inferire un valore che non hai specificato (es. severity non data, deve indovinare).
    2. L'operazione esce dal workspace (commenti a visibility external, channel rivolti ai clienti, upload di massa).
    3. Hai detto esplicitamente "chiedimi prima di ogni passo" nella conversazione.
  • Operazioni distruttive (rows delete, docs delete, force-delete, overwrite di massa) — sempre conferma, anche se le hai pre-autorizzate.

Per le workflow skill (vedi Workflow Skills), la postura di conferma è decisa a tempo di build della skill per script — registrata come colonna Confirm nella tabella Scripts della skill. L'agente la rispetta senza richiedere di nuovo. Gli script distruttivi sono bloccati su always-confirm; quelli non distruttivi di default "esegui e basta".

JSON-first​

Quando l'agente deve agire sull'output di Copera, passa sempre --json. L'output CLI formattato per umani è per te, non per il parser dell'agente.

Sessioni di esempio​

Elencare le board​

Tu: Quali board ho in Copera?

Agente: (esegue copera boards list --json) Hai tre board: Engineering (66ab…), CRM (66cd…), Marketing (66ef…). Vuoi che approfondisca qualcuna?

Creare una riga (con discovery)​

Tu: Crea un bug nella table Bugs intitolato "Login button broken on Safari", severity P1.

Agente: (esegue copera tables list --board 66ab… --json) Vedo due table in Engineering: Bugs (66bg…) e Releases (66rl…). Uso Bugs.

(esegue copera tables get 66bg… --board 66ab… --json) Lo schema ha Status, Severity, Title, Description.

(esegue copera rows create --board 66ab… --table 66bg… --data '{…}' --json) Creata riga #142 (66r1…) — title "Login button broken on Safari", severity P1, status Triage.

L'agente non riformula la chiamata prima di eseguirla — la tua richiesta era non ambigua e la create non è distruttiva. Se avessi specificato un valore inferito dall'agente (es. "crea qualche bug per me"), o se fosse un rows delete, l'agente si fermerebbe a confermare.

Catturare un workflow​

Tu: Ogni volta che ti mando un link Sentry, apri una riga di triage in Bugs e pubblica una notifica su #alerts.

Agente: Sembra un workflow che ripeterai. Vuoi che lo salvi come workflow skill riutilizzabile così ogni sessione futura può eseguirlo in modo identico?

(continua con l'intervista build-workflow-skill)

I profili eliminano le ripetizioni​

Se chiederai all'agente di operare ripetutamente sulla stessa board+table, configura un profilo Copera così gli ID sono già risolti:

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

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

Poi l'agente può eseguire copera rows create --data '{…}' senza i flag --board / --table. Vedi Configurazione CLI per lo schema completo dei profili, e Workflow Skills per come l'agente ti aiuta a impostarli automaticamente.

Cosa aspettarsi quando cambia lo schema​

Gli admin del workspace che cambiano una colonna o un'etichetta di opzione possono rompere le workflow skill che avevano hardcoded lo schema. La detection è reattiva, non pre-flight — la skill non recupera lo schema a ogni esecuzione (brucerebbe il budget di rate limit inutilmente). Invece:

  1. L'agente invoca lo script bundlato del workflow. Lo script restituisce un errore copera (es. invalid option ID).
  2. L'agente carica il fingerprint.md del workflow (solo ora, non prima), classifica l'errore come schema-flavored e si ferma.
  3. Ti dice che lo schema di <table> potrebbe essere cambiato e chiede se recuperare lo schema attuale e aggiornare la skill.
  4. Con il tuo OK, fa diff rispetto allo snapshot salvato, riscrive le sezioni interessate, aggiorna la data dello snapshot e riesegue la chiamata fallita.
  5. Con "no", esce in modo pulito — non ritenta mai in silenzio contro uno schema che sospetta obsoleto.

Puoi anche forzare un refresh in qualsiasi momento: "refresh the schema for <workflow-name>". Vedi Workflow Skills → Schema drift per il meccanismo completo.

Limitazioni​

  • La skill insegna l'uso della CLI; non sostituisce il binario CLI. Installa la copera CLI sulla stessa macchina.
  • I comandi Docs richiedono un Personal Access Token (cp_pat_…). Le Integration key (cp_key_…) funzionano per boards e channels, ma restituiscono un errore di auth sugli endpoint docs.
  • I target delle colonne LINK non sono nello schema — l'agente deve chiederti quale table c'è dall'altra parte. Le workflow skill che usano colonne LINK lo catturano dall'intervista.