Aller au contenu principal

Utiliser le skill

Une fois installé, le skill CLI Copera est chargeable par tout agent qui prend en charge le standard Agent Skills. La façon de l'invoquer dépend de l'agent.

Invocation par agent​

AgentInvocation
Claude Code/copera:cli (explicite) ou tout prompt mentionnant Copera (déclenchement auto).
Cursor/copera-cli (explicite) ou décrivez ce que vous voulez — le skill est apparié par description.
OpenCodeLa découverte est automatique via l'outil skill ; demandez simplement une tâche Copera.
Codex / Windsurf / Cline / Aider / ContinueAmbient — le contenu du skill est chargé dans le contexte de l'agent. Décrivez simplement la tâche.

Vous n'avez presque jamais besoin d'invoquer le skill explicitement. Décrivez simplement ce que vous voulez faire dans Copera, et l'agent chargera la bonne référence et exécutera.

Conventions au premier lancement​

Le skill applique quelques règles qui rendent les exécutions d'agents prévisibles. Les connaître vous aide à comprendre pourquoi les agents font une pause ou demandent avant d'agir.

Découverte avant écritures​

Avant de créer ou mettre à jour quoi que ce soit dans un board que l'agent n'a pas vu dans cette session, il exécutera :

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

Ce n'est pas de l'agent bavard — les types de colonnes et les libellés d'options ne sont pas devinables. Sauter la lecture du schéma est la cause la plus fréquente d'écritures de lignes silencieusement rejetées. Le skill rend cette règle obligatoire.

Confirmation quand c'est important​

L'agent juge quand faire une pause et demander. Le défaut n'est pas « confirmer chaque écriture » — c'est du théâtre de confirmation. À la place :

  • Lectures — s'exécutent silencieusement et résument.
  • Écritures de routine (rows create, rows update, commentaires et messages internes, docs update, drive upload vers un nouveau chemin) — lorsque votre demande est sans ambiguïté, l'agent les exécute simplement et rapporte ce qui a changé. Pas de reformulation.
  • L'agent fait une pause et demande lorsque :
    1. Il a dû inférer une valeur que vous n'avez pas spécifiée (p. ex. sévérité non donnée, doit deviner).
    2. L'opération sort du workspace (commentaires à visibilité externe, channels orientés client, envois massifs).
    3. Vous avez explicitement dit « demande-moi avant chaque étape » dans la conversation.
  • Opérations destructives (rows delete, docs delete, force-delete, écrasement massif) — toujours confirmer, même si vous avez pré-autorisé.

Pour les skills de workflow (voir Skills de workflow), la posture de confirmation est décidée au moment de la construction du skill par script — enregistrée comme une colonne Confirm dans la table Scripts du skill. L'agent l'honore sans redemander. Les scripts destructifs sont verrouillés en confirmation toujours ; les non-destructifs passent par défaut à « juste exécuter ».

JSON d'abord​

Lorsque l'agent doit agir sur la sortie Copera, il passe toujours --json. La sortie CLI formatée pour l'humain est pour vous, pas pour le parseur de l'agent.

Exemples de sessions​

Lister les boards​

Vous : Quels boards ai-je dans Copera ?

Agent : (exécute copera boards list --json) Vous avez trois boards : Engineering (66ab…), CRM (66cd…), Marketing (66ef…). Voulez-vous que j'explore l'un d'eux ?

Créer une ligne (avec découverte)​

Vous : Crée un bug dans la table Bugs intitulé « Login button broken on Safari », sévérité P1.

Agent : (exécute copera tables list --board 66ab… --json) Je vois deux tables dans Engineering : Bugs (66bg…) et Releases (66rl…). J'utilise Bugs.

(exécute copera tables get 66bg… --board 66ab… --json) Le schéma a Status, Severity, Title, Description.

(exécute copera rows create --board 66ab… --table 66bg… --data '{…}' --json) Ligne créée #142 (66r1…) — titre « Login button broken on Safari », sévérité P1, statut Triage.

L'agent ne reformule pas l'appel avant de l'exécuter — votre demande était sans ambiguïté et la création est non destructive. Si vous aviez spécifié une valeur inférée par l'agent (p. ex. « crée un bug pour moi »), ou s'il s'agissait d'un rows delete, l'agent ferait une pause et confirmerait.

Capturer un workflow​

Vous : Chaque fois que je t'envoie un lien Sentry, crée une ligne de triage dans Bugs et poste une notification dans #alerts.

Agent : Cela ressemble à un workflow que vous allez répéter. Voulez-vous que je l'enregistre comme skill de workflow réutilisable afin que toute session future puisse l'exécuter à l'identique ?

(continue avec l'interview build-workflow-skill)

Les profils éliminent la répétition​

Si vous allez demander à l'agent d'opérer sur le même board+table de façon répétée, configurez un profil Copera pour que les IDs soient pré-résolus :

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

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

Ensuite l'agent peut exécuter copera rows create --data '{…}' sans flags --board / --table. Voir Configuration de la CLI pour le schéma complet des profils, et Skills de workflow pour savoir comment l'agent vous aide à configurer cela automatiquement.

À quoi s'attendre lorsque le schéma change​

Les administrateurs de workspace qui modifient une colonne ou un libellé d'option peuvent casser des skills de workflow qui ont figé le schéma en dur. La détection est réactive, pas pré-vol — le skill ne récupère pas le schéma à chaque exécution (cela brûlerait inutilement le budget de limite de débit). À la place :

  1. L'agent invoque un script inclus du workflow. Le script renvoie une erreur copera (p. ex. invalid option ID).
  2. L'agent charge le fingerprint.md du workflow (seulement maintenant, pas avant), classifie l'erreur comme liée au schéma, et fait une pause.
  3. Il vous indique que le schéma de <table> a peut-être changé et demande s'il doit récupérer le schéma actuel et mettre à jour le skill.
  4. Sur votre OK, il compare avec l'instantané enregistré, réécrit les sections affectées, met à jour la date de l'instantané, et relance l'appel en échec.
  5. Sur « non », il quitte proprement — ne réessaie jamais silencieusement contre un schéma qu'il suspecte d'être obsolète.

Vous pouvez aussi forcer un rafraîchissement à tout moment : « refresh the schema for <workflow-name> ». Voir Skills de workflow → Dérive de schéma pour le mécanisme complet.

Limitations​

  • Le skill enseigne l'usage de la CLI ; il ne remplace pas le binaire CLI. Installez la copera CLI sur la même machine.
  • Les commandes docs exigent un Personal Access Token (cp_pat_…). Les clés d'intégration (cp_key_…) fonctionnent pour boards et channels, mais renvoient une erreur d'auth sur les endpoints docs.
  • Les cibles de colonnes LINK ne sont pas dans le schéma — l'agent doit vous demander quelle table est à l'autre bout. Les skills de workflow qui utilisent des colonnes LINK capturent cela lors de l'interview.