Pular para o conteúdo principal

Usando a Skill

Uma vez instalada, a skill da Copera CLI pode ser carregada por qualquer agente que suporte o padrão Agent Skills. Como você a invoca depende do agente.

Invocação por agente​

AgenteInvocação
Claude Code/copera:cli (explícito) ou qualquer prompt mencionando a Copera (acionamento automático).
Cursor/copera-cli (explícito) ou descreva o que você quer — a skill é correspondida por descrição.
OpenCodeA descoberta é automática via a ferramenta skill; basta pedir uma tarefa da Copera.
Codex / Windsurf / Cline / Aider / ContinueAmbiente — o conteúdo da skill é carregado como parte do contexto do agente. Basta descrever a tarefa.

Você quase nunca precisa invocar a skill explicitamente. Apenas descreva o que você quer feito na Copera, e o agente carregará a referência certa e executará.

Convenções de primeira execução​

A skill impõe algumas regras que tornam as execuções dos agentes previsíveis. Conhecê-las ajuda você a entender por que os agentes pausam ou perguntam antes de agir.

Descoberta antes das escritas​

Antes de criar ou atualizar qualquer coisa em um board que o agente não viu nesta sessão, ele rodará:

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

Isso não é o agente sendo tagarela — tipos de coluna e rótulos de opções não são adivinháveis. Pular a leitura do schema é a causa mais comum de escritas de linha silenciosamente rejeitadas. A skill torna essa regra obrigatória.

Confirmação quando importa​

O agente usa bom senso sobre quando pausar e perguntar. O padrão não é "confirmar toda escrita" — isso é teatro de confirmação. Em vez disso:

  • Leituras — rodam silenciosamente e resumem.
  • Escritas de rotina (rows create, rows update, comentários e mensagens internas, docs update, drive upload para um caminho novo) — quando seu pedido é inequívoco, o agente simplesmente as executa e relata o que mudou. Sem reformulação.
  • O agente pausa e pergunta quando:
    1. Ele teve de inferir um valor que você não especificou (ex.: severidade não fornecida, precisa adivinhar).
    2. A operação alcança fora do workspace (comentários de visibilidade externa, channels voltados ao cliente, uploads em massa).
    3. Você disse explicitamente "me pergunte antes de cada passo" na conversa.
  • Operações destrutivas (rows delete, docs delete, force-delete, sobrescrita em massa) — sempre confirme, mesmo que você tenha pré-autorizado.

Para skills de workflow (veja Skills de Workflow), a postura de confirmação é decidida no momento de construção da skill por script — registrada como uma coluna Confirm na tabela de Scripts da skill. O agente honra isso sem perguntar de novo. Scripts destrutivos são travados em sempre-confirmar; os não-destrutivos têm como padrão "simplesmente executar".

JSON em primeiro lugar​

Quando o agente precisa agir sobre a saída da Copera, ele sempre passa --json. A saída da CLI formatada para humanos é para você, não para o parser do agente.

Sessões de exemplo​

Listando boards​

Você: Quais boards eu tenho na Copera?

Agente: (roda copera boards list --json) Você tem três boards: Engineering (66ab…), CRM (66cd…), Marketing (66ef…). Quer que eu detalhe algum deles?

Criando uma linha (com descoberta)​

Você: Crie um bug na tabela Bugs com o título "Login button broken on Safari", severidade P1.

Agente: (roda copera tables list --board 66ab… --json) Vejo duas tabelas em Engineering: Bugs (66bg…) e Releases (66rl…). Usando Bugs.

(roda copera tables get 66bg… --board 66ab… --json) O schema tem Status, Severity, Title, Description.

(roda copera rows create --board 66ab… --table 66bg… --data '{…}' --json) Criei a linha #142 (66r1…) — título "Login button broken on Safari", severidade P1, status Triage.

O agente não reformula a chamada antes de executá-la — seu pedido era inequívoco e a criação é não-destrutiva. Se você tivesse especificado um valor inferido-pelo-agente (ex.: "crie algum bug para mim"), ou se isso fosse um rows delete, o agente pausaria e confirmaria.

Capturando um workflow​

Você: Toda vez que eu te enviar um link do Sentry, registre uma linha de triagem em Bugs e poste uma notificação em #alerts.

Agente: Isso parece um workflow que você vai repetir. Quer que eu o salve como uma skill de workflow reutilizável para que qualquer sessão futura possa executá-lo de forma idêntica?

(continua com a entrevista de build-workflow-skill)

Perfis cortam a repetição​

Se você vai pedir ao agente para operar no mesmo board+tabela repetidamente, configure um perfil da Copera para que os IDs sejam pré-resolvidos:

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

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

Então o agente pode rodar copera rows create --data '{…}' sem as flags --board / --table. Veja Configuração da CLI para o schema completo de perfis, e Skills de Workflow para como o agente ajuda você a configurar isso automaticamente.

O que esperar quando o schema muda​

Admins do workspace mudando uma coluna ou um rótulo de opção podem quebrar skills de workflow que fixaram o schema. A detecção é reativa, não pré-execução — a skill não busca o schema em toda execução (isso queimaria orçamento de limite de taxa desnecessariamente). Em vez disso:

  1. O agente invoca um script empacotado de um workflow. O script retorna um erro do copera (ex.: invalid option ID).
  2. O agente carrega o fingerprint.md do workflow (só agora, não antes), classifica o erro como sendo de schema e pausa.
  3. Ele te diz que o schema de <table> pode ter mudado e pergunta se deve buscar o schema atual e atualizar a skill.
  4. Com seu OK, ele faz o diff contra o snapshot salvo, reescreve as seções afetadas, atualiza a data do snapshot e roda novamente a chamada que falhou.
  5. Com "não", ele sai de forma limpa — nunca tenta de novo silenciosamente contra um schema que suspeita estar desatualizado.

Você também pode forçar uma atualização a qualquer momento: "atualize o schema de <workflow-name>". Veja Skills de Workflow → Mudança de schema para o mecanismo completo.

Limitações​

  • A skill ensina o uso da CLI; ela não substitui o binário da CLI. Instale a copera CLI na mesma máquina.
  • Os comandos de docs exigem um Personal Access Token (cp_pat_…). Integration keys (cp_key_…) funcionam para boards e channels, mas retornam um erro de autenticação em endpoints de docs.
  • Os destinos de colunas LINK não estão no schema — o agente precisa perguntar a você qual tabela está do outro lado. Skills de workflow que usam colunas LINK capturam isso na entrevista.