Tasknotes

TaskNotes Skill

This skill enables you to work with tasks managed by the TaskNotes plugin. Each task is a Markdown file with YAML frontmatter stored in a configurable folder (default: TaskNotes/Tasks/).

Use the search_notes, read_content, get_properties, and manage_notes tools to read and write tasks.

Scripting the TaskNotes API (advanced)

Because this skill is enabled and the TaskNotes plugin exposes a public API, you likely also have an exec_tasknotes tool (check your available tools) that runs JavaScript against the TaskNotes plugin's api object on the main thread. This is more reliable than hand-editing frontmatter for creating/updating tasks, because the plugin manages ids, dates, and recurrence for you.

• api is the TaskNotes plugin API; app is the Obsidian app.
• Discover what's available at runtime before assuming methods exist — e.g. return Object.keys(api) or inspect a method's shape — since the API surface can change across plugin versions.
• Prefer the API for mutations (create/update/complete) over manage_notes frontmatter edits when it's available. Fall back to the file-based approach below if the integration is off.
• Keep snippets read-only unless the user asked to modify data. Awaited work times out; this is not sandboxed.

// Inspect the available API before calling it
return Object.keys(api);

Task File Format

Every task is a .md file. The full set of supported frontmatter fields is:

---
title: "Task title"               # string, required
status: "open"                    # see Statuses below
priority: "normal"                # see Priorities below
due: "2025-01-20"                 # YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS
scheduled: "2025-01-15"          # planned start date (when to work on it)
completed_date: "2025-01-20"     # set automatically when status → completed
contexts:                         # list of @context strings
  - "@work"
  - "@computer"
projects:                         # list of [[wikilinks]] or plain strings
  - "[[Website Redesign]]"
tags:                             # native Obsidian tags
  - "important"
time_estimate: 60                 # minutes (integer)
timeEntries:                      # work session log
  - startTime: "2025-01-15T10:00:00Z"
    endTime: "2025-01-15T10:45:00Z"
    description: "Initial work"
recurrence: "FREQ=WEEKLY;BYDAY=MO"  # RFC 5545 RRULE
recurrence_anchor: "scheduled"      # "scheduled" or "completion"
complete_instances:               # list of completed occurrence dates (recurring tasks)
  - "2025-01-13"
skipped_instances: []             # list of skipped occurrence dates
blocked_by:                       # prerequisite tasks
  - uid: "other-task-id"
    reltype: "FINISHTOSTART"      # FINISHTOSTART | FINISHTOFINISH | STARTTOSTART | STARTTOFINISH
    gap: "1d"                     # optional delay after predecessor
reminders:
  - type: "relative"              # "relative" or "absolute"
    value: "-1d"                  # "-1d" means 1 day before due/scheduled
archived: false                   # boolean
id: "task-uuid"                   # stable identifier (set by plugin)
date_created: "2025-01-10T09:00:00Z"
date_modified: "2025-01-15T14:30:00Z"
---

Optional markdown body with notes, checklists, context, etc.

Statuses

Default values (the user may have customized these):

When a task reaches a "completed" status, completed_date is set automatically and the plugin may archive it after a configured delay.

Priorities

Default values (the user may have customized these):

Key Distinctions

• due — the hard deadline. Use this when the user says "due by", "deadline", "must finish by".
• scheduled — the planned start date. Use this when the user says "start on", "work on it on", "plan for". For recurring tasks, this holds the next concrete occurrence.
• Both fields are independent: a task can have a scheduled date without a due date and vice versa.

Querying Tasks

Find tasks by status

Use search_notes with a property filter, or get_properties to inspect a file's frontmatter.

For structured queries across many tasks, use execute_dataview_query (if the Dataview skill is also enabled):

TABLE title, status, due, priority
FROM "TaskNotes/Tasks"
WHERE status != "done"
SORT due ASC
LIMIT 20

Find overdue tasks

TABLE title, due, priority
FROM "TaskNotes/Tasks"
WHERE due AND date(due) < date(today) AND status != "done"
SORT priority DESC, due ASC
LIMIT 20

Find tasks due today or this week

TABLE title, due, status
FROM "TaskNotes/Tasks"
WHERE due AND date(due) >= date(today) AND date(due) <= date(today) + dur(7 days)
SORT due ASC
LIMIT 20

Find tasks by project

TABLE title, status, due
FROM "TaskNotes/Tasks"
WHERE contains(projects, "[[Website Redesign]]")
SORT due ASC
LIMIT 20

