Aller au contenu principal

Skills de workflow

Le skill CLI enseigne à un agent quelles commandes copera existent. Un skill de workflow lui enseigne quoi faire dans votre workspace — quel board, quelle table, ce que signifient les colonnes, quelles étapes enchaîner, comment confirmer.

Vous n'écrivez pas les skills de workflow à la main. Vous demandez à l'agent d'en construire un pour vous, et il le fait — en interviewant, en explorant votre workspace, et en émettant un fichier SKILL.md.

Quand construire un skill de workflow​

Construisez-en un lorsque vous vous surprenez à demander à l'agent de faire la même procédure plus d'une fois. Exemples :

  • « Trier ce bug » — créer une ligne, définir la sévérité, poster dans #alerts, créer un doc de runbook.
  • « Envoyer le rapport d'ingénierie hebdomadaire » — interroger les lignes mises à jour cette semaine, résumer, poster dans un channel.
  • « Onboarder ce client » — créer une ligne dans le CRM, lier un contact, générer un doc de kickoff.

N'en construisez pas pour des tâches ponctuelles. L'agent demandera avant de transformer une requête en skill.

Comment l'agent le construit​

Lorsque vous dites « fais-en un workflow », l'agent exécute la procédure build-workflow-skill. Neuf étapes :

Confirmer l'intention

Vérifie que vous voulez un skill réutilisable, pas une action ponctuelle. Quitte cette procédure si vous voulez juste que ce soit fait maintenant.

Interview

Capture le nom du workflow (kebab-case), les phrases de déclenchement, les entrées, les étapes en langage clair, et la sortie souhaitée. Le reformule pour que vous puissiez corriger.

Explorer votre workspace

Résout les noms que vous avez mentionnés (« la table Bugs », « le doc runbooks ») en vrais IDs en exécutant copera boards list / tables list / docs tree / drive tree. Demande des précisions si plusieurs éléments correspondent.

Instantané du schéma

Pour chaque table impliquée, exécute copera tables get <table-id> --board <board-id> --json et enregistre le tableau complet des colonnes — IDs, types et libellés d'options — plus une empreinte déterministe. Utilisé uniquement pour le diagnostic, pas pour des contrôles pré-vol.

Choisir où enregistrer le skill + la baseline OS

Demande où enregistrer (par défaut local au projet pour les workflows partagés en équipe ; global utilisateur uniquement pour les automatisations personnelles) et quelle est la baseline OS de votre équipe. Même OS pour tout le monde (macOS/Linux/WSL/Git Bash) → scripts bash ; tout Windows natif → PowerShell ; mixte → opte pour des variantes duales. Le défaut est bash avec Git Bash / WSL sous Windows — garde le bundle à une saveur par verbe.

Écrire les scripts de verbes + la posture de confirmation

Pour chaque écriture copera que le workflow effectue, génère un petit scripts/<verb>.sh (ou .ps1) qui prend des flags sémantiques (--severity P1, --title "…") et les traduit en IDs de colonnes / options Copera en interne. Des IDs en dur éliminent l'hallucination d'ID du LLM à l'exécution. Les scripts n'utilisent que le shell + la copera CLI — pas de jq, python ni node, car tous les coéquipiers ne les auront pas installés.

Chaque script reçoit aussi un flag Confirm (yes / no / yes (locked) pour les ops destructives) décidé pendant l'interview de construction. Les create/update internes passent par défaut à no (juste exécuter) ; les ops à visibilité externe et en masse passent à yes ; les suppressions sont verrouillées en confirmation toujours. L'agent honore le flag par script à l'exécution sans redemander — élimine la taxe « approuver chaque appel de script ».

Émettre SKILL.md et fingerprint.md

Remplit le workflow-skill-template en deux fichiers markdown. SKILL.md est mince (procédure + table de scripts + un paragraphe « on error »). fingerprint.md contient l'instantané de schéma et la procédure complète de gestion de dérive — chargé uniquement en cas de problème.

Dry-run + itérer

Exécute chaque script de bout en bout contre votre workspace réel. Pendant cette passe de validation au moment de la construction, l'agent fait une pause avant chaque écriture indépendamment du flag Confirm — l'objectif est de capturer bugs et mauvaises entrées avant de figer le skill. Itère avec vous. S'arrête lorsque vous confirmez que le workflow se comporte correctement. Après la construction, les invocations runtime honorent le flag Confirm par script sans redemander.

La sortie est un bundle de répertoire — SKILL.md, fingerprint.md, et un dossier scripts/ de petits scripts bash. Portable, régénérable, versionnable, et lisible par tout agent qui prend en charge le standard Agent Skills.

note

Les scripts sont en bash par défaut — fonctionnent dès le départ sur macOS / Linux / WSL / Git Bash. La convention par défaut est « si vous êtes sous Windows, installez Git Bash ou WSL ». L'agent ne générera des variantes PowerShell que lorsque l'équipe est entièrement Windows native, ou des variantes duales .sh + .ps1 lorsque l'équipe est mixte et opte explicitement (plus de maintenance).

note

Les scripts générés évitent délibérément jq, python et node — tout ce qui n'est pas le shell + la copera CLI elle-même. Une dépendance manquante est un mode d'échec pire pour un coéquipier qu'une charge utile un peu verbeuse construite avec l'expansion de paramètres.

À quoi ressemble un skill de workflow​

Un bundle simplifié 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 (extrait — mince, pas de bruit de schéma) :

---
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 (extrait — chargé uniquement lorsque nécessaire) :

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

#!/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'agent appelle bash scripts/triage.sh --severity P1 --title "Login broken" — jamais copera rows create directement. Les IDs de colonnes et d'options ne sont pas du tout dans le prompt de l'agent.

Le modèle complet est dans le dépôt skills.

