| name | task |
| description | Task management system for tracking work across nested projects with TODO.md files |
Task Management Skill
This skill helps agents understand and work with the task management system.
Overview
The task management system tracks work using TODO.md and COMPLETED.md files across nested projects:
- Each subproject can have its own TODO.md
- Cross-project tasks go in the root TODO.md
- Sequential IDs across all projects (1, 2, 3, ...)
File Structure
project/
├── TODO.md # Cross-project tasks
├── COMPLETED.md # Cross-project completed
├── cli/
│ ├── TODO.md # CLI-specific tasks
│ └── COMPLETED.md # CLI completed
└── .opencode/skills/task/
├── SKILL.md # This file
└── scripts/
├── list-tasks.sh
├── complete-task.sh
├── update-task.sh
├── validate-todos.py
└── regenerate-qr.sh
Task Format
Each task uses strict formatting with markers:
<!-- TASK:123 -->
### 123. Task Title
| Field | Value |
|-------|-------|
| **id** | 123 |
| **status** | pending | in_progress | blocked | complete |
| **priority** | critical | high | medium | low |
| **created** | 2026-02-08 |
**Description**
Task description here.
<!-- END TASK:123 -->
Available Scripts
All scripts are in .opencode/skills/task/scripts/:
| Script | Purpose |
|---|
list-tasks.sh | List all active tasks with priority sorting |
list-tasks.sh --include-completed | List all tasks including completed |
complete-task.sh <id> | Mark task complete and move to COMPLETED.md |
update-task.sh <id> --status <v> | Update task status |
update-task.sh <id> --priority <v> | Update task priority |
update-task.sh <id> --title <v> | Update task title |
validate-todos.py | Validate all TODO.md formatting |
regenerate-qr.sh <file> | Regenerate Quick Reference table |
regenerate-qr.sh --all | Regenerate all Quick References |
When to Use
Use this skill when the user asks about:
- Listing tasks
- Creating new tasks
- Completing tasks
- Updating task status/priority
- Validating TODO.md files
- Understanding the task system
Creating a New Task
- Run
list-tasks.sh to find the next available ID
- Determine the correct TODO.md file (root for cross-project, subdirectory for specific)
- Add task with proper format (see Task Format above)
- Run
regenerate-qr.sh <file> to update Quick Reference
- Run
validate-todos.py to verify
Completing a Task
Always use the script:
.opencode/skills/task/scripts/complete-task.sh <task-id>
This will:
- Find the task in TODO.md files
- Update status to
complete
- Add completion date
- Move to appropriate COMPLETED.md
- Regenerate Quick Reference
- Validate the result
Common Status Values
pending - Not started
in_progress - Currently being worked on
blocked - Waiting on something else
complete - Done (use complete-task.sh to set)
Common Priority Values
critical - Urgent, blocking
high - Important
medium - Normal priority
low - Nice to have