DingTalk Todo Skill

Execution Contract

Before the first
```
dws
```
operation, fully read
```
dingtalk-shared
```
; if already loaded in the current task, do not read it again.
Break the request into ordered steps first, then choose entry points step by step. For known commands, execute directly without first checking Help, Schema, or Shortcut Catalog; only check the exact leaf when its flag or security semantics are genuinely unclear.
Add
```
--format json
```
to all commands and judge results by structured business responses. Subsequent IDs come only from this actual response; stop and disambiguate on zero matches, multiple matches, or unclear types.
Writes follow the final Runtime gate. When confirmation is needed, first state the object, action, and impact; append
```
--yes
```
only after the user confirms. Do not write
```
--yes
```
into stored examples.
Verify after every write. On non-idempotent write timeout, missing stable ID, or read-back failure, query to reconcile first; blind replay is forbidden.

Shortcuts (preferred when no dedicated script/recipe exists)

The following shortcuts also enter the public catalog and Runtime Schema. Route by this skill/recipe; on a hit, Shortcut takes priority over atomic commands. For parameters, only query

dws schema --cli-path "todo +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json

; when only the published

result

is needed, query with

--jq '{cli_path,outcomes:.result.outcomes,pagination}'

; for field-level details, query

data_schema

; do not infer missing information from Help/examples. Only when the Schema is unavailable, read the known leaf Help once; an

unknown flag

can be corrected once with the same leaf Help.

unknown command

forbids Help: a wrong suggestion → use the loaded Skill/reference to determine the entry; if both are absent, report drift. Full Catalog/root/parent/product Help is forbidden; omit

--compact

only for mapping, interface, or provenance audits. Only when existing routes and references cannot locate a low-frequency capability, use

dws shortcut list --service todo --format json

to discover.

Shortcut	Risk	Applicable scenarios
`dws todo +assign`	write	Create and assign a todo to someone by name (automatically resolves userId)
`dws todo +assign-multi`	write	Assign one todo to multiple people by name at once (automatically resolves each name into a userId)
`dws todo +comment`	write	Add a todo comment and read back to verify
`dws todo +create`	write	Create a todo and read back to verify
`dws todo +created-todos`	read	List todos I created (as creator, not assigned to me for execution)
`dws todo +due-today`	read	List todos due today
`dws todo +get`	read	Query todo details
`dws todo +get-my-tasks`	read	List my todos under the current organization
`dws todo +get-related-tasks`	read	List all todos related to me at once (union of creator/executor/participant roles, deduplicated by taskId)
`dws todo +list-attachment`	read	Query the attachment list of a todo task
`dws todo +list-comment`	read	Query the comment list of a todo
`dws todo +list-sub`	read	Query the subtask list
`dws todo +overdue`	read	List my overdue incomplete todos
`dws todo +remind`	write	Create a todo for myself with an optional due time
`dws todo +reminder`	write	Set or clear todo reminders (terminal receipt only)
`dws todo +search`	read	Search all todos related to me
`dws todo +todo-done`	write	Mark one of my todos as done by title keyword (automatically locates taskId)
`dws todo +update`	write	Update a todo and read back to verify

Routing Priority

The generic Shortcut priority rule above applies only when one Shortcut fully covers the current step. Do not default to

+remind

+create

just because the request contains 'create'.

Choose the creation entry first: use
```
+assign
```
/
```
+assign-multi
```
for assigning by name; use
```
+remind
```
for recording one for yourself that will only be searched, viewed, or cleaned up later; use
```
+create
```
when you already have a real
```
userId
```
and only need create, read-back, and cleanup.
Compose a lifecycle starting from atomic creation: use
```
todo task create
```
when after creation you need to list by status/priority/role/date/page, or continue updating, completing/reopening, reminding, commenting, attachments, members, subtasks, tags, or creating multiple objects at once. Do not use a creation Shortcut in place of the first step.
Then choose the narrowest entry per step: use
```
+get-my-tasks
```
,
```
+get-related-tasks
```
,
```
+due-today
```
,
```
+overdue
```
,
```
+search
```
,
```
+get
```
,
```
+complete
```
,
```
+reopen
```
,
```
+update
```
,
```
+comment
```
,
```
+reminder
```
, or
```
+list-*
```
when a Shortcut fully covers aggregation, search, and verification; use atomic commands when atomic-specific parameters, dynamic sub-resource IDs, multiple objects, or intermediate states are needed.
Use scripts for deterministic batch/aggregation: batch creation, today/tomorrow/week summaries, and overdue scans use the bundled scripts.
Only pass stable IDs across steps: Shortcuts and atomic commands can coexist, but only pass normalized
```
taskId
```
,
```
commentId
```
,
```
attachmentId
```
,
```
tagCode
```
, and
```
userId
```
; do not assume the two entry types have identical complete return structures.

Golden Routes

