Pular para o conteúdo principal

Skills de Workflow

A skill da CLI ensina a um agente quais comandos copera existem. Uma skill de workflow ensina a ele o que fazer no seu workspace — qual board, qual tabela, o que cada coluna significa, quais passos encadear, como confirmar.

Você não escreve skills de workflow à mão. Você pede ao agente para construir uma para você, e ele faz — entrevistando, sondando seu workspace e emitindo um arquivo SKILL.md.

Quando construir uma skill de workflow​

Construa uma quando você se pegar pedindo ao agente para fazer o mesmo procedimento mais de uma vez. Exemplos:

  • "Trie este bug" — registre uma linha, defina a severidade, poste em #alerts, crie um doc de runbook.
  • "Envie o relatório semanal de engenharia" — consulte linhas atualizadas nesta semana, resuma, poste em um channel.
  • "Faça o onboarding deste cliente" — crie uma linha no CRM, vincule a um contato, gere um doc de kickoff.

Não construa uma para tarefas de uma única vez. O agente vai perguntar antes de transformar um pedido em uma skill.

Como o agente a constrói​

Quando você diz "transforme isso em um workflow", o agente roda o procedimento build-workflow-skill. Nove passos:

Confirmar intenção

Verifica se você quer uma skill reutilizável, não uma de uma única vez. Sai deste procedimento se você só quer que seja feito agora.

Entrevistar

Captura o nome do workflow (kebab-case), frases de acionamento, entradas, passos em português simples e a saída desejada. Repete de volta para você poder corrigir.

Sondar seu workspace

Resolve os nomes que você mencionou ("a tabela Bugs", "o doc de runbooks") para IDs reais rodando copera boards list / tables list / docs tree / drive tree. Pede esclarecimento se múltiplas coisas correspondem.

Tirar um snapshot do schema

Para cada tabela envolvida, roda copera tables get <table-id> --board <board-id> --json e salva o array completo de colunas — IDs, tipos e rótulos de opções — mais um fingerprint determinístico. Usado apenas para diagnósticos, não para verificações pré-execução.

Escolher onde salvar a skill + a baseline de SO

Pergunta onde salvar (padrão local do projeto para workflows compartilhados pelo time; global do usuário apenas para automações pessoais) e qual é a baseline de SO do seu time. Mesmo SO para todos (macOS/Linux/WSL/Git Bash) → scripts bash; todos Windows-nativo → PowerShell; misto → opta por variantes duplas. O padrão é bash com Git Bash / WSL no Windows — mantém o pacote em um sabor por verbo.

Escrever os scripts de verbo + postura de confirmação

Para cada escrita copera que o workflow realiza, gera um pequeno scripts/<verb>.sh (ou .ps1) que recebe flags semânticas (--severity P1, --title "…") e as traduz para IDs de coluna / opção da Copera internamente. IDs fixos eliminam a alucinação de IDs do LLM em tempo de execução. Os scripts usam apenas o shell + a copera CLI — sem jq, python ou node, já que nem todo colega de time os terá instalados.

Cada script também ganha uma flag Confirm (yes / no / yes (locked) para ops destrutivas) decidida durante a entrevista de construção. Create/update interno tem padrão no (simplesmente executa); ops de visibilidade externa e em massa têm padrão yes; deletes são travados em sempre-confirmar. O agente honra a flag por script em tempo de execução sem perguntar de novo — elimina o imposto de "aprovar toda chamada de script".

Emitir SKILL.md e fingerprint.md

Preenche o workflow-skill-template em dois arquivos markdown. SKILL.md é enxuto (procedimento + tabela de scripts + um ponteiro "em caso de erro" de um parágrafo). fingerprint.md guarda o snapshot do schema e o procedimento completo de tratamento de mudanças — carregado apenas quando algo dá errado.

Dry-run + iterar

Roda cada script de ponta a ponta contra seu workspace real. Durante essa passagem de validação em tempo de construção, o agente pausa antes de toda escrita independentemente da flag Confirm — o objetivo é pegar bugs e entradas ruins antes de travar a skill. Itera com você. Para quando você confirma que o workflow se comporta corretamente. Após a construção, as invocações em tempo de execução honram a flag Confirm por script sem perguntar de novo.

A saída é um pacote de diretório — SKILL.md, fingerprint.md e uma pasta scripts/ de pequenos scripts bash. Portátil, regenerável, versionável e legível por todo agente que suporta o padrão Agent Skills.

observação

Os scripts são bash por padrão — funcionam de imediato no macOS / Linux / WSL / Git Bash. A convenção padrão é "se você está no Windows, instale o Git Bash ou WSL". O agente só gerará variantes PowerShell quando o time for totalmente Windows-nativo, ou variantes duplas .sh + .ps1 quando o time for misto e explicitamente optar por isso (mais manutenção).

observação

Os scripts gerados deliberadamente evitam jq, python e node — qualquer coisa que não seja o shell + a própria copera CLI. Uma dependência faltante é um modo de falha pior para um colega de time do que um payload um pouco mais verboso construído com expansão de parâmetros.

Como é uma skill de workflow​

