Obsidian Kanban

Obsidian Kanban Skill

Create and edit markdown-backed Kanban boards for the obsidian-kanban plugin (v2.0.51). Boards are plain .md files that Obsidian renders as interactive Kanban boards.

Where boards live

This skill is drop-in portable: copy the whole obsidian-kanban/ folder into any project's .claude/skills/ and it works with no edits. Nothing below hardcodes a project path.

All boards, issue folders, and context files are created inside the current project, in a top-level kanban/ directory:

<project_root>/kanban/

Resolve <project_root> as the directory containing .claude/ (equivalently, the git repository root). Never write boards outside the project, and never into an Obsidian vault elsewhere on the machine — a project's boards travel with the repo.

Each board gets its own folder named after the board, and everything for that feature lives inside it:

<project_root>/kanban/<board_name>/<board_name>.md
<project_root>/kanban/<board_name>/<board_name>_issues/*.md
<project_root>/kanban/<board_name>/<board_name>_context.md

Create kanban/ and the per-board folder if they do not exist. Do not write boards loose in kanban/.

kanban/README.md is the index across all boards — see "Board index (README)" below.

If a project has pre-existing boards sitting loose in kanban/, leave them where they are unless asked to move them; when you do move one, move the board, its _issues/ folder and its _context.md together into kanban/<board_name>/.

The read-only reference material (the worked example and the plugin guides) ships inside this skill folder and is referenced by paths relative to the skill directory. Read it there; write new boards into the project's kanban/ directory.

First run in a project: bootstrap

Every time this skill is invoked, check these four things in the project:

1. <project_root>/kanban/ exists
2. <project_root>/kanban/README.md exists (the board index)
3. <project_root>/CLAUDE.md has a heading mentioning Kanban
4. <project_root>/kanban/.obsidian/ exists (vault config)

If any is missing, read SETUP.md in this skill directory and follow it for the missing pieces before creating or editing any board. If all four exist, skip SETUP.md entirely and proceed with the rules below.

Item 3 matters most: without a Kanban section in CLAUDE.md, future sessions will not know this skill applies and will improvise a format. If a section is already present, leave it alone — do not reword it.

Board File Structure

Every board file must follow this exact format:

---
kanban-plugin: board
---

## Lane Title

- [ ] Card one
- [ ] Card two
- [x] Completed card

## Another Lane (3)

- [ ] Card with a [[Link to note]]
- [ ] Card with date @{2024-01-15}

## Done

**Complete**
- [x] Finished task


%% kanban:settings

{"kanban-plugin":"board"}

%%

Key structural rules

1. Frontmatter must contain kanban-plugin: board — this is how the plugin identifies a file as a kanban board
2. Lanes are ## headings (H2). Each lane is a column on the board
3. Cards are list items with checkboxes: - [ ] (incomplete) or - [x] (complete)
4. WIP limits are set in parentheses after the lane title: ## In Progress (5) limits that lane to 5 cards. The counter turns bold when exceeded
5. Complete lane — add **Complete** on its own line before cards in a lane to mark it as the "done" lane. Cards moved here get auto-checked
6. Archive — archived cards appear at the bottom of the file (only visible in markdown mode). Controlled by the "Maximum number of archived cards" setting (-1 for unlimited)
7. Board settings block goes at the very end of the file wrapped in %% kanban:settings ... %%

Card Content: Multi-line Cards and Issue Links

Cards support multi-line content. Continuation lines after the - [ ] Title line must be indented with one TAB character. The plugin renders all indented lines as the card body.

Preferred pattern: title + summary + link to issue file

For boards tracking implementation tasks, always use this pattern to keep the board file small while providing full detail:

1. Card title: short descriptive name
2. One-line summary: what this task does (tab-indented)
3. Link to issue file: [[<board_name>_issues/<issue>]] with full implementation details (tab-indented)

Create a separate .md file per card in a <board_name>_issues/ folder next to the board. These issue files are regular Obsidian notes (no kanban frontmatter) and can contain full implementation plans, code snippets, SQL, file lists, etc.

Naming convention

Board folders, board files, issue folders and context files use snake_case, and all four share the same <board_name> stem:

Issue files use kebab-case after the number — this is the one deliberate exception to snake_case, matching the worked example.

Worked example

A complete example ships inside this skill folder — read these files before creating a new board (they are read-only references; write your new board into <project_root>/kanban/):

• Board: example_board.md
• Context file: example_board_context.md
• Issue files:
  • example_board_issues/1.1-database-tables.md
  • example_board_issues/1.2-api-endpoints.md
  • example_board_issues/1.3-login-page.md

File structure

<project_root>/kanban/
├── README.md                         ← index across all boards
└── <board_name>/                     ← one folder per board
    ├── <board_name>.md               ← kanban board (compact cards with summaries + links)
    ├── <board_name>_issues/
    │   ├── 1.1-database-tables.md    ← full implementation spec
    │   ├── 1.2-api-endpoints.md
    │   └── 1.3-login-page.md
    └── <board_name>_context.md       ← persistent memory / feature documentation

The _issues suffix ties the folder to its board. The _context.md file preserves working memory across sessions.

Card links stay relative to the board file ([[<board_name>_issues/<issue>]]), since the issues folder is still a sibling of the board file inside the board folder.

Context file (feature memory)

Every board has a companion <board_name>_context.md file in the same folder. This file is persistent memory — it preserves architecture decisions, key files, implementation patterns, and current state across Claude Code sessions. It also serves as long-term feature documentation.

At session start: Read the context file before doing any work. It tells you everything about the feature.

After completing any task: Update the context file — add decisions, files, patterns, update task history and current state.

When creating a new board: Also create its _context.md file. Use example_board_context.md (next to this skill file) as the template. Fill in the Feature Overview; other sections populate as work progresses.

Context file sections:

• Feature Overview — what this feature does, why, where it lives
• Architecture & Decisions — key decisions with rationale
• Key Files & Locations — files created/modified, grouped logically
• Implementation Notes — patterns, conventions, gotchas
• Task History — table of tasks with summary and status
• Current State — what's working, what's pending, known issues

Board index (README)

kanban/README.md is a single-page overview of every board, so a session can get context without opening each board. It holds, per board: a link to the board file, a one-word status, a done / total card count, the next actionable card, and 3-5 lines on what the feature is and where it stands. Plus a "Loose files" section for anything in kanban/ that is not a board.

Keep it short. It is an index, not documentation: the whole file should stay readable in one screen or two. Detail belongs in <board_name>_context.md, never here. Do not copy decisions, file lists or task tables into it.

Update kanban/README.md whenever:

• a board is created, renamed, finished or abandoned (add/remove/restate its row and blurb)
• cards are completed or moved, so the done / total count or the "Next up" column changes
• a board's overall status changes (planned -> in progress -> shipped)

Refresh the _Last updated:_ YYYY-MM-DD line on every edit. If the README does not exist yet in a project, create it via SETUP.md (Step 3) as part of bootstrap.

Working a board: picking up and completing tasks

At session start, before doing any work on a feature that has a board:

1. Read kanban/README.md for the cross-board picture
2. Read the board file to see current task states
3. Read <board_name>_context.md - this tells you everything about the feature: architecture, files, patterns, current state
4. Read issue files only for tasks you are actively working on

To pick up a task: move the card's - [ ] line (and all its TAB-indented content) from its current lane (e.g. ## To Do) into the ## In Progress lane.

To mark a task complete: change - [ ] to - [x] and move the card into the ## Done lane (the one with **Complete** on the line after the heading).

Then update the linked issue file: if the card links to an issue spec (e.g. [[<board_name>_issues/1.1-task-spec]]), open it and update its Status field to the new state (In Progress, Done).

Then update the context file:

• Add any new architecture decisions to "Architecture & Decisions"
• Add or update entries in "Key Files & Locations"
• Add any new patterns or gotchas to "Implementation Notes"
• Update the task's row in "Task History"
• Update "Current State" to reflect what is working and what is next

Then update kanban/README.md if the board's counts, "Next up" or status changed.

When to use each approach

Multi-line card syntax reference

- [ ] Card title goes here
	Second line (indented with ONE TAB)
	Third line with **markdown** and `code`
	[[Link to detailed spec]]

Important: Use actual TAB characters (\t), not spaces. The plugin serializes multi-line cards using tabs (or 4 spaces if the vault is configured for spaces, but tabs are the default).

Cards

Dates and times on cards

• Date trigger: typing @ (default) in a card opens the date picker. Dates are formatted using Moment.js format strings (default: YYYY-MM-DD)
• Time trigger: typing @@ (default) opens the time picker. Only available on cards that already have a date
• Dates can also be added via right-click > "Add a date"

Images in cards

Images are embedded using standard Obsidian syntax:

- [ ] Card with image ![[photo.png]]

When using images in linked note frontmatter, they must be wrapped in quotes (YAML quirk):

---
delivery-notes: "![[LinkToImage.png]]"
---

Inline Dataview fields do NOT require quotes:

delivery-notes:: ![[LinkToImage.png]]

Creating notes from cards

Right-click a card > "New note from card" creates a note using the configured Note template in the configured Note folder. The card then links to the new note.

Linked page metadata

Cards linking to notes can display that note's frontmatter or Dataview inline fields below the card. Configure which metadata keys to show in board settings under "Linked Page Metadata". Toggle "Field contains markdown" for fields with markdown content.

Gotcha: Links and image embeds in frontmatter must be wrapped in quotes to display correctly as linked metadata.

Settings

Settings can be configured globally (Settings > Kanban) or per-board (board header buttons or "More options" menu). Per-board settings override global ones.

Key settings

Critical Rules

0. Run the bootstrap check on every invocation — kanban/, kanban/README.md, the Kanban section in CLAUDE.md, kanban/.obsidian/; if any is missing, follow SETUP.md before touching any board (see "First run in a project" above)
1. Always include kanban-plugin: board in frontmatter — without it the file won't be recognized as a board
2. Use ## (H2) for lanes only — other heading levels are not recognized as lanes
3. Use - [ ] / - [x] for cards — plain list items without checkboxes won't render as cards
4. Keep the settings block at the end — the %% kanban:settings ... %% block must be the last thing in the file
5. Quote links and embeds in YAML frontmatter — "![[image.png]]" and "[[note]]" need quotes in frontmatter fields
6. WIP limits use parentheses in lane title — ## Lane Name (N) where N is the limit number
7. Every board gets its own folder — create the board, its _issues/ folder and its _context.md under <project_root>/kanban/<board_name>/, never loose in kanban/ and never outside the project
8. Use TAB-indented lines for multi-line card content — continuation lines must start with a TAB character
9. Keep board files small — for detailed tasks, link to spec files instead of putting everything inline
10. Always create a context file when creating a new board — <board_name>_context.md alongside the board file, using example_board_context.md as the template
11. Update the context file after completing any task — add decisions, files, patterns; update task history and current state
12. Keep kanban/README.md current and short - refresh the board's row (status, done / total, next up) whenever it changes, and keep the whole file to a screen or two

Common Mistakes to Avoid

• Forgetting the kanban-plugin: board frontmatter — file opens as a normal note
• Using # or ### instead of ## for lane headings
• Using - without [ ] for cards — they won't be interactive
• Placing content after the %% kanban:settings %% block
• Unquoted embeds/links in YAML frontmatter fields
• Using spaces instead of TAB for multi-line card indentation
• Putting full implementation details inline on cards instead of linking to spec files
• Writing the board loose in kanban/ instead of inside its own kanban/<board_name>/ folder
• Hardcoding an absolute path from another project instead of resolving <project_root>/kanban/
• Creating boards in a project whose CLAUDE.md has no Kanban section — the next session will not know the skill applies and will invent its own format
• Skipping the bootstrap check, or copying the example board and kanban-guides/ into the project (they stay in the skill folder and are read from there)
• Leaving kanban/README.md stale after finishing or adding cards
• Letting kanban/README.md grow into a second context file instead of staying a one-screen index
• Naming the board folder differently from the board file (both must be <board_name>)
• Forgetting to create a _context.md file when creating a new board
• Forgetting to update the context file after completing a task
• Not reading the context file at session start — this is the feature's memory

Reference Guides

Full plugin documentation lives in kanban-guides/ next to this skill file (paths below are relative to the skill directory). Consult these for detailed information:

Overview

• kanban-guides/Obsidian Kanban Plugin.md — Plugin overview and links

How-to Guides

• kanban-guides/How do I/Create a Kanban board.md — Creating boards (UI methods)
• kanban-guides/How do I/Add a date to a card.md — Date picker usage
• kanban-guides/How do I/Add a time to a card.md — Time picker usage
• kanban-guides/How do I/Add an image to a card.md — Embedding images and metadata images
• kanban-guides/How do I/Create notes from cards.md — Creating linked notes from cards
• kanban-guides/How do I/Install the plugin.md — Installation instructions
• kanban-guides/How do I/Search a Kanban board.md — Searching with Ctrl/Cmd+F
• kanban-guides/How do I/Set a WIP Limit.md — Work-in-progress limits on lanes
• kanban-guides/How do I/View a Kanban's archive.md — Viewing archived cards in markdown mode

FAQs

• kanban-guides/FAQs/Frontmatter limitations & gotchas.md — YAML quoting rules for links/images

Settings Reference

• kanban-guides/Settings/Local vs. global settings.md — Per-board vs global settings
• kanban-guides/Settings/Date trigger.md — Date picker trigger character
• kanban-guides/Settings/Time trigger.md — Time picker trigger character
• kanban-guides/Settings/Date format.md — Moment.js date output format
• kanban-guides/Settings/Date display format.md — How dates appear on cards
• kanban-guides/Settings/Time format.md — Time output format
• kanban-guides/Settings/Lane width.md — Column width setting
• kanban-guides/Settings/Note folder.md — Folder for notes created from cards
• kanban-guides/Settings/Note template.md — Template for new notes from cards
• kanban-guides/Settings/Linked page metadata.md — Displaying note metadata on cards
• kanban-guides/Settings/Display card checkbox.md — Toggle card checkboxes
• kanban-guides/Settings/Prepend append new cards.md — New card insertion position
• kanban-guides/Settings/Board header buttons.md — Board toolbar buttons
• kanban-guides/Settings/Maximum number of archived cards.md — Archive size limit
• kanban-guides/Settings/Show relative date.md — Relative vs absolute dates
• kanban-guides/Settings/Hide card display dates.md — Hide date badges on cards
• kanban-guides/Settings/Hide card display tags.md — Hide tag badges on cards
• kanban-guides/Settings/Hide dates in card titles.md — Hide date text in titles
• kanban-guides/Settings/Hide tags in card titles.md — Hide tag text in titles
• kanban-guides/Settings/Link dates to daily notes.md — Link date badges to daily notes
• kanban-guides/Settings/New line trigger.md — Key for new lines in cards
• kanban-guides/Settings/Add date and time to archived cards.md — Timestamp archived cards
• kanban-guides/Settings/Archive date time format.md — Archive timestamp format
• kanban-guides/Settings/Archive date time position.md — Where archive timestamp appears
• kanban-guides/Settings/Archive date time separator.md — Archive timestamp separator