User intent	Preferred entry	Key results / boundaries
Create for yourself, then only search, view details, or clean up	`dws todo +remind --task "<标题>" [--at "<截止ISO>"] --format json`	Automatically resolves the current user; `--at` is the due time, not the reminder time
Assign a todo to Zhang San	`dws todo +assign --to "张三" --task "<标题>" --format json`	Create only after the name resolves uniquely
Create the same todo for Zhang San and Li Si	`dws todo +assign-multi --to "张三,李四" --task "<标题>" --format json`	If any name is not unique, zero writes are performed
Already have `userId` , only create, read back, and clean up	`dws todo +create --title "<标题>" --executors <USER_ID> [--due "<截止ISO>"] [--priority 10\|20\|30\|40] --format json`	Returns a stable `taskId` and reads back to verify the title
After creation, also filter, change resources, or create multiple objects	`dws todo task create --title "<标题>" --executors <USER_ID> ... --format json`	Enter the combined lifecycle from `result.taskId` ; do not start with `+remind` / `+create`
Due today / overdue	`dws todo +due-today --format json` / `dws todo +overdue --format json`	Both fetch all pages within bounds; an empty result is also a successful result
My execution todos under the current organization	`dws todo +get-my-tasks --all --status false --format json`	`--all` fails if not exhausted after 40 pages; do not pretend it is complete
All todos related to me	`dws todo +get-related-tasks --format json`	Union of creator/executor/participant roles, deduplicated by `taskId`
Query by title keyword	`dws todo +search --query "<关键词>" --format json`	Search and list are not mixed; matches across all pages
Known `taskId` , query details	`dws todo +get --task-id <TASK_ID> --format json`	Details must return the same stable `taskId`
Known `taskId` , complete / reopen	`dws todo +complete --task-id <TASK_ID> --format json` / `dws todo +reopen ...`	Read the current state first to avoid duplicate writes, then read back to verify
Only remember the title, mark as complete	`dws todo +todo-done --task "<关键词>" --format json`	Write only on a unique match; stop on zero or multiple candidates
Modify title, due time, or priority	`dws todo +update --task-id <TASK_ID> ... --format json`	Specify at least one field to change; verify each field after writing
Set a standalone reminder	`dws todo +reminder --task-id <TASK_ID> --base-time customTime --at "<提醒ISO>" --format json`	Upstream has no reminder query interface; only the terminal write receipt can be returned, `verified=false`
Remind in advance based on due time	`dws todo +reminder --task-id <TASK_ID> --base-time dueTime --due-date-offset -30 --format json`	The todo must already have a due time; offset unit is minutes
Clear all reminders	`dws todo +reminder --task-id <TASK_ID> --clear --format json`	Clear is a write operation; cannot be mixed with reminder parameters
Batch create	`python scripts/todo_batch_create.py <todos.json> --dry-run`	Preview returns a stable `planDigest` ; execution must submit the same digest confirmed by the user; content changes are rejected before any call is made
Today / tomorrow / week summary	`python scripts/todo_daily_summary.py today\|tomorrow\|week`	Uses `+get-my-tasks --all` ; only includes unfinished todos within the range and with a due time

Low-Frequency Atomic Capabilities

For combined requests, read Combined Lifecycle first. The following commonly used atomic commands are approved; execute them directly without guessing aliases or checking Help:

Intent	Command skeleton
Resolve self / name	`dws contact user get-self --format json` / `dws aisearch person --query "<姓名>" --dimension name --format json`
Create / subtasks	`dws todo task create ...` / `dws todo task create-sub --parent-id <PARENT_ID> --title "<标题>" --executors <USER_ID> ...`
List / details	`dws todo task list [--status true\|false] [--priority ...] [--role-types ...] [--page N --size N] ...` / `dws todo task get --task-id <TASK_ID>`
Update / complete or reopen	`dws todo task update --task-id <TASK_ID> ...` / `dws todo task done --task-id <TASK_ID> --status true\|false`
Add/remove executors / participants	`task add-executor` / `task remove-executor` / `task add-participant` / `task remove-participant` , all use the real `taskId` and `userId`
Comments	`comment add` / `comment list` / `comment delete` ; deletion uses the real `commentId` returned by the list
Attachments	`task add-attachment --file <绝对路径>` / `task list-attachment` / `task remove-attachment`
Reminders	`task add-reminder` adds one; `task reset-reminder` replaces all or clears them
Tags	`tag create` / `tag list` / `tag update` / `tag add` / `tag delete` ; only use real `tagCode`
Delete todo	`dws todo task delete --task-id <TASK_ID> --format json`

Delete-type operations must be confirmed by the user; if the user has explicitly authorized in the current request to 'delete/clean up the object created this time after completion', the authorization only covers the exact IDs recorded in this session. Attachment uploads actually transfer local files and must not be used to probe permissions.

Key Constraints

Title, URL, and display sequence number are not
```
taskId
```
. Act directly on known IDs; for unknown IDs, locate via list/search, and stop on zero or multiple matches.
Todo public commands uniformly use
```
--task-id
```
;
```
--id
```
/
```
--ids
```
are only hidden compatibility aliases. Do not write them into new commands or examples.
Priority: low=10, normal=20, above normal/high/important=30, urgent/highest/P0=40.
```
--due
```
/
```
+remind --at
```
means the deadline; standalone reminders must use
```
+reminder
```
.
The atomic flag for a custom-time reminder is
```
--reminder-time-stamp
```
; do not apply the Shortcut's
```
--at
```
to
```
task add-reminder
```
.
```
task list
```
uses
```
--status
```
; do not write
```
--done
```
; details are
```
task get
```
;
```
task detail
```
does not exist.
'Todo tags' always belong to Todo; use
```
dws todo tag ...
```
; never interpret them as Git tags, contact tags, or other product tags.
Creation and comments are non-idempotent writes. On timeout, missing stable ID, or read-back failure, keep a 'possibly submitted/unverified' state and query to reconcile first; blind replay is forbidden.
All commands add
```
--format json
```
; write Shortcuts follow the Runtime security contract; do not attach
```
--yes
```
on your own before confirmation.
Post-meeting action items from minutes should go through
```
dingtalk-minutes
```
first; OA approvals use
```
dingtalk-misc
```
; time blocks and meetings use
```
dingtalk-calendar
```
.

On-Demand References

Local Intent Disambiguation
Lightweight Flows
Combined Flows
Complete Command Reference

dingtalk-todo

NPX Install

Tags

SKILL.md Content (Chinese)