# Obsidian Kanban

> Create and edit Obsidian Kanban board markdown files correctly. Use when asked to create, modify, or work with Kanban boards, task boards, or feature planning boards in any project.

- Skill: `hristovcodes/obsidian-kanban` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add hristovcodes/obsidian-kanban`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hristovcodes/obsidian-kanban/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: HristovCodes (https://skillmd.com/u/hristovcodes)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hristovcodes/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:

```markdown
---
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:

| Item | Pattern | Example |
|---|---|---|
| Board folder | `<board_name>/` | `web_rewrite/` |
| Board file | `<board_name>.md` | `web_rewrite.md` |
| Issues folder | `<board_name>_issues/` | `web_rewrite_issues/` |
| Context file | `<board_name>_context.md` | `web_rewrite_context.md` |
| Issue file | `{number}-{kebab-case-title}.md` | `1.1-database-schema.md` |

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

| Scenario | Card format |
|----------|-------------|
| Simple task (1-2 lines of context) | Title + tab-indented summary, no spec file |
| Implementation task with details | Title + one-line summary + `[[spec link]]` |
| Completed/archived cards | Title only (details no longer needed on the card) |

### Multi-line card syntax reference

```markdown
- [ ] 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:

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

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

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

Inline Dataview fields do NOT require quotes:

```markdown
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

| Setting | Default | Purpose |
|---------|---------|---------|
| Date trigger | `@` | Character that opens date picker |
| Time trigger | `@@` | Character that opens time picker |
| Date format | `YYYY-MM-DD` | Moment.js format for dates |
| Lane width | (plugin default) | Width of board columns |
| Note folder | vault default | Where "New note from card" saves files |
| Note template | none | Template for notes created from cards |
| Prepend/append new cards | append | Where new cards are inserted in a lane |
| Display card checkbox | on | Show/hide checkboxes on cards |
| Max archived cards | -1 | Limit archive size (-1 = unlimited) |

---

## 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