Saltar al contenido principal

Skills de flujo de trabajo

La Skill de la CLI enseña a un agente qué comandos copera existen. Una skill de flujo de trabajo le enseña qué hacer en tu Workspace: cuál board, cuál tabla, qué significan cuáles columnas, qué pasos encadenar, cómo confirmar.

No escribes skills de flujo de trabajo a mano. Le pides al agente que construya una para ti, y lo hace: entrevistando, explorando tu Workspace y emitiendo un archivo SKILL.md.

Cuándo construir una skill de flujo de trabajo​

Construye una cuando te descubras pidiéndole al agente que haga el mismo procedimiento más de una vez. Ejemplos:

  • "Clasifica este bug": registra una fila, establece la severidad, publica en #alerts, crea un doc de runbook.
  • "Envía el reporte semanal de ingeniería": consulta las filas actualizadas esta semana, resume, publica en un channel.
  • "Haz el onboarding de este cliente": crea una fila en el CRM, vincúlala a un contacto, genera un doc de kickoff.

No construyas una para tareas de un solo uso. El agente preguntará antes de convertir una solicitud en una skill.

Cómo la construye el agente​

Cuando dices "haz de esto un flujo de trabajo", el agente ejecuta el procedimiento build-workflow-skill. Nueve pasos:

Confirmar la intención

Verifica que quieres una skill reutilizable, no algo de un solo uso. Sale de este procedimiento si solo quieres hacerlo ahora.

Entrevista

Captura el nombre del flujo de trabajo (kebab-case), las frases disparadoras, las entradas, los pasos en lenguaje sencillo y la salida deseada. Te lo repite para que puedas corregir.

Explorar tu Workspace

Resuelve los nombres que mencionaste ("la tabla Bugs", "el doc de runbooks") a IDs reales ejecutando copera boards list / tables list / docs tree / drive tree. Pide aclaraciones si varias cosas coinciden.

Tomar una instantánea del esquema

Para cada tabla involucrada, ejecuta copera tables get <table-id> --board <board-id> --json y guarda el array completo de columnas (IDs, tipos y etiquetas de opciones) más un fingerprint determinista. Se usa solo para diagnósticos, no para verificaciones preventivas.

Elegir dónde guardar la skill + la base de SO

Pregunta dónde guardar (por defecto local del proyecto para flujos de trabajo compartidos por el equipo; global del usuario solo para automatizaciones personales) y cuál es la base de SO de tu equipo. Mismo SO para todos (macOS/Linux/WSL/Git Bash) → scripts bash; todos Windows nativo → PowerShell; mixto → opta por variantes duales. El valor predeterminado es bash con Git Bash / WSL en Windows: mantiene el paquete en una sola variante por verbo.

Escribir los scripts de verbo + la postura de confirmación

Para cada escritura copera que el flujo de trabajo realiza, genera un pequeño scripts/<verb>.sh (o .ps1) que recibe flags semánticos (--severity P1, --title "…") y los traduce a IDs de columna / opción de Copera internamente. Los IDs codificados eliminan la alucinación de IDs del LLM en tiempo de ejecución. Los scripts usan solo el shell + la CLI copera: sin jq, python ni node, ya que no todos los compañeros de equipo los tendrán instalados.

Cada script también recibe un flag Confirm (yes / no / yes (locked) para operaciones destructivas) decidido durante la entrevista de construcción. Las operaciones internas de create/update usan por defecto no (solo ejecutar); las de visibilidad externa y las masivas usan por defecto yes; las eliminaciones quedan bloqueadas a confirmar-siempre. El agente respeta el flag por script en tiempo de ejecución sin volver a preguntar, eliminando el impuesto de "aprobar cada llamada a un script".

Emitir SKILL.md y fingerprint.md

Rellena la workflow-skill-template en dos archivos Markdown. SKILL.md es liviano (procedimiento + tabla de scripts + un puntero de "en caso de error" de un párrafo). fingerprint.md contiene la instantánea del esquema y el procedimiento completo de manejo de desfase, y solo se carga cuando algo sale mal.

Ejecución de prueba + iteración

