Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.copera.ai/llms.txt

Use this file to discover all available pages before exploring further.

The CLI skill teaches an agent what copera commands exist. A workflow skill teaches it what to do in your workspace — which board, which table, which columns mean what, what steps to chain, how to confirm. You don’t write workflow skills by hand. You ask the agent to build one for you, and it does — by interviewing, probing your workspace, and emitting a SKILL.md file.

​
When to build a workflow skill

Build one when you catch yourself asking the agent to do the same procedure more than once. Examples:
  • “Triage this bug” — file a row, set severity, post to #alerts, create a runbook doc.
  • “Send the weekly engineering report” — query rows updated this week, summarize, post to a channel.
  • “Onboard this customer” — create a row in CRM, link to a contact, generate a kickoff doc.
Don’t build one for one-shot tasks. The agent will ask before turning a request into a skill.

​
How the agent builds it

When you say “make this a workflow”, the agent runs the build-workflow-skill procedure. Nine steps:
1

Confirm intent

Verifies you want a reusable skill, not a one-shot. Exits this procedure if you just want it done now.
2

Interview

Captures the workflow name (kebab-case), trigger phrases, inputs, plain-English steps, and desired output. Echoes it back so you can correct.
3

Probe your workspace

Resolves names you mentioned (“the Bugs table”, “the runbooks doc”) to real IDs by running copera boards list / tables list / docs tree / drive tree. Asks for clarification if multiple things match.
4

Snapshot the schema

For every table involved, runs copera tables get --json and saves the full column array — IDs, types, and option labels — plus a deterministic fingerprint. Used for diagnostics only, not for pre-flight checks.
5

Choose where to save the skill + the OS baseline

Asks where to save (defaults to project-local for team-shared workflows; user-global only for personal automations) and what your team’s OS baseline is. Same OS for everyone (macOS/Linux/WSL/Git Bash) → bash scripts; all Windows-native → PowerShell; mixed → opts into dual variants. Default is bash with Git Bash / WSL on Windows — keeps the bundle to one flavor per verb.
6

Write the verb scripts + confirmation posture

For each copera write the workflow performs, generates a small scripts/<verb>.sh (or .ps1) that takes semantic flags (--severity P1, --title "…") and translates them to Copera column / option IDs internally. Hardcoded IDs eliminate LLM ID-hallucination at runtime. Scripts use only the shell + the copera CLI — no jq, python, or node, since not every teammate will have them installed.Each script also gets a Confirm flag (yes / no / yes (locked) for destructive ops) decided during the build interview. Internal create/update default to no (just run); external-visibility and bulk ops default to yes; deletes are locked to always-confirm. The agent honors the per-script flag at runtime without re-asking — eliminates the “approve every script call” tax.
7

Emit SKILL.md and fingerprint.md

Fills the workflow-skill-template into two markdown files. SKILL.md is slim (procedure + scripts table + a one-paragraph “on error” pointer). fingerprint.md holds the schema snapshot and the full drift-handling procedure — only loaded when something goes wrong.
8

Dry-run + iterate

Runs each script end-to-end against your real workspace. During this build-time validation pass, the agent pauses before every write regardless of Confirm flag — the goal is to catch bugs and bad inputs before locking the skill in. Iterates with you. Stops when you confirm the workflow behaves correctly. After build, runtime invocations honor the per-script Confirm flag without re-asking.
The output is a directory bundle — SKILL.md, fingerprint.md, and a scripts/ folder of small bash scripts. Portable, regenerable, committable, and readable by every agent that supports the Agent Skills standard.
Scripts are bash by default — works out of the box on macOS / Linux / WSL / Git Bash. The default convention is “if you’re on Windows, install Git Bash or WSL”. The agent will only generate PowerShell variants when the team is fully Windows-native, or dual .sh + .ps1 variants when the team is mixed and explicitly opts in (more maintenance).
Generated scripts deliberately avoid jq, python, and node — anything that isn’t shell + the copera CLI itself. A missing dependency is a worse failure mode for a teammate than a slightly verbose payload built with parameter expansion.

​
What a workflow skill looks like

A simplified triage-bug bundle: 
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 (excerpt — slim, no schema noise): 
---
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 (excerpt — only loaded when needed): 
# 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 (excerpt): 
#!/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
The agent calls bash scripts/triage.sh --severity P1 --title "Login broken" — never copera rows create directly. Column IDs and option IDs are not in the agent’s prompt at all. The full template is in the skills repo.

