Tasknotes

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.

{
  "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.

1. 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.

1. 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:

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

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:

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):

## 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
• Source: vanillaflava/tasknotes-skill
• License: MIT

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