Um pacote triage-bug simplificado:

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 (trecho — enxuto, sem ruído de 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 (trecho — carregado apenas quando necessário):

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

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

O agente chama bash scripts/triage.sh --severity P1 --title "Login broken" — nunca copera rows create diretamente. IDs de coluna e IDs de opção não estão no prompt do agente de forma alguma.

O template completo está no repositório de skills.

Mudança de schema — reativa, não pré-execução​

Admins do workspace editando colunas ou rótulos de opções podem quebrar silenciosamente skills de workflow que fixaram o schema. As skills de workflow lidam com isso reativamente: elas não rebuscam o schema em toda invocação (seu PAT tem um orçamento baixo de limite de taxa; isso o queimaria sem motivo). A detecção de mudança roda apenas quando uma chamada de script falha de uma forma que sugere que o schema mudou.

O snapshot do schema e o procedimento completo de tratamento de mudanças vivem em fingerprint.md, um arquivo irmão que o agente só carrega quando necessário. Mantê-lo fora do SKILL.md significa que o contexto de trabalho do agente permanece pequeno nos 99% das execuções em que nada deu errado.

  1. O agente roda bash scripts/<verb>.sh …. O script falha — código de saída não-zero, JSON de erro do copera no stderr.

  2. O agente carrega o fingerprint.md (só agora, não antes) e segue sua classificação:

    • Sabor de schema — invalid column, unknown columnId, invalid option, 400/422 inesperado de uma escrita. Continue para o passo 3.
    • Não é mudança — auth_required, rate_limit, rede/5xx. Apresente e pare. Não sonde o schema.

  3. Apenas para erros com sabor de schema, o agente diz:

    O script triage.sh falhou com <error.message>. Isso parece que o schema de Bugs pode ter mudado. Quer que eu busque o schema atual e atualize esta skill?

  4. Com seu OK, o agente roda copera tables get <table-id> --board <board-id> --json para a tabela afetada, faz o diff contra o snapshot salvo em fingerprint.md, atualiza a seção Schema (frozen) no fingerprint.md E os mapeamentos case relevantes dentro do script, atualiza schema_snapshot_date e roda novamente a chamada que falhou.

  5. Com "não", o agente sai. Você nunca tenta de novo silenciosamente contra um schema que suspeita estar desatualizado.

A receita do fingerprint é determinística: SHA-256 sobre o columnId:type de cada coluna (mais IDs de opções ordenados para colunas de escolha), unido separado por nova linha, primeiros 16 caracteres hex. Ele é salvo por tabela em fingerprint.md para que o agente tenha algo contra o que fazer diff — não para que rode em toda chamada.

Você também pode forçar uma atualização manual a qualquer momento: diga ao agente "atualize o schema de <workflow-name>" e ele carrega o fingerprint.md e roda o mesmo caminho de atualização sem um gatilho de erro.

observação

A detecção de mudança não consegue saber quando uma coluna LINK foi redirecionada para uma tabela vinculada diferente — o schema da Copera não carrega essa informação. As skills de workflow capturam o nome da tabela vinculada da entrevista original e o documentam como uma limitação conhecida.

Compartilhando skills de workflow​

Uma skill de workflow é apenas um diretório de arquivos. A divisão recomendada:

  • A skill da CLI (a base do Tier A) — instale globalmente, uma vez por máquina de desenvolvedor. Veja Instalar.
  • Skills de workflow — versione-as localmente no projeto, dentro do repositório cujo time as rodará. Elas referenciam os IDs específicos de board / tabela / coluna do seu workspace, então são moldadas pelo projeto, não pelo usuário.

Para um workflow de time:

  • Todo o time (padrão) — salve em .claude/skills/<name>/ (ou o equivalente do seu agente) dentro do repositório do projeto e versione. O agente de cada colega o pega no momento em que eles fazem o pull.
  • Pessoal — salve em ~/.claude/skills/<name>/. Segue você entre projetos, não é compartilhado.
  • Público — envie o pacote para um repositório público do GitHub. Qualquer um pode instalar via npx skills add owner/repo. Use isto apenas para exemplos genéricos e não específicos do workspace.

Alinhe os nomes de perfil entre os colegas de time​

Os scripts empacotados fixam um nome de perfil padrão da Copera (COPERA_PROFILE="${COPERA_PROFILE:-<name>}"). Para um workflow compartilhado pelo time, cada colega precisa de uma entrada [profiles.<name>] com o mesmo nome no seu próprio ~/.copera.toml — caso contrário, a CLI buscará o perfil errado e o script falhará.

Quando o agente constrói uma skill de workflow compartilhada, ele pede que você escolha o nome do perfil (padrão é o nome kebab-case do workflow) e escreve uma seção Setup no SKILL.md gerado para que novos colegas saibam exatamente o que adicionar:

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

Os tokens permanecem por colega de time; apenas o nome do perfil e os IDs de board/tabela são compartilhados.

Colegas que prefiram não adicionar um segundo perfil podem sobrepor por invocação:

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

— mas a convenção nomeada escala melhor. Documente o nome de perfil esperado no onboarding do seu time junto com a própria skill.

dica

Evite versionar skills que fixam IDs de channels privados, IDs de linhas específicas de clientes ou outros identificadores secretos do workspace se seu repositório for público. O agente sinaliza isso durante o passo 7 do procedimento de construção.

Quando regenerar​

Você normalmente não precisa. A verificação de mudança lida com alterações de schema no lugar. Regenere do zero quando:

  • O próprio procedimento muda ("agora também notificamos o Slack").
  • As frases de acionamento mudam.
  • Você renomeou o workflow.
  • Você quer apontá-lo para um board/tabela totalmente diferente.

Em todos esses casos, peça ao agente para "reconstruir o workflow triage-bug" e percorra a entrevista novamente.

A skill da CLI

A base sobre a qual as skills de workflow se apoiam.

Referência da CLI

Os comandos que a seção de procedimento referenciará.