Usar la Skill
Una vez instalada, la Skill de la CLI de Copera puede ser cargada por cualquier agente compatible con el estándar Agent Skills. Cómo la invocas depende del agente.
Invocación por agente
| Agente | Invocación |
|---|---|
| Claude Code | /copera:cli (explícita) o cualquier prompt que mencione Copera (auto-disparo). |
| Cursor | /copera-cli (explícita) o describe lo que quieres: la skill se asocia por descripción. |
| OpenCode | El descubrimiento es automático mediante la herramienta skill; simplemente pide una tarea de Copera. |
| Codex / Windsurf / Cline / Aider / Continue | Ambiental: el contenido de la skill se carga como parte del contexto del agente. Solo describe la tarea. |
Casi nunca necesitas invocar la skill explícitamente. Solo describe lo que quieres hacer en Copera, y el agente cargará la referencia correcta y la ejecutará.
Convenciones de la primera ejecución
La skill impone algunas reglas que hacen que las ejecuciones del agente sean predecibles. Conocerlas te ayuda a entender por qué los agentes hacen pausas o preguntan antes de actuar.
Descubrimiento antes de escribir
Antes de crear o actualizar cualquier cosa en un board que el agente no haya visto en esta sesión, ejecutará:
copera boards list --json
copera tables list --board <board-id> --json
copera tables get <table-id> --board <board-id> --json
Esto no es que el agente sea charlatán: los tipos de columna y las etiquetas de las opciones no se pueden adivinar. Saltarse la lectura del esquema es la causa más común de escrituras de filas rechazadas silenciosamente. La skill hace que esta regla sea obligatoria.
Confirmación cuando importa
El agente usa el criterio sobre cuándo hacer una pausa y preguntar. El valor predeterminado no es "confirmar cada escritura": eso es teatro de confirmación. En su lugar:
- Lecturas: se ejecutan en silencio y se resumen.
- Escrituras de rutina (
rows create,rows update, comentarios y mensajes internos,docs update,drive uploada una ruta nueva): cuando tu solicitud es inequívoca, el agente simplemente las ejecuta y reporta lo que cambió. Sin repetir. - El agente hace una pausa y pregunta cuando:
- Tuvo que inferir un valor que no especificaste (por ejemplo, no se dio la severidad y debe adivinarla).
- La operación llega fuera del Workspace (comentarios visibles externamente, channels de cara al cliente, cargas masivas).
- Dijiste explícitamente "pregúntame antes de cada paso" en la conversación.
- Operaciones destructivas (
rows delete,docs delete, eliminación forzada, sobrescritura masiva): siempre confirma, incluso si lo autorizaste de antemano.
Para las skills de flujo de trabajo (consulta Skills de flujo de trabajo), la postura de confirmación se decide en el momento de construcción de la skill por cada script, registrada como una columna Confirm en la tabla de Scripts de la skill. El agente la respeta sin volver a preguntar. Los scripts destructivos quedan bloqueados a confirmar-siempre; los no destructivos usan por defecto "solo ejecutar".
JSON primero
Cuando el agente necesita actuar sobre la salida de Copera, siempre pasa --json. La salida de la CLI con formato legible para humanos es para ti, no para el parser del agente.
Sesiones de ejemplo
Listar boards
Tú: ¿Qué boards tengo en Copera?
Agente: (ejecuta
copera boards list --json) Tienes tres boards: Engineering (66ab…), CRM (66cd…), Marketing (66ef…). ¿Quieres que profundice en alguno de ellos?
Crear una fila (con descubrimiento)
Tú: Crea un bug en la tabla Bugs titulado "Login button broken on Safari", severidad P1.
Agente: (ejecuta
copera tables list --board 66ab… --json) Veo dos tablas en Engineering:Bugs(66bg…) yReleases(66rl…). UsandoBugs.(ejecuta
copera tables get 66bg… --board 66ab… --json) El esquema tiene Status, Severity, Title, Description.(ejecuta
copera rows create --board 66ab… --table 66bg… --data '{…}' --json) Creé la fila #142 (66r1…): título "Login button broken on Safari", severidad P1, estado Triage.
El agente no repite la llamada antes de ejecutarla: tu solicitud fue inequívoca y la creación no es destructiva. Si hubieras especificado un valor inferido-por-el-agente (por ejemplo, "crea algún bug para mí"), o si esto fuera un rows delete, el agente haría una pausa y confirmaría.
Capturar un flujo de trabajo
Tú: Cada vez que te envíe un enlace de Sentry, registra una fila de triage en Bugs y publica una notificación en #alerts.
Agente: Eso suena como un flujo de trabajo que repetirás. ¿Quieres que lo guarde como una skill de flujo de trabajo reutilizable para que cualquier sesión futura pueda ejecutarlo de forma idéntica?
(continúa con la entrevista de build-workflow-skill)
Los perfiles eliminan la repetición
Si vas a pedirle al agente que opere sobre el mismo board+tabla repetidamente, configura un perfil de Copera para que los IDs queden pre-resueltos:
# ~/.copera.toml
default_profile = "bugs"
[profiles.bugs]
token = "cp_pat_…"
board_id = "66ab…"
table_id = "66bg…"
Entonces el agente puede ejecutar copera rows create --data '{…}' sin los flags --board / --table. Consulta Configuración de la CLI para el esquema completo del perfil, y Skills de flujo de trabajo para saber cómo el agente te ayuda a configurarlo automáticamente.
Qué esperar cuando cambia el esquema
Los administradores del Workspace que cambian una columna o la etiqueta de una opción pueden romper las skills de flujo de trabajo que codificaron el esquema. La detección es reactiva, no preventiva: la skill no obtiene el esquema en cada ejecución (eso quemaría el presupuesto de límite de tasa innecesariamente). En su lugar:
- El agente invoca el script empaquetado de un flujo de trabajo. El script devuelve un error de copera (por ejemplo, invalid option ID).
- El agente carga el
fingerprint.mddel flujo de trabajo (solo ahora, no antes), clasifica el error como de tipo esquema y hace una pausa. - Te dice que el esquema de
<table>puede haber cambiado y pregunta si obtener el esquema actual y actualizar la skill. - Con tu visto bueno, lo compara con la instantánea guardada, reescribe las secciones afectadas, actualiza la fecha de la instantánea y vuelve a ejecutar la llamada fallida.
- Si dices "no", sale limpiamente: nunca reintenta silenciosamente contra un esquema que sospecha que está desactualizado.
También puedes forzar una actualización en cualquier momento: "actualiza el esquema de <workflow-name>". Consulta Skills de flujo de trabajo → Desfase de esquema para el mecanismo completo.
Limitaciones
- La skill enseña el uso de la CLI; no reemplaza el binario de la CLI. Instala la CLI
coperaen la misma máquina. - Los comandos de docs requieren un Personal Access Token (
cp_pat_…). Las claves de integración (cp_key_…) funcionan para boards y channels, pero devuelven un error de autenticación en los endpoints de docs. - Los destinos de las columnas LINK no están en el esquema: el agente tiene que preguntarte cuál tabla está al otro lado. Las skills de flujo de trabajo que usan columnas LINK capturan esto durante la entrevista.