菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| 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"}} |
Manage Kanban Zone kanban boards through the Kanban Zone Public API (v1.4).
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.
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:
{"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:
https://kanbanzone.io/settings/integrations). Its "Available API Calls"
meter shows current usage against the plan's monthly limit, per API key./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.
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:
# 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.
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:
{"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.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.
# 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.
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
All examples below assume a .env file with KANBAN_ZONE_API_KEY and KANBAN_ZONE_BOARD_ID exists in the workspace root.
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/kanban_zone_api.py reports throughput --from-date 2026-01-01 --to-date 2026-04-01
Commands are organized into nine resource groups. Run python3 scripts/kanban_zone_api.py <group> --help to see subcommands for any group. Run python3 scripts/kanban_zone_api.py <group> <subcommand> --help for full flag details.
Manage boards and their metadata.
python3 scripts/kanban_zone_api.py boards list
python3 scripts/kanban_zone_api.py boards get --include-columns
python3 scripts/kanban_zone_api.py boards custom-fields
| Subcommand | Description |
|---|---|
list | List all boards with metrics (active/blocked/overdue counts) |
get | Get a specific board's details; --include-columns adds column data and WIP limits |
columns | List all columns for the active board |
labels | List all labels defined on the active board |
members | List all members of the active board |
custom-fields | List custom field definitions for the active board |
templates | List card templates available on the active board |
Create, read, update, move, delete, and search cards.
python3 scripts/kanban_zone_api.py cards list --label "Bug" --blocked
python3 scripts/kanban_zone_api.py cards create --title "New task" --column-id COL1 --owner dev@example.com
python3 scripts/kanban_zone_api.py cards move --id 42 --column-id COL2
| Subcommand | Description |
|---|---|
list | List cards on the active board with optional filters (label, owner, column, blocked, priority, query) |
get | Get a single card by number or ObjectId |
create | Create one card (supports watchers, custom fields, description file) |
create-bulk | Create multiple cards from a JSON file |
update | Update card fields (title, description, owner, watchers, custom fields, blocked status) |
move | Move a card to a different column |
delete | Delete a card |
history | Get the activity history for a card |
metrics | Get cycle time and lead time metrics for a card |
links-add | Add a card-to-card or external URL link to a card |
links-remove | Remove a card-to-card or external URL link from a card |
search | Search cards across all boards by keyword and optional filters |
wip-check | Check WIP limits across all columns, flagging over/under-limit columns |
Add and list comments on cards.
python3 scripts/kanban_zone_api.py comments add --card 42 --text "Review complete."
python3 scripts/kanban_zone_api.py comments list --card 42
| Subcommand | Description |
|---|---|
add | Add a comment to a card |
list | List all comments on a card |
Manage checklists and their inline tasks attached to cards.
python3 scripts/kanban_zone_api.py checklists create --card 42 --title "Release QA" --task "Run tests" --task "Update docs"
python3 scripts/kanban_zone_api.py checklists list --card 42
| Subcommand | Description |
|---|---|
create | Create a checklist on a card, optionally pre-populating it with tasks |
update | Update a checklist's title or reorder its tasks |
delete | Delete a checklist |
list | List all checklists (and their tasks) on a card |
Manage individual tasks within a checklist.
python3 scripts/kanban_zone_api.py tasks create --checklist CHECKLIST_ID --title "Write tests"
python3 scripts/kanban_zone_api.py tasks update --id TASK_ID --completed true
| Subcommand | Description |
|---|---|
create | Add a task to an existing checklist |
update | Update a task (title, completed status, assignee) |
delete | Delete a task |
move | Reorder a task within its checklist |
Register and manage webhooks for board event notifications.
python3 scripts/kanban_zone_api.py webhooks list
python3 scripts/kanban_zone_api.py webhooks create --url https://hooks.example.com/kanban-zone-webhook --event CARD_MOVED
python3 scripts/kanban_zone_api.py webhooks verify-signature --payload-file /tmp/payload.json --signature <raw-hex-value-from-X-KanbanZone-Signature-header>
| Subcommand | Description |
|---|---|
list | List all registered webhooks for the active board |
get | Get details of a specific webhook by ObjectId |
create | Register a new webhook endpoint with selected event types |
update | Update a webhook's URL or event subscription |
delete | Delete a webhook registration |
test | Send a test ping to a registered webhook |
verify-signature | Verify an incoming webhook delivery's HMAC signature |
Pull board-level analytics reports for a date range.
python3 scripts/kanban_zone_api.py reports throughput --from-date 2026-01-01 --to-date 2026-04-01
python3 scripts/kanban_zone_api.py reports cycle-time --from-date 2026-01-01
python3 scripts/kanban_zone_api.py reports flow-efficiency
| Subcommand | Description |
|---|---|
throughput | Cards completed per time unit over the date range |
arrival-rate | Cards arriving (created) per time unit over the date range |
cycle-time | Statistical distribution of time from start to completion |
lead-time | Statistical distribution of time from creation to completion |
flow | Cumulative flow diagram data showing column occupancy over time |
flow-efficiency | Ratio of active (value-add) time to total elapsed time |
allocation | Breakdown of card effort by label, owner, or custom field |
abandoned-effort | Cards that were started but deleted or reverted before completion |
Manage card share tokens — named tokens defined in Organization Settings (Settings → Integrations → Card Tokens) that are assigned to cards to control card visibility and external sharing.
python3 scripts/kanban_zone_api.py tokens list
python3 scripts/kanban_zone_api.py tokens assign --card 42 --token-id <token-definition-id>
python3 scripts/kanban_zone_api.py tokens revoke --id TOKEN_ID
| Subcommand | Description |
|---|---|
assign | Create and assign a new API token with an optional label |
revoke | Revoke a token by its ObjectId |
list | List all active tokens for the organization |
Read the caller's identity and the active board/org context.
python3 scripts/kanban_zone_api.py org me
python3 scripts/kanban_zone_api.py org context
| Subcommand | Description |
|---|---|
me | Return the authenticated user's profile and permissions |
context | Return the resolved board/org context used by the current CLI invocation |
Always use --description-file instead of --description for creating or updating card descriptions. This avoids multi-line quoting issues in shell commands.
Always format descriptions as HTML, never Markdown. Kanban Zone renders card descriptions as HTML. Use tags like <h3>, <p>, <ul>/<li>, <strong>, <em>, <a href="...">, and <br> instead of Markdown syntax (###, **, -, [text](url), etc.).
⚠️ NEVER use HTML tables in descriptions. Kanban Zone silently strips <table>, <thead>, <tbody>, <tr>, <th>, and <td> tags — the data disappears from the rendered card without warning. For any tabular data, use a <pre> block with fixed-width ASCII columns instead (this is the HTML equivalent of Markdown triple-backtick code blocks). Example:
<pre>
Field | Value
--------------+------------
Priority | High
Due date | 2026-04-30
Owner | sarah@co.com
</pre>
Do not attempt to "illustrate tables of data with HTML tables" — always use <pre> with fixed-width characters.
Workflow:
/tmp/kanban-zone-desc.txt) using the Write tool.--description-file /tmp/kanban-zone-desc.txt.# CORRECT — use --description-file for all description changes
python3 scripts/kanban_zone_api.py cards update --id 42 --description-file /tmp/kanban-zone-desc.txt
python3 scripts/kanban_zone_api.py cards create --title "New task" --description-file /tmp/kanban-zone-desc.txt
# AVOID — inline --description with multi-line content
python3 scripts/kanban_zone_api.py cards update --id 42 --description "line 1\nline 2\n..."
The --description-file flag reads the entire file content as the description. It overrides --description if both are provided.
--id accepts either a card number (digits only, e.g. 42) or a 24-character hexadecimal ObjectId (e.g. 507f1f77bcf86cd799439011). The skill auto-detects which form is supplied:
cards get lookup if the cache is cold) before calling ObjectId-keyed endpoints.Sub-resource IDs (checklist ID, task ID, comment ID, token ID, webhook ID) are always 24-hex ObjectIds — there are no short numeric aliases for these resources.
To avoid unnecessary API calls when resolving board or column names to IDs, and card numbers to ObjectIds, maintain a local cache file in your memory directory.
Store kanbanzone-cache.json in your persistent memory directory with this structure:
{
"boards": {
"<board-public-id>": {
"name": "Board Name",
"columns": {
"<column-id>": { "name": "Column Name", "state": "In Progress" }
},
"cards": {
"byNumber": { "42": "507f1f77bcf86cd799439011" },
"byObjectId": { "507f1f77bcf86cd799439011": 42 }
}
}
},
"updated": "2026-02-25T12:00:00Z"
}
The byNumber and byObjectId sub-objects form a bidirectional map between card numbers and their ObjectIds. They are populated opportunistically — every cards list or cards get response that returns card data should be used to update both maps, so the cache grows warmer with normal use without ever requiring a dedicated cache-fill step.
kanbanzone-cache.json from your memory directory.Whenever you run boards list, boards get --include-columns, cards list, or cards get for any reason, always update kanbanzone-cache.json with the returned data. This keeps the cache fresh as a side effect of normal operations.
If the user says board, column, or card data is stale, or explicitly asks to refresh the cache, re-fetch from the API and overwrite kanbanzone-cache.json.
"updated" to the current ISO 8601 timestamp.| State | Meaning |
|---|---|
Backlog | Pre-commitment items |
To Do | Committed, ready to start |
Buffer | Queue between stages |
In Progress | Currently being worked on |
Done | Completed |
Archive | Historical items |
None | No state assigned |
All commands output JSON. Run python3 scripts/kanban_zone_api.py --help for full usage.
| Group | Subcommand | Description |
|---|---|---|
boards | list | List all boards with metrics |
boards | get | Get a specific board's details and columns |
boards | columns | List all columns for the active board |
boards | labels | List all labels on the active board |
boards | members | List all members of the active board |
boards | custom-fields | List custom field definitions for the active board |
boards | templates | List card templates on the active board |
cards | list | List cards with optional filters |
cards | get | Get a single card by number or ObjectId |
cards | create | Create one card |
cards | create-bulk | Create multiple cards from a JSON file |
cards | update | Update card fields |
cards | move | Move a card to a column |
cards | delete | Delete a card |
cards | history | Get activity history for a card |
cards | metrics | Get cycle/lead time metrics for a card |
cards | links-add | Add a card-to-card or URL link |
cards | links-remove | Remove a card-to-card or URL link |
cards | search | Search cards across all boards |
cards | wip-check | Check WIP limits across columns |
comments | add | Add a comment to a card |
comments | list | List all comments on a card |
checklists | create | Create a checklist on a card |
checklists | update | Update a checklist's title or tasks |
checklists | delete | Delete a checklist |
checklists | list | List all checklists on a card |
tasks | create | Add a task to a checklist |
tasks | update | Update a task (title, completed, assignee) |
tasks | delete | Delete a task |
tasks | move | Reorder a task within its checklist |
webhooks | list | List all registered webhooks |
webhooks | get | Get a specific webhook by ObjectId |
webhooks | create | Register a new webhook endpoint |
webhooks | update | Update a webhook's URL or event |
webhooks | delete | Delete a webhook |
webhooks | test | Send a test ping to a webhook |
webhooks | verify-signature | Verify an incoming webhook delivery's HMAC signature |
reports | throughput | Cards completed per time unit |
reports | arrival-rate | Cards arriving per time unit |
reports | cycle-time | Distribution of time from start to completion |
reports | lead-time | Distribution of time from creation to completion |
reports | flow | Cumulative flow diagram data |
reports | flow-efficiency | Ratio of active time to total elapsed time |
reports | allocation | Effort breakdown by label, owner, or custom field |
reports | abandoned-effort | Cards started but abandoned before completion |
tokens | assign | Create and assign a new API token |
tokens | revoke | Revoke a token |
tokens | list | List all active tokens |
org | me | Return the authenticated user's profile |
org | context | Return the resolved board/org context |
If you previously used flat commands (create-card, update-card, move-card, etc.), they still work as hidden aliases and will not appear in --help output — see references/migration-from-v2.md for the full mapping. New code should use the grouped commands documented above.
See references/api-reference.md for complete endpoint documentation, data models, and response schemas.