⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
kanban-zone
Interact with Kanban Zone kanban boards via the Kanban Zone API. Use when the user wants to manage kanban cards, boards, comments, checklists, tasks, webhooks, or board reports. Even if the user just says "check the board", "what's in progress", or mentions kanban cards, use this skill.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
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
- Log in to Kanban Zone and go to Settings → Organization Settings → Integrations → API Key. Direct link: https://kanbanzone.io/settings/integrations
- Click Generate (or copy an existing key).
- Paste the raw key into your
.envasKANBAN_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
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
SKILL.md7.8 KBupstream ↗
--- name: kanban-zone description: Interact with Kanban Zone kanban boards via the Kanban Zone API. Use when the user wants to manage kanban cards, boards, comments, checklists, tasks, webhooks, or board reports. Even if the user just says "check the board", "what's in progress", or mentions kanban cards, use this skill. license: MIT compatibility: Requires python3 and environment variables KANBAN_ZONE_API_KEY and KANBAN_ZONE_BOARD_ID. Wraps Kanban Zone Public API v1.4. metadata: version: "3.2.0" openclaw: requires: env: - KANBAN_ZONE_API_KEY - KANBAN_ZONE_BOARD_ID bins: - python3 primaryEnv: KANBAN_ZONE_API_KEY homepage: https://docs.kanbanzone.io --- # Kanban Zone Manage Kanban Zone kanban boards through the Kanban Zone Public API (v1.4). ## Delete operations work again (Kanban Zone fixed its API, 2026-06-11) If you have prior context saying delete commands are broken, it is stale: Kanban Zone fixed the server-side "Body Parser failed" defect that made every DELETE fail between 2026-05-16 and 2026-06-11. All five delete commands (`cards delete`, `checklists delete`, `tasks delete`, `webhooks delete`, `tokens revoke`) work normally. A successful delete prints `{"deleted": true, "id": ...}` and exits zero. The skill keeps a defensive check: if the old failure envelope ever reappears, the delete **fails loudly** (`KanbanZoneDeleteUnsupportedError`, exit non-zero) instead of reporting a fake success — if you see that error, the defect has regressed; tell the user and fall back to the Kanban Zone web UI. ## ⚠️ Monthly API usage limit (error code 2006) Kanban Zone enforces a **monthly API-call quota** per organization (usage is tracked per API key against the plan's limit). When the quota is exhausted, **every** API call fails until the monthly quota resets or the plan's limit is raised — and Kanban Zone returns the failure as **HTTP 200** with the error only in the response body: ```json {"code": 2006, "status": 429, "name": "TooManyRequests", "message": "API Usage limit reached"} ``` The skill detects this envelope and **exits non-zero** with a `KanbanZoneUsageLimitError` that explains the situation in full. It does **not** hand the envelope back as if it were data (before v3.2.0 this leaked through and made a quota-exhausted card lookup report "card not found"). **Guidance for agents:** - **Do not retry.** No request will succeed until the quota resets or the limit is raised, and retry loops burn through the fresh quota the moment it does. - **Direct the user to check their API usage status** in the Kanban Zone web interface: the **Organization > Integrations** panel (`https://kanbanzone.io/settings/integrations`). Its "Available API Calls" meter shows current usage against the plan's monthly limit, per API key. - Budget the remaining quota in normal operation: a cold-cache card-number lookup paginates `/cards` at one call per 100 cards, so keep the local cache warm and avoid polling loops. See `README.md` → "Monthly API usage limit" for the full technical detail. ## ⚠️ Exec Safety Rule — Multi-line Commands **Never pass multi-line shell commands or long `--description` strings inline to `exec`.** The exec preflight will block them as "complex interpreter invocation". **Always write to a temp file first:** ```python # Write description to temp file with open('/tmp/kanban-zone-desc.txt', 'w') as f: f.write("""Your multi-line description here""") # Then run the CLI via a script file script = '''import subprocess result = subprocess.run( ["python3", "skills/kanban-zone/scripts/kanban_zone_api.py", "cards", "update", "--id", "123", "--description", open("/tmp/kanban-zone-desc.txt").read()], capture_output=True, text=True ) print(result.stdout) print(result.stderr) ''' with open('/tmp/kanban-zone-run.py', 'w') as f: f.write(script) # Then exec: python3 /tmp/kanban-zone-run.py ``` Or simply build the whole call as a Python script in `/tmp/` and exec that file directly. ## ⚠️ Reading Command Output — do not pipe through inline parsers Every command prints a **single JSON value** to stdout and nothing else. On success it is the result object/array; on failure it is `{"error": true, "message": "..."}` **and the process exits non-zero**. **Do not pipe the output through an inline `python3 -c "..."` (or `jq`, `grep`, etc.) to pluck a field.** Two things go wrong, and both waste a turn: - The inline parser assumes the *success* shape. When the command fails, the output is the `{"error": ...}` object instead, so the parser raises `KeyError` on the field you expected — and that traceback **replaces** the genuinely helpful `message`, so you have to re-run the command bare just to see what actually went wrong. - Inline `python3 -c` scripts are exactly the "complex interpreter invocation" the exec preflight blocks (see the Exec Safety Rule above). **Instead:** run the command on its own with `--pretty` and read the JSON directly from the tool result. It is already structured — you do not need to post-process it. ```bash # GOOD — run it bare, read the JSON yourself python3 scripts/kanban_zone_api.py --pretty cards get --id 65 # BAD — parser crashes on the error shape and hides the real message python3 scripts/kanban_zone_api.py cards get --id 65 | python3 -c "import sys,json; print(json.load(sys.stdin)['CardItem']['title'])" ``` If a result is genuinely too large to read inline (e.g. `cards search` across many boards) and you must extract fields with a script, **write the script to a `/tmp/*.py` file** (per the Exec Safety Rule) and have it **check `if data.get("error"): ...` first** before touching success-shape keys. **Response shapes vary by command** — don't assume. `cards get` returns `{"_id", "CardItem", "meta"}` (the card is nested under `CardItem`); `cards list` / `cards search` return `{"count", "cards": [...]}` with each card wrapped in a `CardItem` envelope; `boards list` wraps each board in a `BoardItem` envelope. When unsure, run once with `--pretty` and look. ## Environment Setup The CLI script reads two environment variables: `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID`. The script **automatically loads** these from a `.env` file if they are not already in the environment. It searches the current working directory **and the script's own location (symlinks resolved)**, plus **every ancestor directory of each**, up to the filesystem root — so a workspace-root `.env` is found no matter which directory you run the command from. No shell export, `cd`, or command substitution is needed — just run the Python command directly. **You do not need to `cd` anywhere first.** If you see `--board or KANBAN_ZONE_BOARD_ID is required` or `KANBAN_ZONE_API_KEY is not set`, the `.env` is genuinely missing — do not retry from a different directory or re-run blindly. Either pass `--board <id>` / `--api-token <key>` explicitly, or tell the user the `.env` is not present in the workspace tree. **Get your API key:** Settings > Organization Settings > Integrations > API Key Direct: `https://kanbanzone.io/settings/integrations` **Find column IDs:** Board Settings > API, or Organization Settings > Integrations > API ## Quick Start All examples below assume a `.env` file with `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID` exists in the workspace root. ```bash python3 scripts/kanban_zone_api.py boards list python3 scripts/kanban_zone_api.py boards get python3 scripts/kanban_zone_api.py cards list --label "Bug" python3 scripts/kanban_zone_api.py cards get --id 42 python3 scripts/kanban_zone_api.py cards create --title "New task" --column-id COL1 python3 scripts/kanban_zone_api.py cards move --id 42 --column-id COL2 python3 scripts/kanban_zone_api.py cards delete --id 42 python3 scripts/kanban_zone_api.py comments add --card 42 --text "Looks good!" python3 scripts/kanban_zone_api.py checklists create --card 42 --title "QA" --task "T1" python3 scripts/kaREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/maxgood-ai-kanban-zone-agent-skill.md