# Tasknotes

> Manage tasks in an Obsidian TaskNotes vault. Use for creating, reading, updating, or completing tasks; checking what is open or in progress; adding items to a list; marking tasks done or in progress; updating task status or priority; investigating why a task is missing from a view or board; troubleshooting TaskNotes MCP or API connection issues; setting up or configuring TaskNotes; or running a s…

- **Type:** Skill
- **Install:** `agentstack add skill-vanillaflava-tasknotes-skill-tasknotes`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vanillaflava](https://agentstack.voostack.com/s/vanillaflava)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vanillaflava](https://github.com/vanillaflava)
- **Source:** https://github.com/vanillaflava/tasknotes-skill/tree/master/tasknotes

## Install

```sh
agentstack add skill-vanillaflava-tasknotes-skill-tasknotes
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# TaskNotes

Multi-modal task management for Obsidian TaskNotes vaults. The skill probes the environment first and routes to the best available access method.

---

## Step 0 - Environment probe

**Run before any operation.** Determines which path to take.

**Bundled help:** This skill includes `references/tasknotes-help.md` with step-by-step setup instructions, full API endpoint reference, and troubleshooting for all failure modes. Read it yourself when connection or setup issues arise, and share the relevant sections with the user to guide them through fixes.

### 1. MCP available?

Run `tool_search("tasknotes")`. If `tasknotes:` tools load successfully, the MCP server is live.

### 2. HTTP API available?

Attempt `web_fetch("http://localhost:8080/api/health")`. If the response contains `{"status":"ok",...}`, the HTTP API is live on port 8080.

If the request fails (connection refused or timeout), ask the user:
- *"What port is your TaskNotes HTTP API configured on? Check Settings → TaskNotes → Integrations → HTTP API."*
- *"Are both the HTTP API toggle and the MCP Server toggle enabled in those settings?"*

Try the user-supplied port before giving up. If still unreachable, HTTP API is unavailable.

### 3. Filesystem available?

Check whether any loaded tool can read and write `.md` files. Do not assume a specific tool name - any filesystem capability qualifies.

### Routing

| MCP | HTTP API | Filesystem | Route |
|---|---|---|---|
| Yes | - | - | MCP for all ops including body reads (fixed in v4.8.0) |
| No | Yes | - | HTTP API for all frontmatter and body ops |
| No | No | Yes | Filesystem path - all workflows below |
| No | No | No | Inform user what is missing; link `references/tasknotes-help.md` for setup |

### What works on which surface

| Operation | MCP | HTTP API | Filesystem |
|---|---|---|---|
| Create task | `tasknotes_create_task` | `POST /api/tasks` | Workflow 1 |
| Update frontmatter | `tasknotes_update_task` | `PUT /api/tasks/:id` | Workflow 3 |
| Mark done | `tasknotes_update_task` | `PUT /api/tasks/:id` | Workflow 4 |
| Query / filter tasks | `tasknotes_query_tasks` | `POST /api/tasks/query` | Workflow 5 |
| Read task frontmatter | `tasknotes_get_task` | `GET /api/tasks/:id` | Read .md file |
| Read task body / checklist | `tasknotes_get_task` (details field) | `GET /api/tasks/:id` | Read .md file |
| Write task body | `tasknotes_update_task` (details field) | `PUT /api/tasks/:id` | Write .md file |
| Complete recurring instance | `tasknotes_complete_recurring_instance` | `POST /api/tasks/:id/complete-instance` | Not supported (GUI only) |
| Schema diagnostic | ✗ → Workflow 9 | ✗ → Workflow 9 | Workflow 9 |
| Time tracking | `tasknotes_*_time_tracking` | `/api/tasks/:id/time/*` | Manual (complex) |
| Pomodoro | `tasknotes_*_pomodoro` | `/api/pomodoro/*` | Not supported |
| Works when Obsidian closed | ✗ | ✗ | ✓ |

---

## Path: MCP

The `tasknotes:` MCP tools are mostly self-describing - call them directly. Two things agents reliably get wrong are NOT obvious from the tool list and are pinned below: the `query_tasks` argument shape, and per-instance recurring completion.

**Key tools:**
- `tasknotes_create_task` - create a task with frontmatter fields
- `tasknotes_update_task` - update frontmatter fields (including `status`, `priority`, `projects`, `details`)
- `tasknotes_query_tasks` - filter tasks with AND/OR conditions (arg shape below)
- `tasknotes_list_tasks` - unfiltered list with pagination (`limit`/`offset`); prefer `query_tasks` when filtering
- `tasknotes_get_task` - read a single task (frontmatter + `details` body) by file path
- `tasknotes_toggle_status` - cycle status through the configured workflow
- `tasknotes_get_filter_options` - list available statuses, priorities, projects, contexts
- `tasknotes_complete_recurring_instance` / `tasknotes_materialize_occurrence` - recurring tasks (see below)

In deferred-tools environments, load a tool's schema before guessing its args: `tool_search("select:tasknotes_query_tasks")`.

**Querying with `tasknotes_query_tasks` - flattened arg shape.** The MCP tool takes the filter group **flattened to top-level arguments**, NOT the wrapped `{"type":"group", ...}` body documented for the HTTP API in `references/tasknotes-help.md`. Passing the HTTP wrapper fails with a `conjunction`/`children` validation error.

- Required top-level: `conjunction` (`"and"` | `"or"`) and `children` (array). Optional: `sortKey`, `sortDirection` (`"asc"` | `"desc"`), `groupKey`.
- Each child is a condition `{ "type": "condition", "id": "", "property": "", "operator": "", "value":  }` - the key is `property`, NOT `field`. Nested groups are allowed as children.
- Common operators: `is`, `is-not`, `contains`, `does-not-contain`, `is-empty`, `is-not-empty` (hyphenated - `is-not`, not `is not`). Full list in `references/tasknotes-help.md`.

```json
{
  "conjunction": "and",
  "children": [
    { "type": "condition", "id": "c1", "property": "projects", "operator": "contains", "value": "[[Project - Home]]" },
    { "type": "condition", "id": "c2", "property": "status", "operator": "is-not", "value": "done" }
  ],
  "sortKey": "status",
  "sortDirection": "asc"
}
```

`tasknotes_get_task` and `tasknotes_update_task` take **`id`** (the vault-relative file path), not `taskId`.

**Recurring tasks (MCP).** To complete a single occurrence without closing the series, call `tasknotes_complete_recurring_instance` (`id` = task file path; optional `date` = `YYYY-MM-DD`, defaults to today). To create a concrete occurrence note for one date, call `tasknotes_materialize_occurrence` (`id`, `date`). Never set `status: done` on the recurring task itself - that closes the whole series. See Workflow 10.

**Conventions that apply regardless of path:**
- `projects:` must be a wikilink array - `["[[Domain - Home]]"]` not a plain string; plain strings are silently broken and the task will not appear on any Kanban
- Status cycle: `open` → `in-progress` → `done`
- Always include `tags: ["task"]` - without it the task is invisible to all TaskNotes views
- Task paths in MCP calls are vault-relative (e.g. `Agent Access/TaskNotes/Tasks/filename.md`)

**Schema diagnostic:** Not available via MCP. If the user asks for a schema health check, switch to the Filesystem path → Workflow 9.

---

## Path: HTTP API

Use when the HTTP API is available but MCP is not.

**Base URL:** `http://localhost:{port}/api` (default port: 8080)

**Key endpoints:**

| Method | Endpoint | Use |
|---|---|---|
| GET | `/api/health` | Verify server is running |
| GET | `/api/tasks` | List tasks with pagination |
| POST | `/api/tasks` | Create a task |
| GET | `/api/tasks/{id}` | Read a task's frontmatter by path |
| PUT | `/api/tasks/{id}` | Update task fields |
| POST | `/api/tasks/query` | Filter tasks with AND/OR logic |
| POST | `/api/tasks/{id}/toggle-status` | Cycle task status |
| GET | `/api/filter-options` | List valid statuses, priorities, projects |

The `{id}` parameter is the URL-encoded vault-relative file path (e.g. `Agent%20Access%2FTaskNotes%2FTasks%2Ftask.md`).

**Schema diagnostic:** Not available via HTTP API. Switch to Filesystem path → Workflow 9.

**Full endpoint reference:** `references/tasknotes-help.md`

---

## Path: Filesystem

Used when MCP and HTTP API are both unavailable, or when the filesystem is the only available surface.

All workflows below operate by reading and writing `.md` task files directly.

**Note - direct edits while Obsidian is running (plugin v4.9.0+):** the plugin now detects direct file edits to lifecycle fields (`status`, `completedDate`, scheduled/due dates) and runs the matching side-effects - Google Calendar sync and auto-archive. Previously these were silent. This only applies when Obsidian is open while you edit files directly; with Obsidian closed there are no side-effects.

---

### Config Discovery (filesystem path)

**Read `tasknotes-config.md` before any filesystem operation.** It carries the task folder path, project routing table, and field defaults.

The skill bundles a default `tasknotes-config.md` at `references/tasknotes-config.md` for first-time deployment.

1. **Scope check - MANDATORY STOP:** If filesystem scope is a bare drive root (`C:\`, `/`) or user home - stop. Ask the user for their TaskNotes folder path.

2. **Search for `tasknotes-config.md`** recursively within scope (first-match, max 5 levels).
   - **Found and parses cleanly:** extract `tasks_folder`, `default_status`, `default_priority`, `default_tags`, `projects`, `contexts`. Proceed.
   - **Found but malformed:** stop. Report exactly what is malformed. Offer: (a) user fixes and re-invokes, or (b) replace with bundled default (warn this overwrites customisations).
   - **Not found:** go to step 3.

3. **No config found:**
   - Look for an existing `TaskNotes/Tasks` folder as a placement hint.
   - **Found:** *"I found TaskNotes/Tasks at [path]. Deploy `tasknotes-config.md` alongside it at [parent]?"* Wait for confirmation.
   - **Not found:** ask the user for a folder path; deploy config and create `TaskNotes/Tasks/` on confirmation.
   - Remind the user to set Settings → TaskNotes → General → Task folder to match.

**Resolving `tasks_folder`:** Join the value with the config file's directory. If it resolves outside (e.g. uses `../`), stop and ask the user to confirm.

### Data Model

Each task is a `.md` file in `tasks_folder`. Filename: `YYYY-MM-DD-slug.md` (title lowercased, spaces as hyphens).

**Canonical frontmatter field order:**

```yaml
---
title: Task title here
status: open
priority: normal
scheduled: YYYY-MM-DD
completedDate:
projects:
  - "[[Project Note Title]]"
dateCreated: YYYY-MM-DD
dateModified: YYYY-MM-DD
tags:
  - task
contexts:
  - "@context-label"
---
```

Use `default_status`, `default_priority`, and `default_tags` from config. Field order matters for Obsidian Properties rendering.

**Required:** `title`, `status`, `priority`, `dateCreated`, `dateModified`, `tags` (must include `task`).

**Include when relevant:** `scheduled`, `projects` (wikilink only), `contexts`.

**Leave empty until set:** `completedDate`.

**Add only as needed:** `due: YYYY-MM-DD`, `timeEstimate: 30` (minutes).

**Recurring tasks:**

```yaml
recurrence: "DTSTART:YYYYMMDD;FREQ=WEEKLY;BYDAY=MO"
recurrence_anchor: scheduled
scheduled: YYYY-MM-DD
```

`recurrence_anchor`: `scheduled` (from scheduled date) or `completion` (from completion date).

**Dependencies:**

```yaml
blockedBy:
  - uid: "relative/path/to/blocking-task.md"
    reltype: "FINISHTOSTART"
```

**Date format:** `YYYY-MM-DD` for all date fields. No timestamps.

---

### Task Body

Write enough context that any agent or human can resume the task without the originating chat. Include what needs doing and why, acceptance criteria as inline checkboxes, constraints, and links to related notes.

**Suggested structure** (use what applies - simple tasks need only one line):

```markdown
## Context
What triggered this task; which session or conversation.

## Problem or intent
What is broken, missing, or unclear.

## Approach
Shape of the answer. Open questions explicitly listed.

## Acceptance criteria
- [ ] Binary checkable item
- [ ] Another checkable item
```

---

### Organisation: Projects, Contexts, Tags

| Field | Purpose | Drives Relationships Widget | Notes |
|---|---|---|---|
| `projects:` | Links task to a vault note; that note shows a live Kanban of all tasks pointing to it | Yes | Must be a wikilink. Plain strings are silently broken. |
| `contexts:` | Semantic sub-domain label for filtering within a project's views | No | Free-form string. Multiple per task. |
| `tags:` | Identifies the file as a task to the plugin | No | `task` is required. Without it the file is invisible to all views. |

The `projects:` map in `tasknotes-config.md` is the lookup table. Register a project note there before creating tasks for it.

---

### Relationships Widget

The Relationships Widget renders on any vault note. The **Subtasks (Kanban)** tab shows all tasks whose `projects:` field contains a wikilink to that note, grouped by status. Fully automatic - no per-note configuration.

Settings: Settings → TaskNotes → Appearance → UI Elements → Relationships Widget (on/off and position).

---

### Project Routing Discipline

On every task creation:

1. Look up the project note in `tasknotes-config.md`
2. Verify the project note exists in the vault; do not link to a non-existent note
3. If the note does not exist: stop, inform the user, offer to create it first
4. If no matching entry: show the known project list, ask which applies or whether a new entry is needed
5. Never write `projects:` as a plain string - always a wikilink

**Adding a new project:** confirm the note name, create a stub if needed, add to `tasknotes-config.md`, then create the task.

**No projects configured:** tasks can be created without `projects:`. Inform the user the task will not appear in any project view or trigger the Relationships Widget.

---

### Subtask Model

**Tier 1 - Inline checklists:** steps or acceptance criteria within a single task file.

**Tier 2 - Child task files:** when a subtask warrants its own status tracking, create it as a normal task and set its `projects:` to the parent task's wikilink. The Relationships Widget surfaces it in the parent's Subtasks tab.

Rule: inline checklists for steps within one task; separate files for work with independent status.

---

### Quick Reference

| I want to... | Workflow | Key step |
|---|---|---|
| Create a task | 1 | Verify project note exists before linking |
| Read a task | 2 | Read the file; do not rely on memory |
| Update a task | 3 | Read first, surgical edit, update `dateModified` |
| Mark done | 4 | `status: done` + `completedDate: YYYY-MM-DD` |
| List tasks for a project | 5 | Search by project wikilink |
| Fix a GUI-created task | 6 | Adopt workflow |
| Clean up done tasks | 8 | Housekeeping - guide user to plugin archive |
| Schema diagnostic | 9 | Scan for structural problems |
| Recurring task | 10 | Write RRULE; never mark done via agent |

### Workflows

#### 1. Create a task

1. Read `tasknotes-config.md`
2. Identify domain; look up project note and context
3. Verify project note exists (see Project Routing Discipline)
4. Generate filename: `YYYY-MM-DD-.md`. Append `-2`, `-3` if file exists.
5. Get today's date for `dateCreated` and `dateModified`
6. Write file with required frontmatter + relevant optional fields + body
7. Confirm filename and key fields to the user

**GUI creation note:** Agent creation is the reliable path for correct project assignment. If the user creates tasks via the plugin GUI, the task may be missing `projects:` or `tags:` - use Workflow 6 to repair.

#### 2. Find / read tasks

Search `tasks_folder` for files by project wikilink, status, or keyword. Always read each candidate file in full before acting on it.

When using MCP or HTTP API, task body content (checklists, notes) is returned in the `details` field - no separate file read needed (fixed in v4.8.0).

#### 3. Update a task

Always read the file first. Use surgical edits. Always update `dateModified` alongside any other change.

#### 4. Complete a task

1. Read the task file
2. Set `status: done`
3. Add `completedDate: YYYY-MM-DD`
4. Update `dateModified`

Never delete task files. Done tasks remain on disk; TaskNotes views filter by status.

#### 5. List tasks for a domain

1. Read `tasknotes-config.md` for the project wikilink
2. Search `tasks_folder` for files containing that wikilink. Direct files only; exclude `Archive/`. Paginate to completion - do not stop early.
3. Read frontmatter: title, status, priority, due
4. Present: `in-progress` first, then `open`; skip `done`

**Domain signal:** The project wikilink is the only reliable cross-task domain signal. `contexts:` is a secondary filter, not a substitute.

**Health check:** If more than 150 files and done/archived account for a third or more, flag it

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vanillaflava](https://github.com/vanillaflava)
- **Source:** [vanillaflava/tasknotes-skill](https://github.com/vanillaflava/tasknotes-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vanillaflava-tasknotes-skill-tasknotes
- Seller: https://agentstack.voostack.com/s/vanillaflava
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.