Ejecuta cada script de principio a fin contra tu Workspace real. Durante esta pasada de validación en tiempo de construcción, el agente hace una pausa antes de cada escritura sin importar el flag Confirm: el objetivo es detectar bugs y entradas incorrectas antes de fijar la skill. Itera contigo. Se detiene cuando confirmas que el flujo de trabajo se comporta correctamente. Tras la construcción, las invocaciones en tiempo de ejecución respetan el flag Confirm por script sin volver a preguntar.

La salida es un paquete de directorio: SKILL.md, fingerprint.md y una carpeta scripts/ de pequeños scripts bash. Portable, regenerable, versionable y legible por cada agente compatible con el estándar Agent Skills.

nota

Los scripts son bash por defecto: funcionan de inmediato en macOS / Linux / WSL / Git Bash. La convención predeterminada es "si estás en Windows, instala Git Bash o WSL". El agente solo generará variantes de PowerShell cuando el equipo sea completamente Windows nativo, o variantes duales .sh + .ps1 cuando el equipo sea mixto y opte explícitamente por ello (más mantenimiento).

nota

Los scripts generados evitan deliberadamente jq, python y node: cualquier cosa que no sea el shell + la CLI copera misma. Una dependencia faltante es un peor modo de falla para un compañero de equipo que un payload ligeramente más extenso construido con expansión de parámetros.

Cómo se ve una skill de flujo de trabajo​

Un paquete triage-bug simplificado:

triage-bug/
├── SKILL.md            # siempre cargado
├── fingerprint.md      # solo cargado ante error de script o actualización manual
└── scripts/
    ├── triage.sh       # registra una fila de triage
    └── notify.sh       # publica en #alerts

SKILL.md (extracto: liviano, sin ruido de esquema):

---
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 (extracto: solo cargado cuando se necesita):

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

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

El agente llama a bash scripts/triage.sh --severity P1 --title "Login broken", nunca a copera rows create directamente. Los IDs de columna y los IDs de opción no están en absoluto en el prompt del agente.

La plantilla completa está en el repo de skills.

Desfase de esquema: reactivo, no preventivo​

Los administradores del Workspace que editan columnas o etiquetas de opciones pueden romper silenciosamente las skills de flujo de trabajo que codificaron el esquema. Las skills de flujo de trabajo manejan esto de forma reactiva: no vuelven a obtener el esquema en cada invocación (tu PAT tiene un presupuesto bajo de límite de tasa; eso lo quemaría sin razón). La detección de desfase se ejecuta solo cuando una llamada a un script falla de una manera que sugiere que el esquema se movió.

La instantánea del esquema y el procedimiento completo de manejo de desfase viven en fingerprint.md, un archivo hermano que el agente solo carga cuando se necesita. Mantenerlo fuera de SKILL.md significa que el contexto de trabajo del agente se mantiene pequeño en el 99% de las ejecuciones en las que nada salió mal.

  1. El agente ejecuta bash scripts/<verb>.sh …. El script falla: código de salida distinto de cero, JSON de error de copera en stderr.

  2. El agente carga fingerprint.md (solo ahora, no antes) y sigue su clasificación:

    • De tipo esquema: invalid column, unknown columnId, invalid option, un 400/422 inesperado de una escritura. Continúa al paso 3.
    • No es desfase: auth_required, rate_limit, red/5xx. Lo expone y se detiene. No explora el esquema.

  3. Solo para los errores de tipo esquema, el agente dice:

    El script triage.sh falló con <error.message>. Esto parece indicar que el esquema de Bugs puede haber cambiado. ¿Quieres que obtenga el esquema actual y actualice esta skill?

  4. Con tu visto bueno, el agente ejecuta copera tables get <table-id> --board <board-id> --json para la tabla afectada, lo compara con la instantánea guardada en fingerprint.md, actualiza la sección Schema (frozen) en fingerprint.md Y los mapeos case relevantes dentro del script, actualiza schema_snapshot_date y vuelve a ejecutar la llamada fallida.

  5. Si dices "no", el agente sale. Nunca reintentas silenciosamente contra un esquema que sospechas que está desactualizado.

