Kanban AI Skill
Manage a Kanban board as Markdown files in the kanban/ directory. Each file is a card. The board state is derived by reading all card files and grouping by status.
Narrative Record (Required)
Treat cards as durable source material for future review. Do not rewrite or delete prior narrative content unless explicitly asked. When updating a card, append a brief narrative note to a ## Narrative section at the end of the file. Focus on reasons, discoveries, insights, and decisions. Avoid transactional status-change logs unless they matter to the story. Use ISO dates.
Narrative entry format:
## Narrative
- 2026-02-05: Discovered the auth flow must support device-based MFA; shifted approach to use WebAuthn. (by @assistant)If the card has no ## Narrative section, add it. If a change is minor (e.g., typo), skip the narrative note unless it carries meaningful insight.
When a card is moved to done, add enough narrative detail that a future reader can understand the card’s story and outcome. Keep it coherent and complete without being verbose.
Card Fields
Each card's frontmatter supports the following fields:
id— Unique numeric identifier. Scan existing cards inkanban/(includingkanban/archived/), take max + 1. Start at1if empty. Reference cards by this number.status— Column:backlog,todo,doing,done, orarchive.priority—HighorNormal. Defaults toNormalif omitted.blocked_by— List of card IDs that must bedonebefore this card moves todoing. Example:[3, 7]. Omit or set to[]if unblocked.assignee— (optional) Owner of the card.due_date— (optional) Target date.tags— (optional) List of labels.
Creating a Card
Create a new .md file in kanban/. Filename should be kebab-case.
If possible, include a Job Story using the structure “When [situation], I want to [motivation], so I can [expected outcome].” Do not force it; only add when it fits. If you add one, share it with the requester to confirm.
---
id: 1
status: todo
priority: Normal
blocked_by: []
assignee: "@claude"
due_date: 2026-02-28
tags: [auth, backend]
---
# Implement User Authentication
Set up user authentication using JWTs.
## Acceptance Criteria
- Users can register for a new account.
- Users can log in with their credentials.
- Authenticated users receive a JWT.Moving a Card
Update the status field in frontmatter.
Before moving to doing, verify all IDs in blocked_by have status done. If any are not done, the card stays put.
Cards with status: done may be moved into kanban/archived/ to keep the main board tidy. This is a file-location move only; the card should remain a normal card with status: done unless explicitly changed. If kanban/archived/ does not exist, create it under the active cards folder (kanban/) before moving the card.
Viewing the Board
Helper scripts are bundled in the scripts/ directory alongside this skill file. To locate them, find this skill's directory within the installed plugin (e.g., using glob for **/kanban-ai/scripts/view_board.sh).
Run the board view script:
bash <SCRIPTS_DIR>/view_board.sh kanban/Outputs cards grouped by status column, with priority and blocked_by flags inline.
Searching and Filtering
Search by Tag
bash <SCRIPTS_DIR>/search_by_tag.sh kanban/ <tag>Output: Cards with that tag (ID, status, title)
Search Content
bash <SCRIPTS_DIR>/search_content.sh kanban/ "<search term>"Output: Cards matching the search term with context lines
Show Blocked Cards
bash <SCRIPTS_DIR>/show_blocked.sh kanban/Output: Cards with non-empty blocked_by field and what's blocking them
List All Tags
bash <SCRIPTS_DIR>/list_tags.sh kanban/Output: All tags sorted by usage count (most used first)
List All Cards
bash <SCRIPTS_DIR>/list_all_cards.sh kanban/Output: All cards in pipe-delimited format (id|status|blocked_by|title), sorted by ID. Useful for parsing, debugging dependencies, or exporting board state.
Note: <SCRIPTS_DIR> refers to the scripts/ directory next to this SKILL.md file. All scripts take the kanban directory as the first argument. If omitted, they default to the current directory.