​
Schema drift — reactive, not pre-flight

Workspace admins editing columns or option labels can silently break workflow skills that hardcoded the schema. Workflow skills handle this reactively: they don’t refetch the schema on every invocation (your PAT has a low rate-limit budget; that would burn it for no reason). Drift detection runs only when a script call fails in a way that suggests the schema moved. The schema snapshot and the full drift-handling procedure live in fingerprint.md, a sibling file the agent only loads when needed. Keeping it out of SKILL.md means the agent’s working context stays small on the 99% of runs where nothing has gone wrong.
  1. The agent runs bash scripts/<verb>.sh …. The script fails — exit code non-zero, copera error JSON on stderr.
  2. The agent loads fingerprint.md (only now, not before) and follows its classification:
    • Schema-flavored — invalid column, unknown columnId, invalid option, unexpected 400/422 from a write. Continue to step 3.
    • Not drift — auth_required, rate_limit, network/5xx. Surface and stop. Don’t probe the schema.
  3. For schema-flavored errors only, the agent says:
    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. On your OK, the agent runs copera tables get --json for the affected table, diffs against the saved snapshot in fingerprint.md, updates the Schema (frozen) section in fingerprint.md AND the relevant case mappings inside the script, bumps schema_snapshot_date, and re-runs the failing call.
  5. On “no”, the agent exits. You never silently retry against a schema you suspect is stale.
The fingerprint recipe is deterministic: SHA-256 over each column’s columnId:type (plus sorted option IDs for choice columns), joined newline-separated, first 16 hex chars. It’s saved per-table in fingerprint.md so the agent has something to diff against — not so it runs on every call. You can also force a manual refresh at any time: tell the agent “refresh the schema for <workflow-name>” and it loads fingerprint.md and runs the same update path without an error trigger.
Drift detection cannot tell when a LINK column has been retargeted to a different linked table — the Copera schema doesn’t carry that information. Workflow skills capture the linked table name from the original interview and document it as a known limitation.

​
Sharing workflow skills

A workflow skill is just a directory of files. The recommended split:
  • The CLI skill (the Tier A foundation) — install globally, once per developer machine. See Install.
  • Workflow skills — commit them project-local, inside the repo whose team will run them. They reference your workspace’s specific board / table / column IDs, so they’re project-shaped, not user-shaped.
For a team workflow:
  • Team-wide (default) — save to .claude/skills/<name>/ (or your agent’s equivalent) inside the project repo and commit. Every teammate’s agent picks it up the moment they pull.
  • Personal — save to ~/.claude/skills/<name>/. Follows you across projects, not shared.
  • Public — push the bundle to a public GitHub repo. Anyone can install via npx skills add owner/repo. Use this only for generic, non-workspace-specific examples.

​
Align profile names across teammates

The bundled scripts hardcode a default Copera profile name (COPERA_PROFILE="${COPERA_PROFILE:-<name>}"). For a team-shared workflow, every teammate needs a [profiles.<name>] entry with the same name in their own ~/.copera.toml — otherwise the CLI will look up the wrong profile and the script will fail. When the agent builds a shared workflow skill, it asks you to pick the profile name (defaults to the workflow’s kebab-case name) and writes a Setup section into the generated SKILL.md so new teammates know exactly what to add: 
# ~/.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…"
Tokens stay per-teammate; only the profile name and the board/table IDs are shared. Teammates who’d rather not add a second profile can override per invocation: 
COPERA_PROFILE=my-existing-profile bash scripts/triage.sh --severity P1 --title "…"
— but the named-convention scales better. Document the expected profile name in your team’s onboarding alongside the skill itself.
Avoid committing skills that hardcode private channel IDs, customer-specific row IDs, or other workspace-secret identifiers if your repo is public. The agent flags this during step 7 of the build procedure.

​
When to regenerate

You don’t usually need to. The drift-check handles schema changes in-place. Regenerate from scratch when:
  • The procedure itself changes (“we now also notify Slack”).
  • The trigger phrases change.
  • You renamed the workflow.
  • You want to point it at a different board/table altogether.
In all those cases, ask the agent to “rebuild the triage-bug workflow” and walk through the interview again.

The CLI skill

The foundation that workflow skills sit on top of.

CLI Reference

The commands the procedure section will reference.