La receta del fingerprint es determinista: SHA-256 sobre el columnId:type de cada columna (más los IDs de opciones ordenados para columnas de elección), unidos separados por saltos de línea, los primeros 16 caracteres hexadecimales. Se guarda por tabla en fingerprint.md para que el agente tenga algo con qué comparar, no para que se ejecute en cada llamada.

También puedes forzar una actualización manual en cualquier momento: dile al agente "actualiza el esquema de <workflow-name>" y cargará fingerprint.md y ejecutará la misma ruta de actualización sin un disparador de error.

nota

La detección de desfase no puede saber cuándo una columna LINK ha sido reapuntada a una tabla vinculada diferente: el esquema de Copera no lleva esa información. Las skills de flujo de trabajo capturan el nombre de la tabla vinculada de la entrevista original y lo documentan como una limitación conocida.

Compartir skills de flujo de trabajo​

Una skill de flujo de trabajo es simplemente un directorio de archivos. La división recomendada:

  • La Skill de la CLI (la base del Nivel A): instálala globalmente, una vez por máquina de desarrollo. Consulta Instalación.
  • Skills de flujo de trabajo: versiónalas localmente en el proyecto, dentro del repositorio cuyo equipo las ejecutará. Hacen referencia a los IDs específicos de board / tabla / columna de tu Workspace, así que tienen forma de proyecto, no forma de usuario.

Para un flujo de trabajo de equipo:

  • Para todo el equipo (por defecto): guárdalo en .claude/skills/<name>/ (o el equivalente de tu agente) dentro del repositorio del proyecto y versiónalo. El agente de cada compañero de equipo lo recoge en cuanto hacen pull.
  • Personal: guárdalo en ~/.claude/skills/<name>/. Te sigue entre proyectos, no se comparte.
  • Público: sube el paquete a un repositorio público de GitHub. Cualquiera puede instalarlo mediante npx skills add owner/repo. Usa esto solo para ejemplos genéricos y no específicos de un Workspace.

Alinea los nombres de perfil entre compañeros de equipo​

Los scripts empaquetados codifican un nombre de perfil de Copera por defecto (COPERA_PROFILE="${COPERA_PROFILE:-<name>}"). Para un flujo de trabajo compartido por el equipo, cada compañero de equipo necesita una entrada [profiles.<name>] con el mismo nombre en su propio ~/.copera.toml, de lo contrario la CLI buscará el perfil equivocado y el script fallará.

Cuando el agente construye una skill de flujo de trabajo compartida, te pide elegir el nombre del perfil (por defecto el nombre kebab-case del flujo de trabajo) y escribe una sección de Setup en el SKILL.md generado para que los nuevos compañeros de equipo sepan exactamente qué agregar:

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

Los tokens se mantienen por compañero de equipo; solo se comparten el nombre del perfil y los IDs de board/tabla.

Los compañeros de equipo que prefieran no agregar un segundo perfil pueden sobrescribirlo por invocación:

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

— pero la convención de nombres escala mejor. Documenta el nombre de perfil esperado en el onboarding de tu equipo junto con la skill misma.

consejo

Evita versionar skills que codifiquen IDs de channels privados, IDs de filas específicas de clientes u otros identificadores secretos del Workspace si tu repositorio es público. El agente lo señala durante el paso 7 del procedimiento de construcción.

Cuándo regenerar​

Por lo general no necesitas hacerlo. La verificación de desfase maneja los cambios de esquema en su lugar. Regenera desde cero cuando:

  • El procedimiento en sí cambia ("ahora también notificamos a Slack").
  • Cambian las frases disparadoras.
  • Renombraste el flujo de trabajo.
  • Quieres apuntarlo a un board/tabla completamente diferente.

En todos esos casos, pídele al agente que "reconstruya el flujo de trabajo triage-bug" y recorre la entrevista de nuevo.

La Skill de la CLI

La base sobre la que se apoyan las skills de flujo de trabajo.

Referencia de la CLI

Los comandos que la sección de procedimiento referenciará.