Dérive de schéma — réactive, pas pré-vol​

Les administrateurs de workspace qui éditent des colonnes ou des libellés d'options peuvent casser silencieusement des skills de workflow qui ont figé le schéma en dur. Les skills de workflow gèrent cela de façon réactive : ils ne re-récupèrent pas le schéma à chaque invocation (votre PAT a un budget de limite de débit bas ; cela le brûlerait pour rien). La détection de dérive ne s'exécute que lorsqu'un appel de script échoue d'une façon qui suggère que le schéma a bougé.

L'instantané de schéma et la procédure complète de gestion de dérive vivent dans fingerprint.md, un fichier frère que l'agent ne charge que lorsque nécessaire. Le garder hors de SKILL.md signifie que le contexte de travail de l'agent reste petit sur les 99 % d'exécutions où rien n'a mal tourné.

  1. L'agent exécute bash scripts/<verb>.sh …. Le script échoue — code de sortie non nul, JSON d'erreur copera sur stderr.

  2. L'agent charge fingerprint.md (seulement maintenant, pas avant) et suit sa classification :

    • Lié au schéma — invalid column, unknown columnId, invalid option, 400/422 inattendu d'une écriture. Continuer à l'étape 3.
    • Pas de dérive — auth_required, rate_limit, réseau/5xx. Remonter et s'arrêter. Ne pas explorer le schéma.

  3. Pour les erreurs liées au schéma uniquement, l'agent dit :

    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. Sur votre OK, l'agent exécute copera tables get <table-id> --board <board-id> --json pour la table affectée, compare avec l'instantané enregistré dans fingerprint.md, met à jour la section Schema (frozen) dans fingerprint.md ET les mappings case pertinents dans le script, met à jour schema_snapshot_date, et relance l'appel en échec.

  5. Sur « non », l'agent quitte. Vous ne réessayez jamais silencieusement contre un schéma que vous suspectez d'être obsolète.

La recette d'empreinte est déterministe : SHA-256 sur le columnId:type de chaque colonne (plus les IDs d'options triés pour les colonnes de choix), joints séparés par des sauts de ligne, 16 premiers caractères hex. Elle est enregistrée par table dans fingerprint.md pour que l'agent ait quelque chose à comparer — pas pour s'exécuter à chaque appel.

Vous pouvez aussi forcer un rafraîchissement manuel à tout moment : dites à l'agent « refresh the schema for <workflow-name> » et il charge fingerprint.md et suit le même chemin de mise à jour sans déclencheur d'erreur.

note

La détection de dérive ne peut pas savoir lorsqu'une colonne LINK a été redirigée vers une table liée différente — le schéma Copera ne porte pas cette information. Les skills de workflow capturent le nom de la table liée depuis l'interview d'origine et le documentent comme limitation connue.

Partager des skills de workflow​

Un skill de workflow n'est qu'un répertoire de fichiers. La répartition recommandée :

  • Le skill CLI (le fondement de niveau A) — installer globalement, une fois par machine de développeur. Voir Installation.
  • Skills de workflow — les versionner locaux au projet, dans le dépôt dont l'équipe les exécutera. Ils référencent les IDs spécifiques de board / table / colonne de votre workspace, donc ils sont en forme de projet, pas d'utilisateur.

Pour un workflow d'équipe :

  • À l'échelle de l'équipe (défaut) — enregistrer dans .claude/skills/<name>/ (ou l'équivalent de votre agent) dans le dépôt du projet et versionner. L'agent de chaque coéquipier le récupère dès qu'il tire.
  • Personnel — enregistrer dans ~/.claude/skills/<name>/. Vous suit d'un projet à l'autre, non partagé.
  • Public — pousser le bundle vers un dépôt GitHub public. N'importe qui peut installer via npx skills add owner/repo. Utilisez ceci uniquement pour des exemples génériques, non spécifiques au workspace.

Aligner les noms de profils entre coéquipiers​

Les scripts inclus figent un nom de profil Copera par défaut (COPERA_PROFILE="${COPERA_PROFILE:-<name>}"). Pour un workflow partagé en équipe, chaque coéquipier a besoin d'une entrée [profiles.<name>] avec le même nom dans son propre ~/.copera.toml — sinon la CLI cherchera le mauvais profil et le script échouera.

Lorsque l'agent construit un skill de workflow partagé, il vous demande de choisir le nom du profil (par défaut le nom kebab-case du workflow) et écrit une section Setup dans le SKILL.md généré pour que les nouveaux coéquipiers sachent exactement quoi ajouter :

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

Les tokens restent par coéquipier ; seuls le nom du profil et les IDs board/table sont partagés.

Les coéquipiers qui préfèrent ne pas ajouter un second profil peuvent surcharger par invocation :

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

— mais la convention de nommage s'échelle mieux. Documentez le nom de profil attendu dans l'onboarding de votre équipe aux côtés du skill lui-même.

astuce

Évitez de versionner des skills qui figent en dur des IDs de channels privés, des IDs de lignes spécifiques à un client, ou d'autres identifiants secrets du workspace si votre dépôt est public. L'agent signale cela pendant l'étape 7 de la procédure de construction.

Quand régénérer​

Vous n'en avez généralement pas besoin. La vérification de dérive gère les changements de schéma en place. Régénérez from scratch lorsque :

  • La procédure elle-même change (« nous notifions maintenant aussi Slack »).
  • Les phrases de déclenchement changent.
  • Vous avez renommé le workflow.
  • Vous voulez le pointer vers un board/table entièrement différent.

Dans tous ces cas, demandez à l'agent de « rebuild the triage-bug workflow » et repassez par l'interview.

Le skill CLI

Le fondement sur lequel s'appuient les skills de workflow.

Référence CLI

Les commandes que la section procédure référencera.