dingMCP/skills/dingtalk-approval/SKILL.md

name, description

name

description

dingtalk-approval

Use the protected DingTalk Approval MCP to list, inspect, summarize, approve, reject, return, create, or locally draft the signed-in user's DingTalk OA and XFT approvals, including approvals the user handled or submitted. Trigger for approval todos or history, expense review, reimbursement details, explicit approval actions, requests to start or submit a new approval, or requests to save, continue, list, or delete a local approval draft.

DingTalk Approval

Use only the dingtalk-approval MCP tools. DingTalk OA and XFT use the same gateway-authenticated DingTalk user. Never ask for AppKey, Secret, userId, employee ID, cookies, or raw access tokens.

Login and first run

Use the host's native remote-MCP OAuth flow when the user can complete its registered callback. If the redirect URI uses 127.0.0.1 or localhost, the user must open the authorization page on the same device that runs the Agent. An SSH, headless, Messenger, phone, or other cross-device interaction cannot complete that loopback callback and must use the local STDIO Bridge device-code flow instead. If the interaction topology is unknown during installation, ask only whether the user will open the page on the Agent's device. When native OAuth is suitable, let the host open or present the authorization URL and have the user authorize it personally. Never claim that a link was pushed through another channel. After OAuth succeeds, make one read-only approval_list_todos call with source=all and limit=1; both DingTalk OA and XFT must be available before reporting setup complete.

When a successful response contains onboarding.firstRun=true, show its short examples and write-safety note once. Do not execute an example automatically.

Hosts that cannot use remote Streamable HTTP MCP or standard OAuth, and cross-device users who cannot reach a host loopback callback, should use the optional local STDIO Bridge. In that compatibility mode, handle the installer's postInstall immediately. If it contains authChallenge.directUrl, copy the complete clickable URL into the current reply; the user may open this device-code page on another device. If the link expires, call approval_login; if the connector is not loaded yet, run the returned loginCommand. Never reinstall merely to renew a link, read Bridge state files, or render QR images as ASCII. One successful gateway login covers both sources.

Review and process

1. Call approval_list_todos first. Treat approvalId, selectionId, targetId, reference availability, call limits, and batching as internal tool details: never mention or explain them to the user. When the user only asks to review approvals, report only relevant business information and do not proactively discuss how writes would be performed. Internally use approvalId for one or some items; when the user explicitly asks to process the entire returned result set and a selectionId is present, prefer it because the gateway binds it to that exact live set.
2. For ordinary review call approval_get_detail with view=summary; for expenses use view=expense. Use filtered raw paging only when a required field is missing.
3. Approve and reject do not require per-item approval_get_actions calls: the gateway revalidates every item immediately before writing. allowed=true means the pending-task preflight passed; guaranteed=false means DingTalk may still enforce a signature or another business rule at execution. Only before return, call approval_get_actions and copy a returned targetId exactly.
4. Call approval_process_batch only after the user explicitly requests a write action. One call accepts at most 20 items. For an entire eligible listed group pass selectionId and an empty items list; for a subset pass its approvalId items. Never combine both. If one confirmed list contains more than 20 requested items, split only those original approvalId values into internal groups of at most 20; do not relist between groups or mix newly appeared todos into the authorization. The user's request must cover every group, but do not add a redundant confirmation when it already clearly does. Never tell the user about the 20-item limit, internal grouping, or reference fields; simply carry out the authorized business action and report the business results.
5. The gateway validates every approvalId and targetId before the first write. If any reference is invalid, the result is preflight_failed, writesStarted=false, and the entire call writes zero items. Relist, show the refreshed targets, and obtain confirmation again; never compensate or retry automatically.
6. Report every item result from the compact tool text. failed means the operation was rejected and did not take effect; do not retry unless the user explicitly asks after reviewing the reason. succeeded means the node was submitted; completed means the current user has no remaining node. outcome_uncertain means a write was submitted but not confirmed: never retry it automatically; wait and list todos again. If follow-up is required, list todos again. If a DingTalk template requires handwriting or another client-only action, send its client link to the user instead of retrying.

Review history

Call approval_list_history with scope=handled for approvals the current user already processed, or scope=submitted for approvals the current user initiated. The default window is the most recent 30 days. Use optional startDate and endDate for a specific window of at most 120 days; YYYY-MM-DD is interpreted in Asia/Shanghai, the end date is inclusive, and timezone-aware ISO 8601 timestamps are also accepted. Use source, query, and limit to narrow the live result. Historical approvalId values are user-bound, short-lived, and read-only: use them only with approval_get_detail. Never pass them to approval_get_actions or approval_process_batch; the gateway rejects them before any write. Historical results intentionally have no selectionId or available actions.

Create an approval

When the user asks to draft, save, continue, list, or delete a submission draft, read references/local-drafts.md completely and follow it. A draft exists only on the Agent machine and never on the gateway or upstream service. Do not expose its UUID or local path.

Before preparing, submitting, revoking, or reconciling a newly initiated approval—including one resumed from a local draft—read references/create-approval.md completely and follow it. Do not use that reference for ordinary todo review, history lookup, or processing someone else's pending approval.