kanban-zone

Kanban Zone Skill for Claude Code

What It Is

Manage your Kanban Zone boards — cards, columns, comments, checklists, tasks, webhooks, and flow reports — directly from any Claude Code-compatible workspace. Built in official partnership with Kanban Zone, this skill wraps the Kanban Zone Public API v1.4 using nothing but the Python 3 standard library: no virtual environment, no third-party packages, and no external runtime dependencies of any kind. Drop it into a repo, point it at your API key, and your AI assistant gains full board access in seconds.

Note on delete operations: All delete commands work normally. Each one checks that the response isn't a failure disguised behind an HTTP 200 status ("Body Parser failed" in the body instead of the deleted record); when it detects that pattern, it fails loudly (KanbanZoneDeleteUnsupportedError) instead of reporting a fake success.

⚠️ Monthly API usage limit (error code 2006)

Kanban Zone enforces a monthly API-call quota per organization, tracked per API key against the plan's limit. When the quota is exhausted, every API call fails until the month's quota resets or the plan's limit is raised.

What happens: Kanban Zone returns the rejection as HTTP 200, with the error visible only inside the response body ({"code": 2006, "status": 429, "name": "TooManyRequests", "message": "API Usage limit reached"}). Naive clients treat that as a successful, empty response instead of surfacing the underlying error.

What the skill does: every command detects the code-2006 envelope (and any other error envelope hidden behind an HTTP 200) and fails loudly — it exits non-zero with a KanbanZoneUsageLimitError stating that the request was rejected, that retrying will not help, and where to check usage.

What to do: check your usage in the Kanban Zone web interface under Organization > Integrations (https://kanbanzone.io/settings/integrations) — the "Available API Calls" meter shows consumption against your plan's monthly limit. To restore API access, wait for the monthly reset or upgrade the plan's API allowance.

Install

# Clone the skill into your project's skills/ directory (or anywhere on your path)
git clone https://github.com/MaxGood-AI/kanban-zone-agent-skill skills/kanban-zone

The skill is invoked directly via python3 scripts/kanban_zone_api.py ... — no plugin registration step is required.

Requirements: Python 3.8 or later (verify with python3 --version).

Create a .env file in the directory where you'll be working:

KANBAN_ZONE_API_KEY=your-api-key-here
KANBAN_ZONE_BOARD_ID=your-default-board-public-id

The skill loads .env automatically — no shell export needed. Discovery searches the current working directory and the script's own location (symlinks resolved), plus every ancestor directory of each, so a .env at your workspace root is found no matter which subdirectory you run the command from. KANBAN_ZONE_BOARD_ID sets the default board for every command; pass --board <id> to override it for a single call.

Multiple boards: create one .env per project folder, each with the relevant KANBAN_ZONE_BOARD_ID. The nearest .env (current directory or closest ancestor) wins, and a real environment variable always overrides a .env value. The same KANBAN_ZONE_API_KEY works across all boards and can be set once as a system environment variable if you prefer.

API Key

1. Log in to Kanban Zone and go to Settings → Organization Settings → Integrations → API Key. Direct link: https://kanbanzone.io/settings/integrations
2. Click Generate (or copy an existing key).
3. Paste the raw key into your .env as KANBAN_ZONE_API_KEY=.... The CLI base64-encodes it automatically before every request — do not pre-encode it yourself.

Cookbook

Each example below is a complete, copy-pasteable bash command. All examples use the grouped v3 command surface (boards list, cards create, etc.).

1. List boards and pick one to work on

Inspect all your boards at a glance before deciding which one to target for the session.

python3 scripts/kanban_zone_api.py boards list --include-columns

Pick the publicId from the output and drop it into your .env as KANBAN_ZONE_BOARD_ID, or pass --board <id> inline for a one-off override.

2. Create a card with watchers and custom fields

Create a fully annotated card in the "Backlog" column, assign it, add a watcher, and stamp two custom fields.

python3 scripts/kanban_zone_api.py cards create \
  --title "Q3 client proposal — Acme Corp" \
  --column-id COL_ABC123 \
  --owner [email protected] \
  --watcher [email protected] \
  --priority 1 --label "Sales" --size M --due-at "09/30/2026" \
  --custom-field "Client=Acme Corp" \
  --custom-field "Region=Northeast"

3. Update a description from a temp file

Long HTML descriptions clash with shell quoting. Write the body to a temp file first, then hand it to the CLI via --description-file.

python3 -c "
import textwrap
open('/tmp/desc.txt', 'w').write(textwrap.dedent('''
  <h3>Scope</h3>
  <p>Revised timeline following client call on 2026-05-09.</p>
  <ul>
    <li>Phase 1 due 2026-06-01</li>
    <li>Phase 2 due 2026-07-15</li>
  </ul>
''').strip())
"
python3 scripts/kanban_zone_api.py cards update --id 42 \
  --description-file /tmp/desc.txt

Note: Kanban Zone renders descriptions as HTML. Use <pre> blocks for any tabular data — <table> tags are silently stripped by the platform.

4. Move a card to "In Progress"

Provide the target column ID (visible in Board Settings → API).

python3 scripts/kanban_zone_api.py cards move --id 42 --column-id COL_INPROG

5. Add a comment to a card

Post a status update or question directly on the card's activity feed.

python3 scripts/kanban_zone_api.py comments add --card 42 \
  --text "Scope confirmed with client. Proceeding to design phase."

6. Create a checklist with tasks; mark one complete

Add a QA checklist to a card, then immediately mark the first task done.

# Create the checklist (returns the checklist ID and first task ID)
python3 scripts/kanban_zone_api.py checklists create --card 42 \
  --title "QA Sign-off" \
  --task "Smoke test on staging" \
  --task "Cross-browser check" \
  --task "Accessibility audit"

# Mark task 1001 complete (replace with the returned task ID)
python3 scripts/kanban_zone_api.py tasks update --id 1001 --completed true

7. Register a webhook and verify a delivery's signature

Subscribe to card-created events, then use the built-in HMAC verifier to confirm the first delivery is authentic.

# Register the webhook (set the org-level Webhook Key in Kanban Zone Settings → Integrations first)
python3 scripts/kanban_zone_api.py webhooks create \
  --url "https://hooks.yourapp.com/kanban" \
  --event CARD_CREATED

# After the first delivery arrives, verify its signature (key from KANBAN_ZONE_WEBHOOK_KEY env or --webhook-key)
python3 scripts/kanban_zone_api.py webhooks verify-signature \
  --payload-file /tmp/webhook-body.json \
  --signature "<raw-hex-from-X-KanbanZone-Signature-header>" \
  --webhook-key "your-webhook-key"

8. Pull a throughput report for the last quarter

Measure how many cards were completed between two dates.

python3 scripts/kanban_zone_api.py reports throughput \
  --from-date 2026-01-01 --to-date 2026-03-31

Other available report types: arrival-rate, cycle-time, lead-time, flow, flow-efficiency, allocation, abandoned-effort.

9. Audit overdue cards across all boards

Search across every board you can access for cards matching a label, owner, or free-text query.

# cards search supports --query / --label / --owner across all boards.
# The skill iterates every board and applies these filters client-side.
python3 scripts/kanban_zone_api.py cards