Skip to content
Skills Library
AI & agents · Automation

task-workflow

/task-workflow

This skill should be used when an AI agent needs to "add a task", "create a task", "update a task", "modify a task", "complete a task", "mark task done", "close a task", "start working on a task", "annotate a task with notes", "add context to a task", "log progress on a task", "check task status", "list tasks", "show overdue tasks", "manage tasks with taskwarrior", or when any agent workflow requires recording work in the task ledger. Defines the default add→start→update→close lifecycle for AI agents executing tasks via the `task` CLI.

Licence
MIT
Last repository change
18.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
1
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 18.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/tw-summary.sh

What it does and when to use it

This skill should be used when an AI agent needs to "add a task", "create a task", "update a task", "modify a task", "complete a task", "mark task done", "close a task", "start working on a task", "annotate a task with notes", "add context to a task", "log progress on a task", "check task status", "list tasks", "show overdue tasks", "manage tasks with taskwarrior", or when any agent workflow requires recording work in the task ledger. Defines the default add→start→update→close lifecycle for AI agents executing tasks via the `task` CLI.

Triggers from the description

add a taskcreate a taskupdate a taskmodify a taskcomplete a taskmark task doneclose a taskstart working on a task
Original author description

This skill should be used when an AI agent needs to "add a task", "create a task", "update a task", "modify a task", "complete a task", "mark task done", "close a task", "start working on a task", "annotate a task with notes", "add context to a task", "log progress on a task", "check task status", "list tasks", "show overdue tasks", "manage tasks with taskwarrior", or when any agent workflow requires recording work in the task ledger. Defines the default add→start→update→close lifecycle for AI agents executing tasks via the `task` CLI.

How it works

  1. Core Lifecycle: Add → Start → Update → Close
  2. Notes and Annotations
  3. Viewing Tasks
  4. Mandatory State Updates for AI Agents
  5. Picking Up Existing Work
  6. Modifying Tasks
  7. Calendar Integration
  8. Additional Resources
Original SKILL.md headings · 233 lines, 1,053 words
SKILL.md preview
---
name: task-workflow
description: >
  This skill should be used when an AI agent needs to "add a task", "create a task",
  "update a task", "modify a task", "complete a task", "mark task done", "close a task",
  "start working on a task", "annotate a task with notes", "add context to a task",
  "log progress on a task", "check task status", "list tasks", "show overdue tasks",
  "manage tasks with taskwarrior", or when any agent workflow requires recording work
  in the task ledger. Defines the default add→start→update→close lifecycle for AI
  agents executing tasks via the `task` CLI.
---

# Task Workflow

Manage the full lifecycle of tasks using Taskwarrior — from capture through completion.
This skill defines the canonical workflow AI agents MUST follow when touching the task
ledger. Taskwarrior stores data in `~/.task/` by default; run all `task` commands via Bash.

## Core Lifecycle: Add → Start → Update → Close

Every unit of work follows this four-stage lifecycle. Never skip stages silently.

### Stage 1: Add (Capture)

Capture tasks immediately when work is identified. A task not in the ledger doesn't exist.

```bash
# Minimal capture — always include project
task add "Description of work" project:ProjectName

# Full capture with all known attributes
task add "Description of work" \
  project:ProjectName.SubProject \
  priority:H \
  due:tomorrow \
  +tag1 +tag2

# Record the new task ID from output for subsequent commands
```

**Capture rules:**
- Always assign a `project` — unowned tasks decay
- Use `project:Parent.Child` for sub-projects (e.g., `project:Work.API`)
- Set `priority:H/M/L` only when it reflects real urgency — do not default to H
- Add `due:` only when there is a real deadline
- Add `+` tags for cross-cutting concerns (`+blocked`, `+waiting`, `+review`)
- Translate natural language dates: "next Friday" → `due:friday`, "end of month" → `due:eom`

### Stage 2: Start (Activate)

Before executing any work, mark the task active. This creates an audit trail and exposes
blockers before time is spent.

```bash
# Read full task record — annotations are context pointers
task <id> info

# Open any annotation URLs or file paths before acting:
# obsidian:// links → open the note
# https://github.com/... → read the issue/PR
# ~/path/to/file → read the file

# Mark active
task <id> start
```

**Start rules:**
- Always run `task <id> info` before starting — annotations contain the full context
- Open every annotation that is a URL or file path before proceeding
- Only start one task at a time when possible (`task +ACTIVE list` to check)

### Stage 3: Update (Progress)

Log progress incrementally. Do not batch updates at the end — if execution is interrupted,
the ledger must reflect current state.

```bash
# Annotate progress — one annotation per meaningful event
task <id> annotate "Progress: implemented X, pending Y"

# Annotate a blocker
task <id> annotate "Blocked: waiting for API key from team"
task <id> modify +blocked

# Link a new resource discovered during work
task <id> annotate "https://github.com/user/repo/issues/42"
task <id> annotate "~/code/project/src/module.py"

# Annotate an Obsidian note
task <id> annotate "obsidian://open?vault=<vault>&file=Projects/<slug>/notes.md"

# Update due date if timeline changed
task <id> modify due:eow

# Remove a tag when state resolves
task <id> modify -blocked
```

**Update rules:**
- One annotation per resource or event — keeps each item individually removable
- Never batch multiple updates into one annotation
- If blocked mid-work: annotate the reason + add `+blocked` before stopping
- If context becomes available (URL, file, note), annotate immediately
- See `references/obsidian-vault.md` for Obsidian URI format

### Stage 4: Close (Complete)