Find tasks by context

TABLE title, status, due
FROM "TaskNotes/Tasks"
WHERE contains(contexts, "@work")
SORT priority DESC
LIMIT 20

Find high-priority open tasks

TABLE title, due, scheduled
FROM "TaskNotes/Tasks"
WHERE priority = "high" AND status = "open"
SORT due ASC
LIMIT 20

Creating a Task

Use manage_notes with type: "create". Always include at minimum title and status. Follow this template:

---
title: "Buy groceries"
status: "open"
priority: "normal"
scheduled: "2025-01-15"
due: ""
contexts:
  - "@errands"
projects: []
tags: []
time_estimate: 30
---

Rules:

• Store in the task folder (ask the user if unsure; default is TaskNotes/Tasks/).
• Use the task title as the filename, sanitised for the filesystem (e.g., Buy groceries.md).
• Always use YYYY-MM-DD date format.
• Leave unknown fields empty ("") rather than omitting them — the plugin expects them.
• Do NOT set date_created, date_modified, or id — these are managed by the plugin.

Completing a Task

Update the status field to the completed value (usually "done") via manage_notes with type: "update".

{
  "type": "update",
  "path": "TaskNotes/Tasks/Buy groceries.md",
  "edits": [
    { "oldText": "status: \"open\"", "newText": "status: \"done\"" }
  ]
}

Do NOT set completed_date manually — the plugin manages it automatically.

Rescheduling a Task

Update scheduled and/or due with the new date:

{
  "type": "update",
  "path": "TaskNotes/Tasks/Some task.md",
  "edits": [
    { "oldText": "scheduled: \"2025-01-10\"", "newText": "scheduled: \"2025-01-17\"" }
  ]
}

Recurring Tasks

Recurring tasks use RFC 5545 RRULE syntax in the recurrence field. The scheduled field holds the next occurrence — do not manually advance it; the plugin handles this on completion.

Common patterns

recurrence_anchor controls whether the next recurrence is calculated from the scheduled date ("scheduled") or from the actual completion date ("completion").

To mark a single occurrence as done without creating a new manage_notes update, you'd normally use the plugin's UI. If the user asks to mark one occurrence done via the agent, append the date to complete_instances:

{ "oldText": "complete_instances: []", "newText": "complete_instances:\n  - \"2025-01-13\"" }

Time Estimates & Tracking

• time_estimate is an integer in minutes.
• timeEntries is a list of {startTime, endTime, description} objects with ISO 8601 UTC timestamps.
• Use the plugin's UI to start/stop the timer. The agent can read timeEntries to summarise tracked time.

Summarise tracked time for a task

Total minutes tracked = sum of (endTime - startTime) across all entries. When answering questions about time tracked, compute this from the timeEntries array.

Task Dependencies

The blocked_by field lists prerequisite tasks:

blocked_by:
  - uid: "abc123"           # the `id` of the blocking task
    reltype: "FINISHTOSTART" # relationship type
    gap: "1d"               # optional gap after predecessor finishes

Relationship types:

• FINISHTOSTART — this task can start after the predecessor finishes (most common)
• FINISHTOFINISH — this task must finish at/after the predecessor finishes
• STARTTOSTART — this task can start after the predecessor starts
• STARTTOFINISH — this task must finish after the predecessor starts

Working with the Bases Skill

If the bases skill is enabled, you can create .base views over the task folder for rich UI. Example — open tasks by priority:

filters:
  and:
    - file.inFolder("TaskNotes/Tasks")
    - 'status != "done"'

formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
  is_overdue: 'if(due, date(due) < today(), false)'

views:
  - type: table
    name: "Open Tasks"
    order:
      - file.name
      - status
      - priority
      - due
      - formula.days_until_due
    groupBy:
      property: priority
      direction: DESC

Tips & Constraints

• Always read a task file before updating it — use read_content or get_properties to get the current frontmatter before constructing edits.
• Use exact string matches in edits — Obsidian's manage_notes tool does text replacement, so the oldText must exactly match what's in the file, including indentation and quotes.
• Do not edit id, date_created, date_modified, completed_date — these are plugin-managed fields.
• Task folder path is configurable by the user. If unsure, search for files with status in their frontmatter to locate the tasks folder.
• If the user's statuses or priorities differ from the defaults above, read an existing task first to discover the actual values in use.