TaskNotes CLI Skill

Manage tasks in Obsidian using the TaskNotes CLI (tn) tool.

When to Use

Activate this skill when users:

• Ask about their tasks, todos, or work items
• Want to see what they need to do today or this week
• Need to create, update, or complete tasks
• Mention keywords: task, todo, 任务, 工作, 待办, Obsidian, 日程, deadline, overdue
• Ask questions like "我今天要做什么", "有什么任务", "帮我看看工作进度"

Core Commands

List Tasks

# List active tasks (default limit: 20)
tn list --limit 10

# Today's tasks
tn list --today

# Overdue tasks
tn list --overdue

# Completed tasks
tn list --completed

# JSON output (for parsing)
tn list --json --limit 10

Filter Tasks

Use --filter for advanced queries:

# By status
tn list --filter "status:in-progress"
tn list --filter "status:done"

# By priority
tn list --filter "priority:high"

# By context (工作/学习/生活)
tn list --filter "contexts:@工作"

# By project
tn list --filter "projects:拓扑灵犀"

# Combined filters
tn list --filter "priority:high AND status:in-progress"
tn list --filter "(status:in-progress OR status:open) AND contexts:@工作"

# Date-based
tn list --filter "due:before:2026-01-25"

Available Statuses: open, deep-research, plan-mode, in-progress, done, pending

Available Priorities: none, low, normal, high

Available Contexts: @@学习, @@工作, @@生活, @work, @cleanup

Search Tasks

tn search "关键词"

Create Tasks

⚠️ 重要: tn create 的自然语言解析功能不稳定，可能会把 due:today 等关键字直接写入标题而非 frontmatter。

推荐做法: 先创建任务（仅标题），然后用 tn update 设置属性：

# 推荐方式：分两步创建
tn create "完成项目报告"
tn update "Calendar/Tasks/完成项目报告.md" --due tomorrow --priority high

# 或者一行完成（先创建再更新）
tn create "开会讨论需求" && tn update "Calendar/Tasks/开会讨论需求.md" --scheduled 2026-01-25

不推荐（自然语言解析可能失败）：

# 可能导致 "due:tomorrow priority:high" 被写入标题
tn create "完成项目报告 due:tomorrow priority:high"

Update Tasks

Task IDs are file paths like Calendar/Tasks/任务名.md

# Update status
tn update "Calendar/Tasks/任务名.md" --status in-progress
tn update "Calendar/Tasks/任务名.md" --status done

# Update priority
tn update "Calendar/Tasks/任务名.md" --priority high

# Update dates
tn update "Calendar/Tasks/任务名.md" --due 2026-01-30
tn update "Calendar/Tasks/任务名.md" --scheduled 2026-01-25

# Update title
tn update "Calendar/Tasks/任务名.md" --title "新的任务标题"

# Manage tags/contexts/projects
tn update "Calendar/Tasks/任务名.md" --add-tags "urgent,important"
tn update "Calendar/Tasks/任务名.md" --add-contexts "@工作"
tn update "Calendar/Tasks/任务名.md" --add-projects "项目名"

Complete Tasks

tn complete "Calendar/Tasks/任务名.md"

Toggle Task Status

tn toggle "Calendar/Tasks/任务名.md"

Delete Tasks

tn delete "Calendar/Tasks/任务名.md" --force

Archive Tasks

tn archive "Calendar/Tasks/任务名.md"

Statistics & Projects

# Overall statistics
tn stats

# List projects
tn projects list

# Show project details
tn projects show "项目名"

# Project statistics
tn projects stats "项目名" --period month

Time Tracking

# Start timer for a task
tn timer start --task "Calendar/Tasks/任务名.md"

# Stop timer
tn timer stop

# Check timer status
tn timer status

# View time log
tn timer log --period today
tn timer log --period week

Pomodoro Timer

# Start pomodoro session
tn pomodoro start --task "Calendar/Tasks/任务名.md"
tn pomodoro start --duration 25

# Control pomodoro
tn pomodoro pause
tn pomodoro resume
tn pomodoro stop

# View stats
tn pomodoro status
tn pomodoro stats --week
tn pomodoro sessions --limit 10

Filter Syntax Reference

Property	Operators	Example
status	is, is-not	status:in-progress
priority	is, is-not	priority:high
tags	contains	tags:urgent
contexts	contains	contexts:@工作
projects	contains	projects:项目名
due	before, after, on-or-before	due:before:2026-01-25
scheduled	before, after	scheduled:after:2026-01-20
title	contains	title:contains:"会议"
archived	checked, not-checked	archived:not-checked

Logical Operators: AND, OR, parentheses for grouping

Workflow Guidelines

1. Start of day: Run tn list --today or tn list --overdue to check pending work
2. Before starting work: Update task status to in-progress
3. When blocked: Update status to pending or add context
4. After completion: Run tn complete <taskId> to mark done
5. Weekly review: Run tn stats and tn projects list to review progress

Notes

• Task IDs are Obsidian file paths relative to vault root
• Suppress deprecation warnings by redirecting stderr: 2>/dev/null
• Use --json flag for programmatic parsing
• Vault location: /path/to/your/vault (example: ~/Documents/notes/my-vault)