Close tasks immediately when work is done. Never leave a finished task pending.

```bash
# Mark done — mandatory after any completed work
task <id> done

# If a GitHub/GitLab issue was linked, close or comment after marking done
# (retrieve annotation first: task <id> info)

# Partial completion — stop and annotate remaining work
task <id> stop
task <id> annotate "Partial: completed X. Remaining: Y"
```

**Close rules:**
- Call `task <id> done` — this is non-negotiable; the task is not done until the ledger reflects it
- If completion is partial: stop the active timer, annotate remaining work, do NOT mark done
- After closing, show a brief summary of remaining tasks in the same project

## Notes and Annotations

Annotations are the primary mechanism for attaching context — notes, URLs, file paths,
Obsidian links, GitHub issues. A task can carry unlimited annotations.

```bash
# Plain note
task 42 annotate "Spoke with vendor, waiting for quote"

# Obsidian note (see references/obsidian-vault.md for vault config)
task 42 annotate "obsidian://open?vault=<vault>&file=Projects/<slug>/meeting.md"

# Web URL
task 42 annotate "https://github.com/user/repo/issues/87"

# Local file
task 42 annotate "~/code/src/validator.rs"

# View all annotations
task 42 info

# Remove a specific annotation (matches by substring)
task 42 denotate "validator.rs"
```

For multiline notes and extended task descriptions, see `references/examples.md`.

## Viewing Tasks

```bash
# Daily planning view (urgency-sorted)
task next

# Full pending list
task list

# Task with all annotations and metadata
task <id> info

# Overdue
task +OVERDUE list

# Due today
task +TODAY list

# Active (started) tasks
task +ACTIVE list

# By project
task project:Work list

# Quick summary across all projects
bash ${CLAUDE_PLUGIN_ROOT}/skills/task-workflow/scripts/tw-summary.sh
```

## Mandatory State Updates for AI Agents

Every time an AI agent completes, stalls, or is blocked on work, it MUST update Taskwarrior
before considering the turn done.

| Situation | Required action |
|-----------|----------------|
| Work completed | `task <id> done` |
| Work partially done | `task <id> stop` + annotate progress |
| Blocked | `task <id> modify +blocked` + annotate reason |
| Blocked resolved | `task <id> modify -blocked` + `task <id> start` |
| New resource found | `task <id> annotate "<url or path>"` |
| Timeline slipped | `task <id> modify due:<new-date>` |

## Picking Up Existing Work

```bash
# See what is active
task +ACTIVE list

# Read full record before acting
task <id> info

# Open all annotation pointers — obsidian://, https://, ~/path
# Then continue from where work left off
```

## Modifying Tasks

```bash
# Change priority
task <id> modify priority:H

# Change project
task <id> modify project:Work.Q4

# Set due date
task <id> modify due:tomorrow

# Add/remove tags
task <id> modify +important -waiting

# Add dependency (task <id> cannot start until task <dep> is done)
task <id> modify depends:<dep>

# Change description
task <id> modify "Updated description"
```

## Calendar Integration

To schedule work blocks or check availability before setting `due:`, use the `task-calendar` skill.
It bridges tasks with Google Calendar without modifying this workflow.

## Additional Resources

- **`references/best-practices.md`** — Taskwarrior best practices: project hierarchy, tagging, urgency, capture habits
- **`references/examples.md`** — Multiline tasks, notes patterns, complex real-world examples
- **`references/filters.md`** — Full filter syntax: operators, date math, virtual tags
- **`references/advanced.md`** — Urgency tuning, UDAs, hook scripts, custom reports
- **`references/obsidian-vault.md`** — Vault name, base path, PARA URI patterns
- **`scripts/tw-summary.sh`** — Quick summary by project, overdue, and active tasks
Files in this package (7)
  • SKILL.md 7 KB
  • references/advanced.md 6 KB
  • references/best-practices.md 5 KB
  • references/examples.md 6 KB
  • references/filters.md 6 KB
  • references/obsidian-vault.md 1 KB
  • scripts/tw-summary.sh 2 KB

Versions

RepositoryScoreLicence
This page · kjgarza/marketplace-claude100MIT
customware-ai/skills90MIT

Database snapshot: 13.11.2026 · package version f71b787f17fc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100task-done
    Close a taskwarrior task with landing commit annotation and optional GitHub issue/PR close. Use when finishing a coordination task or marking a work order complete.
  • 100task-init
    This skill should be used when the user asks to "initialize taskwarrior", "set up taskwarrior", "configure taskwarrior for this project", "run /init for taskwarrior", "set up task management", "bootstrap the task plugin", "configure task contexts", or "first-time taskwarrior…
  • 100taskwarrior
    Use when querying or modifying tasks via the taskwarrior CLI - dense recipes for listing, single-field lookups, multi-task batched lookups, full-text search, and the soft description-length convention. Activates on `task list`, `task add`, `task info`, `task done`, "what's on…
  • 100tasks
    Claude Code task framework for reusable workflows. Use when user asks about "/task:run", "/task:list", "/task:new", "create a task", "global tasks", "local tasks", or needs to run structured multi-step workflows. Triggers on task-related questions or when creating reusable automation.
  • 100task-reconcile
    Close taskwarrior tasks whose linked GitHub issue/PR closed or merged. Use when stale trackers pile up, after a PR-merge sweep, or auditing queue drift.
  • 100task-system
    Manage shared task lists for agent teams including creating tasks, setting dependencies, claiming work, and tracking progress. Use when creating work items, building task pipelines, coordinating task ownership, or managing task dependencies.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.