{
  "schemaVersion": "1.0",
  "item": {
    "slug": "ms-todo-oauth",
    "name": "Ms Todo Oauth",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/nathanatgit/ms-todo-oauth",
    "canonicalUrl": "https://clawhub.ai/nathanatgit/ms-todo-oauth",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/ms-todo-oauth",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ms-todo-oauth",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "_meta.json",
      "requirements.txt",
      "scripts/MANUAL_TEST_CHECKLIST.txt",
      "scripts/QUICK_REFERENCE.txt",
      "scripts/TEST_README.txt"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/ms-todo-oauth"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/ms-todo-oauth",
    "agentPageUrl": "https://openagent3.xyz/skills/ms-todo-oauth/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ms-todo-oauth/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ms-todo-oauth/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "ms-todo-oauth",
        "body": "A fully-tested Microsoft To Do command-line client for managing tasks and lists via Microsoft Graph API."
      },
      {
        "title": "⚠️This is a oauth based script. It contains a generated Azure Client ID and Secret ID",
        "body": "IF YOU WORRIED ABOUT YOUR PRIVACY, CONSIDER REPLACING THEM TO YOUR OWN IN scripts\\ms-todo-oauth.py.\nJust search for values below:\n\nclient_id=\"ca6ec244……\n\nclient_secret=\"TwQ8Q……"
      },
      {
        "title": "✨ Features",
        "body": "✅ Full Task Management: Create, complete, delete, and search tasks\n🗂️ List Organization: Create and manage multiple task lists\n⏰ Rich Task Options: Priorities, due dates, reminders, descriptions, tags\n🔄 Recurring Tasks: Daily, weekly, monthly patterns with custom intervals\n📊 Multiple Views: Today, overdue, pending, statistics\n🔍 Powerful Search: Find tasks across all lists\n💾 Data Export: Export all tasks to JSON\n🧪 Fully Tested: 29 comprehensive automated tests\n🌐 Unicode Support: Full support for Chinese characters and emojis"
      },
      {
        "title": "Prerequisites",
        "body": "Python >= 3.9 must be installed\nWorking directory: All commands MUST be run from the root of this skill (the directory containing this SKILL.md file)\nNetwork access: Requires internet access to Microsoft Graph API endpoints\nMicrosoft Account: Personal Microsoft account (Hotmail, Outlook.com) or work/school account\nAuthentication: First-time use requires OAuth2 login via browser. See Authentication section\n\nToken cache: ~/.mstodo_token_cache.json (persists across sessions, auto-refreshed)"
      },
      {
        "title": "First-Time Setup",
        "body": "Before using this skill for the first time, dependencies must be installed:\n\n# Navigate to skill directory\ncd <path-to-ms-todo-oauth>\n\n# Create a venv in the project (creates '.venv' folder)\npython3 -m venv .venv\n# Activate the venv choose based on platforms:\n#- Bash/Zsh: \nsource .venv/bin/activate\n# - Fish: \nsource .venv/bin/activate.fish\n#  - Windows (PowerShell):\n.venv\\Scripts\\Activate.ps1\n\npip install --upgrade pip\npip install -r requirements.txt\n\n# Alternative (global python env, not recommended):\n# pip install -r requirements.txt\n\nDependencies:\n\nmsal (Microsoft Authentication Library) - Official Microsoft OAuth library\nrequests - HTTP client for API calls\nSpecified in requirements.txt"
      },
      {
        "title": "Environment Verification",
        "body": "After installation, verify the setup:\n\n# If using native venv (activate as above):\npython3 scripts/ms-todo-oauth.py --help\n\n# Expected: Command help text should be displayed\n\nTroubleshooting:\n\nIf Python not found, install Python 3.9 or higher from https://python.org"
      },
      {
        "title": "Testing (Optional but Recommended)",
        "body": "Verify all functionality works correctly:\n\n# Run comprehensive automated test suite (29 tests)\npython3 test_ms_todo_oauth.py\n\n# Expected: All tests pass (100% pass rate)\n\nSee Testing section for details."
      },
      {
        "title": "Security Notes",
        "body": "Uses official Microsoft Graph API via Microsoft's msal library\nAll code is plain Python (.py files), readable and auditable\nTokens stored locally in ~/.mstodo_token_cache.json\nAll API calls go directly to Microsoft endpoints (graph.microsoft.com)\nOAuth2 standard authentication flow\nNo third-party services involved"
      },
      {
        "title": "Command Reference",
        "body": "All commands follow this pattern:\n\npython3 scripts/ms-todo-oauth.py [GLOBAL_OPTIONS] <command> [COMMAND_OPTIONS]"
      },
      {
        "title": "Global Options",
        "body": "OptionDescription-v, --verboseShow detailed information (IDs, dates, notes).Must be placed BEFORE the subcommand.--debugEnable debug mode to display API requests and responses. Useful for troubleshooting.Must be placed BEFORE the subcommand.--reauthForce re-authentication by clearing the token cache and starting fresh login\n\n⚠️ Common mistake: Global options MUST come before the subcommand.\n\n✅ python3 scripts/ms-todo-oauth.py -v lists\n✅ python3 scripts/ms-todo-oauth.py --debug add \"Task\"\n❌ python3 scripts/ms-todo-oauth.py lists -v"
      },
      {
        "title": "Authentication",
        "body": "Authentication uses OAuth2 authorization code flow, designed for both interactive and automated environments.\n\nlogin get — Get OAuth2 authorization URL\n\npython3 scripts/ms-todo-oauth.py login get\n\nOutput example:\n\n======================================================================\n🔐 OAuth2 Authorization Required\n======================================================================\n\nPlease visit the following URL to authorize the application:\n\n  https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?...\n\nAfter authorization, you will be redirected to a callback URL.\nCopy the 'code' parameter from the callback URL and run:\n\n  ms-todo-oauth.py login verify <authorization_code>\n\n======================================================================\n\nWhat to do:\n\nOpen the provided URL in your browser\nSign in with your Microsoft account\nGrant permissions when prompted\nYou'll be redirected to a URL like: http://localhost:8000/callback?code=M.R3_BAY.abc123...\nCopy the entire code after code= (usually a long string starting with M.R3_BAY.)\n\nAgent behavior: Present the URL to the user and explain they need to:\n\nVisit the URL\nComplete the login\nCopy the authorization code from the callback URL\nProvide it to you\n\nlogin verify — Complete login with authorization code\n\npython3 scripts/ms-todo-oauth.py login verify <authorization_code>\n\nExample:\n\npython3 scripts/ms-todo-oauth.py login verify \"M.R3_BAY.abc123def456...\"\n\nOutput on success:\n\n✓ Authentication successful!\n✓ Login information saved, you will be logged in automatically next time.\n\nOutput on failure:\n\n❌ Token acquisition failed\nError: invalid_grant\nDescription: AADSTS54005: OAuth2 Authorization code was already redeemed...\n\nExit code: 0 on success, 1 on failure.\n\nImportant notes:\n\nEach authorization code can only be used ONCE\nIf verification fails, you need to run login get again to get a new code\nOnce successfully logged in, the token is cached and you won't need to login again unless:\n\nYou run logout\nYou run --reauth\nThe token expires and cannot be auto-refreshed\n\nlogout — Clear saved login\n\npython3 scripts/ms-todo-oauth.py logout\n\nOutput: ✓ Login information cleared\n\nOnly use when the user explicitly asks to switch accounts or clear login data. Under normal circumstances, the token is cached and login is automatic."
      },
      {
        "title": "List Management",
        "body": "lists — List all task lists\n\npython3 scripts/ms-todo-oauth.py lists\npython3 scripts/ms-todo-oauth.py -v lists  # with IDs and creation dates\n\nOutput example:\n\n📋 Task Lists (3 total):\n\n1. 任务\n   ID: AQMkADAwATYwMAItYTQwZC04OThhLTAwAi0wMAoALgAAA0QJKpxW32BIsIlHaM...\n   Created: 2024-12-15T08:30:00Z\n2. Work\n3. Shopping\n\ncreate-list — Create a new list\n\npython3 scripts/ms-todo-oauth.py create-list \"<name>\"\n\nArgumentRequiredDescriptionnameYesName of the new list (supports Unicode/Chinese)\n\nExample:\n\npython3 scripts/ms-todo-oauth.py create-list \"项目 A\"\n\nOutput: ✓ List created: 项目 A\n\ndelete-list — Delete a list\n\npython3 scripts/ms-todo-oauth.py delete-list \"<name>\" [-y]\n\nArgument/OptionRequiredDescriptionnameYesName of the list to delete-y, --yesNoSkip confirmation prompt\n\n⚠️ This is a destructive operation. Without -y, the command will prompt for confirmation. All tasks in the list will be deleted. Consider asking the user before deleting important lists.\n\nOutput: ✓ List deleted: <name>\n\nExit code: 1 if list not found, 0 on success"
      },
      {
        "title": "Task Operations",
        "body": "add — Add a new task\n\npython3 scripts/ms-todo-oauth.py add \"<title>\" [options]\n\nOptionRequiredDefaultDescriptiontitleYes—Task title (positional argument, supports Unicode/Chinese/emojis)-l, --listNo(default list)Target list name. If not specified, uses your Microsoft To Do default list.-p, --priorityNonormalPriority:low, normal, high-d, --dueNo—Due date. Accepts days from now (3 or 3d) or date (2026-02-15). Note: Only date is supported by Microsoft To Do API, not time.-r, --reminderNo—Reminder datetime. Formats:3h (hours from now), 2d (days from now), 2026-02-15 14:30 (date+time with space, needs quotes), 2026-02-15T14:30:00 (ISO format), 2026-02-15 (date only, defaults to 09:00).-R, --recurrenceNo—Recurrence pattern. Formats:daily (every day), weekdays (Mon-Fri), weekly (every week), monthly (every month). With interval: daily:2 (every 2 days), weekly:3 (every 3 weeks), monthly:2 (every 2 months).-D, --descriptionNo—Task description/notes (supports multiline with quotes)-t, --tagsNo—Comma-separated tags/categories (e.g.,\"work,urgent\")--create-listNoFalseCreate the list if it doesn't exist (deprecated, lists auto-create now)\n\nAuto-created lists: If the specified list doesn't exist, it will be automatically created.\n\nOutput example:\n\n✓ Task added: Complete report\n\nWith recurrence:\n\n✓ Task added: Daily standup\n🔄 Recurring task created\n\nExamples:\n\n# Simple task\npython3 scripts/ms-todo-oauth.py add \"Buy milk\" -l \"Shopping\"\n\n# High priority task due in 3 days\npython3 scripts/ms-todo-oauth.py add \"Submit report\" -l \"Work\" -p high -d 3\n\n# Task with reminder in 2 hours\npython3 scripts/ms-todo-oauth.py add \"Call client\" -r 2h\n\n# Task with specific date and time reminder\npython3 scripts/ms-todo-oauth.py add \"Meeting\" -d 2026-03-15 -r \"2026-03-15 14:30\"\n\n# Daily recurring task\npython3 scripts/ms-todo-oauth.py add \"Daily standup\" -l \"Work\" -R daily\n\n# Weekday recurring task  \npython3 scripts/ms-todo-oauth.py add \"Gym\" -R weekdays -l \"Personal\"\n\n# Task with all options\npython3 scripts/ms-todo-oauth.py add \"Project Review\" \\\n  -l \"Work\" \\\n  -p high \\\n  -d 7 \\\n  -r \"2026-02-20 14:00\" \\\n  -D \"Review Q1 deliverables and prepare presentation\" \\\n  -t \"work,important,meeting\"\n\n# Chinese task with emoji\npython3 scripts/ms-todo-oauth.py add \"🎉 完成项目\" -l \"任务\" -p high\n\ncomplete — Mark a task as completed\n\npython3 scripts/ms-todo-oauth.py complete \"<title>\" [-l \"<list>\"]\n\nOptionRequiredDefaultDescriptiontitleYes—Exact task title-l, --listNo(default list)List name where the task resides\n\nTitle matching: Requires exact match. If unsure of exact title, use search first.\n\nOutput: ✓ Task completed: <title>\n\nExit code: 1 if task not found, 0 on success\n\ndelete — Delete a task\n\npython3 scripts/ms-todo-oauth.py delete \"<title>\" [-l \"<list>\"] [-y]\n\nOptionRequiredDefaultDescriptiontitleYes—Exact task title-l, --listNo(default list)List name where the task resides-y, --yesNo—Skip confirmation prompt\n\n⚠️ Destructive operation. Without -y, will prompt for confirmation.\n\nOutput: ✓ Task deleted: <title>\n\nExit code: 1 if task not found, 0 on success"
      },
      {
        "title": "Task Views",
        "body": "tasks — List tasks in a specific list\n\npython3 scripts/ms-todo-oauth.py tasks \"<list>\" [-a]\n\nOptionRequiredDescriptionlistYesList name (exact match)-a, --allNoInclude completed tasks (default: incomplete only)\n\nOutput example:\n\n📋 Tasks in list \"Work\" (2 total):\n\n1. [In Progress] Write documentation ⭐\n2. [In Progress] Review PR\n\nWith -a flag:\n\n📋 Tasks in list \"Work\" (3 total):\n\n1. [In Progress] Write documentation ⭐\n2. [Completed] Submit report\n3. [In Progress] Review PR\n\nExit code: 1 if list not found, 0 on success\n\npending — All incomplete tasks across all lists\n\npython3 scripts/ms-todo-oauth.py pending [-g]\n\nOptionRequiredDescription-g, --groupNoGroup results by list\n\nOutput example (with -g):\n\n📋 All incomplete tasks (3 total):\n\n📂 Work:\n  [In Progress] Write documentation ⭐\n  [In Progress] Review PR\n\n📂 Shopping:\n  [In Progress] Buy groceries\n\nWithout -g:\n\n📋 All incomplete tasks (3 total):\n\n[In Progress] Write documentation ⭐\n   List: Work\n[In Progress] Review PR\n   List: Work\n[In Progress] Buy groceries\n   List: Shopping\n\ntoday — Tasks due today\n\npython3 scripts/ms-todo-oauth.py today\n\nLists incomplete tasks with due date matching today's date.\n\nOutput example:\n\n📅 Tasks due today (2 total):\n\n[In Progress] Submit report ⭐\n   List: Work\n[In Progress] Buy groceries\n   List: Shopping\n\nIf no tasks: 📅 No tasks due today\n\noverdue — Overdue tasks\n\npython3 scripts/ms-todo-oauth.py overdue\n\nLists incomplete tasks past their due date, sorted by days overdue.\n\nOutput example:\n\n⚠️  Overdue tasks (1 total):\n\n[In Progress] Submit report ⭐\n   List: Work\n   Overdue: 3 days\n\nIf no overdue tasks: ✓ No overdue tasks\n\ndetail — View full task details\n\npython3 scripts/ms-todo-oauth.py detail \"<title>\" [-l \"<list>\"]\n\nOptionRequiredDefaultDescriptiontitleYes—Task title (supportspartial/fuzzy match)-l, --listNo(default list)List name\n\nFuzzy matching: Matches tasks containing the search string (case-insensitive).\n\nWhen multiple tasks match:\n\nPrefers incomplete tasks over completed\nReturns most recently modified task\n\nOutput example:\n\n============================================================\n📌 Task Details\n============================================================\n\n📋 Title: Complete Q1 Report\n🔖 Status: [In Progress]\n⚡ Priority: ⭐ High\n📅 Created: 2026-01-15 08:30:00\n📝 Modified: 2026-02-10 14:22:00\n⏰ Due: 2026-02-20 00:00:00\n🔔 Reminder: 2026-02-20 09:00:00\n\n📝 Notes:\n- Review sales figures\n- Include charts\n- Prepare for board meeting\n\n🏷️  Categories: work, important, Q1\n\n🔄 Recurrence:\n   Every week on Monday\n   Start date: 2026-02-17\n   No end date\n\n============================================================\n\nsearch — Search tasks by keyword\n\npython3 scripts/ms-todo-oauth.py search \"<keyword>\"\n\nSearches across all lists in both task titles and descriptions (case-insensitive).\n\nOutput example:\n\n🔍 Search results for \"report\" (2 found):\n\n[In Progress] Complete Q1 Report ⭐\n   List: Work\n   Notes: Review sales figures...\n\n[Completed] Submit weekly report\n   List: Work\n\nstats — Task statistics\n\npython3 scripts/ms-todo-oauth.py stats\n\nShows aggregate statistics across all lists.\n\nOutput example:\n\n📊 Task Statistics:\n\n  Total lists: 3\n  Total tasks: 15\n  Completed: 10\n  Pending: 5\n  High priority: 2\n  Overdue: 1\n\n  Completion rate: 66.7%\n\nexport — Export all tasks to JSON\n\npython3 scripts/ms-todo-oauth.py export [-o \"<filename>\"]\n\nOptionRequiredDefaultDescription-o, --outputNotodo_export.jsonOutput file path\n\nExports complete task data from all lists in JSON format.\n\nOutput: ✓ Tasks exported to: <filename>\n\nJSON structure:\n\n{\n  \"Work\": [\n    {\n      \"id\": \"AQMkADAwATYwMAItYTQw...\",\n      \"title\": \"Complete report\",\n      \"status\": \"notStarted\",\n      \"importance\": \"high\",\n      \"createdDateTime\": \"2026-01-15T08:30:00Z\",\n      \"dueDateTime\": {\n        \"dateTime\": \"2026-02-20T00:00:00.0000000\",\n        \"timeZone\": \"UTC\"\n      },\n      \"body\": {\n        \"content\": \"Review Q1 numbers\",\n        \"contentType\": \"text\"\n      },\n      \"categories\": [\"work\", \"important\"]\n    }\n  ],\n  \"Shopping\": [...]\n}"
      },
      {
        "title": "Exit Codes",
        "body": "CodeMeaning0Success1Failure (not logged in, API error, invalid arguments, resource not found)2Invalid command-line arguments"
      },
      {
        "title": "Common Error Messages",
        "body": "ErrorCauseResolution❌ Not logged inNo cached token or token expiredRun login get then login verify <code>ModuleNotFoundError: No module named 'msal'Dependencies not installedRun pip install -r requirements.txt❌ List not found: <name>Specified list does not existCheck list name with lists command. Note: exact match required.❌ Task not found: <name>No task with exact matching titleUse search to find exact title, or tasks \"<list>\" to list all tasks❌ Error: Invalid isoformat stringDateTime parsing errorThis should not occur in v1.1.0+. If you see this, report as bug.❌ Error: Unsupported HTTP methodInternal API errorThis should not occur in v1.1.0+. If you see this, report as bug.❌ Error: <API error message>Microsoft Graph API errorRetry; check network; use --debug for full detailsNetwork error / Connection timeoutNo internet or API unreachableCheck network connection; verify access to graph.microsoft.com"
      },
      {
        "title": "Testing",
        "body": "This skill includes a comprehensive test suite to ensure reliability."
      },
      {
        "title": "Automated Testing",
        "body": "Run the full test suite:\n\ncd <skill-directory>\npython3 test_ms_todo_oauth.py\n\nPrerequisites:\n\nMust be authenticated (logged in) before running tests\nInternet connection required\nApproximately 2-3 minutes to complete\n\nTest Coverage (29 tests):\n\n✅ Authentication (login/logout)\n✅ List management (create, delete, list)\n✅ Basic task operations (add, complete, delete, list)\n✅ Task options (priorities, due dates, reminders, descriptions, tags)\n✅ Recurring tasks (daily, weekly, weekdays, monthly, custom intervals)\n✅ Task views (today, overdue, pending, search, stats)\n✅ Data export and validation\n✅ Error handling (non-existent resources)\n✅ Unicode support (Chinese characters, emojis)\n\nExpected output:\n\n========================================================================\nTEST SUMMARY\n========================================================================\n\nTotal tests: 29\nPassed: 29\nFailed: 0\nPass rate: 100.0%\n\n========================================================================\n🎉 ALL TESTS PASSED! 🎉\n========================================================================"
      },
      {
        "title": "Manual Testing",
        "body": "For manual verification, see MANUAL_TEST_CHECKLIST.txt which provides:\n\nStep-by-step test procedures\nExpected outcomes\n9 test categories covering all functionality"
      },
      {
        "title": "Test Cleanup",
        "body": "The automated test suite:\n\nCreates a temporary test list (e.g., 🧪 Test List 14:23:45)\nRuns all tests in isolation\nDeletes the test list on completion\nCleans up any temporary files\n\nIf tests are interrupted, you may need to manually delete leftover test lists."
      },
      {
        "title": "Critical Rules",
        "body": "Working directory: Always cd to the directory containing this SKILL.md before running commands.\n\n\nDependency installation: Before first use or when encountering import errors, ensure all dependencies are installed.\n\n\nCheck authentication first: Before any operation, verify authentication status:\npython3 scripts/ms-todo-oauth.py lists\n\nIf this returns \"Not logged in\" error (exit code 1), initiate the login flow.\n\n\nTask list organization: When adding tasks:\n\nFirst, run lists to see available task lists\nIf user doesn't specify a list, tasks will be added to their default list (usually \"Tasks\" or \"任务\")\nIntelligently categorize tasks into appropriate lists:\n\nWork tasks → \"Work\" list\nPersonal errands → \"Personal\" or default list\nShopping → \"Shopping\" list\nProject-specific → Use project name as list\n\n\nLists will be auto-created if they don't exist\nSupport Chinese list names and Unicode characters\n\n\n\nDestructive operations: For delete and delete-list:\n\nThese commands prompt for confirmation by default (blocking behavior)\nUse -y flag ONLY when:\n\nUser has explicitly requested to delete without confirmation\nThe deletion intent is unambiguous and confirmed through conversation\n\n\nWhen in doubt, ask the user for confirmation instead of using -y\nThese operations return exit code 1 on failure (resource not found)\n\n\n\nGlobal option placement: -v, --debug, and --reauth must come BEFORE the subcommand:\n\n✅ python3 scripts/ms-todo-oauth.py -v lists\n❌ python3 scripts/ms-todo-oauth.py lists -v\n\n\n\nLogin flow:\n\nDo NOT call login verify until user confirms they've completed browser authentication\nEach authorization code can only be used once\nIf verify fails, you must run login get again for a new code\n\n\n\nError handling:\n\nCheck exit codes: 0 = success, 1 = failure, 2 = invalid arguments\nParse error messages to provide helpful guidance\nUse --debug flag when troubleshooting API issues"
      },
      {
        "title": "Recommended Workflow for Agents",
        "body": "Step 1: Setup and Authentication Check\n---------------------------------------\ncd <skill_directory>\n\npython3 scripts/ms-todo-oauth.py lists          # Test auth & see available lists\n\nIf exit code is 1 and output contains \"Not logged in\":\n  a. python3 scripts/ms-todo-oauth.py login get\n  b. Present URL to user\n  c. Explain: \"Visit this URL, login, and copy the 'code' parameter from callback URL\"\n  d. Wait for user to provide authorization code\n  e. python3 scripts/ms-todo-oauth.py login verify \"<code>\"\n  f. Verify success (exit code 0)\n\nStep 2: Task Analysis and List Selection\n-----------------------------------------\nWhen user requests to add task(s):\n  a. Analyze task context from user's description\n  b. Review available lists (from Step 1 output)\n  c. Choose appropriate list or use default:\n     - Work-related → \"Work\"\n     - Personal errands → \"Personal\" or default\n     - Shopping items → \"Shopping\"\n     - Project-specific → \"<ProjectName>\"\n  d. If list doesn't exist, it will be auto-created\n\nStep 3: Execute Operation\n--------------------------\nAdd task with appropriate options:\n  python3 scripts/ms-todo-oauth.py add \"Task Title\" \\\n    -l \"Work\" \\\n    -p high \\\n    -d 3 \\\n    -r 2h \\\n    -D \"Detailed description\" \\\n    -t \"tag1,tag2\"\n\nStep 4: Verify and Report\n--------------------------\nCheck exit code:\n  - 0: Success → Confirm to user\n  - 1: Failure → Parse error, provide guidance\n  - 2: Invalid args → Fix command syntax\n\nOptionally verify:\n  python3 scripts/ms-todo-oauth.py tasks \"<list>\"  # Show updated list"
      },
      {
        "title": "Task Title Matching Rules",
        "body": "Exact match required: complete, delete commands\nPartial/fuzzy match supported: detail, search commands\nCase-insensitive: All search operations\nBest practice: Use search first to find exact title, then use it in subsequent commands\n\nExample workflow:\n\n# Find task with fuzzy search\npython3 scripts/ms-todo-oauth.py search \"report\"\n# Output shows: \"Complete Q1 Report\"\n\n# Use exact title from search results\npython3 scripts/ms-todo-oauth.py complete \"Complete Q1 Report\" -l \"Work\""
      },
      {
        "title": "Default List Behavior",
        "body": "When -l is not specified, operations use the Microsoft To Do default list\nThe default list is typically named \"Tasks\" (English) or \"任务\" (Chinese)\nTo target a specific list, always provide -l \"<ListName>\""
      },
      {
        "title": "Example Task Categorization",
        "body": "User request: \"Add these tasks: buy milk, finish report, call dentist\"\n\nAgent approach:\n\n# First check available lists\npython3 scripts/ms-todo-oauth.py lists\n\n# Categorize intelligently:\npython3 scripts/ms-todo-oauth.py add \"Buy milk\" -l \"Shopping\"\npython3 scripts/ms-todo-oauth.py add \"Finish report\" -l \"Work\" -p high -d 2\npython3 scripts/ms-todo-oauth.py add \"Call dentist\" -l \"Personal\"\n# Or use default list if no specific context: add \"Call dentist\""
      },
      {
        "title": "Common Workflows",
        "body": "Daily task review:\n\npython3 scripts/ms-todo-oauth.py today          # Check today's tasks\npython3 scripts/ms-todo-oauth.py overdue        # Check overdue tasks\npython3 scripts/ms-todo-oauth.py -v pending -g  # Review all pending, grouped\n\nAdding various task types:\n\n# Simple task (default list)\npython3 scripts/ms-todo-oauth.py add \"Buy milk\"\n\n# Work task with priority and deadline\npython3 scripts/ms-todo-oauth.py add \"Quarterly review\" -l \"Work\" -p high -d 7\n\n# Task with reminder\npython3 scripts/ms-todo-oauth.py add \"Call client\" -r 3h\n\n# Detailed task with all options\npython3 scripts/ms-todo-oauth.py add \"Project meeting\" \\\n  -l \"Work\" \\\n  -p high \\\n  -d 2026-03-15 \\\n  -r \"2026-03-15 14:30\" \\\n  -D \"Discuss Q1 goals and resource allocation\" \\\n  -t \"meeting,important,Q1\"\n\n# Recurring tasks\npython3 scripts/ms-todo-oauth.py add \"Daily standup\" -R daily -l \"Work\"\npython3 scripts/ms-todo-oauth.py add \"Weekly review\" -R weekly -d 7\npython3 scripts/ms-todo-oauth.py add \"Gym\" -R weekdays -l \"Personal\"\npython3 scripts/ms-todo-oauth.py add \"Monthly report\" -R monthly -p high\n\nTask completion workflow:\n\n# Search for task\npython3 scripts/ms-todo-oauth.py search \"report\"\n\n# Complete using exact title from search results\npython3 scripts/ms-todo-oauth.py complete \"Quarterly review\" -l \"Work\"\n\nData management:\n\n# Export for backup\npython3 scripts/ms-todo-oauth.py export -o \"backup_$(date +%Y%m%d).json\"\n\n# View statistics\npython3 scripts/ms-todo-oauth.py stats"
      },
      {
        "title": "Version 1.1.0 (Current)",
        "body": "✅ Fixed: DateTime parsing errors (Microsoft's 7-decimal format)\n✅ Fixed: HTTP method parameter order bugs\n✅ Fixed: Missing start_date parameter in create_task()\n✅ Fixed: Missing complete_task() method\n✅ Fixed: Error exit codes now correctly return 1 on failure\n✅ Added: Comprehensive test suite (29 automated tests)\n✅ Added: Better error messages and troubleshooting\n✅ Improved: OAuth2 authentication flow documentation\n✅ Improved: Unicode and emoji support documentation\n✅ Improved: Agent usage guidelines"
      },
      {
        "title": "Version 1.0.2 (Previous)",
        "body": "Initial release with OAuth2 authentication\nBasic task and list management\nRecurring task support\nMultiple task views\nData export functionality"
      },
      {
        "title": "Authentication Issues",
        "body": "Problem: ❌ Not logged in\n\nSolution: Run login get, complete browser flow, then login verify <code>\n\nProblem: ❌ Token acquisition failed: invalid_grant\n\nCause: Authorization code already used or expired\nSolution: Run login get again to get a fresh code\n\nProblem: Login worked but now getting \"Not logged in\" again\n\nCause: Token expired and auto-refresh failed\nSolution: Run --reauth to force fresh login:\npython3 scripts/ms-todo-oauth.py --reauth lists"
      },
      {
        "title": "Import/Dependency Issues",
        "body": "Problem: ModuleNotFoundError: No module named 'msal'\n\nSolution: Install dependencies: pip install -r requirements.txt"
      },
      {
        "title": "API/Network Issues",
        "body": "Problem: Connection timeout or network errors\n\nCheck: Internet connection\nCheck: Can you access https://graph.microsoft.com in browser?\nTry: Using --debug flag to see full API request/response\n\nProblem: Unexpected API errors\n\nTry: Re-authenticate: python3 scripts/ms-todo-oauth.py --reauth lists\nTry: Debug mode: python3 scripts/ms-todo-oauth.py --debug <command>"
      },
      {
        "title": "Task/List Not Found",
        "body": "Problem: ❌ Task not found: <title>\n\nSolution: Use search to find exact title\nNote: complete and delete require exact title match\n\nProblem: ❌ List not found: <name>\n\nSolution: Run lists to see exact list names\nNote: List names are case-sensitive"
      },
      {
        "title": "Test Failures",
        "body": "Problem: Tests failing with datetime errors\n\nSolution: Ensure you've applied all v1.1.0 fixes\nCheck: Verify _parse_ms_datetime() helper function exists\n\nProblem: Tests failing with \"Not logged in\"\n\nSolution: Authenticate before running tests:\npython3 scripts/ms-todo-oauth.py login get\n# Complete browser flow\npython3 scripts/ms-todo-oauth.py login verify <code>\n# Then run tests\npython3 test_ms_todo_oauth.py"
      },
      {
        "title": "Additional Resources",
        "body": "Test Suite: test_ms_todo_oauth.py - Automated tests\nManual Tests: MANUAL_TEST_CHECKLIST.txt - Step-by-step testing guide\nQuick Reference: QUICK_REFERENCE.txt - Command cheat sheet\nBug Fixes: COMPLETE_FIX_PATCH.txt - Documentation of v1.1.0 fixes"
      },
      {
        "title": "Support & Contributing",
        "body": "Reporting Issues:\n\nProvide error message and command used\nInclude output from --debug flag if applicable\nNote your Python version: python3 --version\nNote your OS: Windows/Mac/Linux\n\nTesting New Features:\n\nAlways run the test suite after code changes\nAdd new test cases to test_ms_todo_oauth.py for new features\nUpdate MANUAL_TEST_CHECKLIST.txt with manual test procedures"
      },
      {
        "title": "License",
        "body": "MIT License - See LICENSE file for details\n\nVersion: 1.1.0\nLast Updated: 2026-02-13\nStatus: ✅ Fully Tested & Production Ready"
      }
    ],
    "body": "ms-todo-oauth\n\nA fully-tested Microsoft To Do command-line client for managing tasks and lists via Microsoft Graph API.\n\n⚠️This is a oauth based script. It contains a generated Azure Client ID and Secret ID\n\nIF YOU WORRIED ABOUT YOUR PRIVACY, CONSIDER REPLACING THEM TO YOUR OWN IN scripts\\ms-todo-oauth.py. Just search for values below:\n\nclient_id=\"ca6ec244……\n\nclient_secret=\"TwQ8Q……\n\n✨ Features\n✅ Full Task Management: Create, complete, delete, and search tasks\n🗂️ List Organization: Create and manage multiple task lists\n⏰ Rich Task Options: Priorities, due dates, reminders, descriptions, tags\n🔄 Recurring Tasks: Daily, weekly, monthly patterns with custom intervals\n📊 Multiple Views: Today, overdue, pending, statistics\n🔍 Powerful Search: Find tasks across all lists\n💾 Data Export: Export all tasks to JSON\n🧪 Fully Tested: 29 comprehensive automated tests\n🌐 Unicode Support: Full support for Chinese characters and emojis\nPrerequisites\nPython >= 3.9 must be installed\nWorking directory: All commands MUST be run from the root of this skill (the directory containing this SKILL.md file)\nNetwork access: Requires internet access to Microsoft Graph API endpoints\nMicrosoft Account: Personal Microsoft account (Hotmail, Outlook.com) or work/school account\nAuthentication: First-time use requires OAuth2 login via browser. See Authentication section\nToken cache: ~/.mstodo_token_cache.json (persists across sessions, auto-refreshed)\nInstallation & Setup\nFirst-Time Setup\n\nBefore using this skill for the first time, dependencies must be installed:\n\n# Navigate to skill directory\ncd <path-to-ms-todo-oauth>\n\n# Create a venv in the project (creates '.venv' folder)\npython3 -m venv .venv\n# Activate the venv choose based on platforms:\n#- Bash/Zsh: \nsource .venv/bin/activate\n# - Fish: \nsource .venv/bin/activate.fish\n#  - Windows (PowerShell):\n.venv\\Scripts\\Activate.ps1\n\npip install --upgrade pip\npip install -r requirements.txt\n\n# Alternative (global python env, not recommended):\n# pip install -r requirements.txt\n\n\nDependencies:\n\nmsal (Microsoft Authentication Library) - Official Microsoft OAuth library\nrequests - HTTP client for API calls\nSpecified in requirements.txt\nEnvironment Verification\n\nAfter installation, verify the setup:\n\n\n# If using native venv (activate as above):\npython3 scripts/ms-todo-oauth.py --help\n\n# Expected: Command help text should be displayed\n\n\nTroubleshooting:\n\nIf Python not found, install Python 3.9 or higher from https://python.org\nTesting (Optional but Recommended)\n\nVerify all functionality works correctly:\n\n# Run comprehensive automated test suite (29 tests)\npython3 test_ms_todo_oauth.py\n\n# Expected: All tests pass (100% pass rate)\n\n\nSee Testing section for details.\n\nSecurity Notes\nUses official Microsoft Graph API via Microsoft's msal library\nAll code is plain Python (.py files), readable and auditable\nTokens stored locally in ~/.mstodo_token_cache.json\nAll API calls go directly to Microsoft endpoints (graph.microsoft.com)\nOAuth2 standard authentication flow\nNo third-party services involved\nCommand Reference\n\nAll commands follow this pattern:\n\npython3 scripts/ms-todo-oauth.py [GLOBAL_OPTIONS] <command> [COMMAND_OPTIONS]\n\nGlobal Options\nOption\tDescription\n-v, --verbose\tShow detailed information (IDs, dates, notes).Must be placed BEFORE the subcommand.\n--debug\tEnable debug mode to display API requests and responses. Useful for troubleshooting.Must be placed BEFORE the subcommand.\n--reauth\tForce re-authentication by clearing the token cache and starting fresh login\n\n⚠️ Common mistake: Global options MUST come before the subcommand.\n\n✅ python3 scripts/ms-todo-oauth.py -v lists\n✅ python3 scripts/ms-todo-oauth.py --debug add \"Task\"\n❌ python3 scripts/ms-todo-oauth.py lists -v\nAuthentication\n\nAuthentication uses OAuth2 authorization code flow, designed for both interactive and automated environments.\n\nlogin get — Get OAuth2 authorization URL\npython3 scripts/ms-todo-oauth.py login get\n\n\nOutput example:\n\n======================================================================\n🔐 OAuth2 Authorization Required\n======================================================================\n\nPlease visit the following URL to authorize the application:\n\n  https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?...\n\nAfter authorization, you will be redirected to a callback URL.\nCopy the 'code' parameter from the callback URL and run:\n\n  ms-todo-oauth.py login verify <authorization_code>\n\n======================================================================\n\n\nWhat to do:\n\nOpen the provided URL in your browser\nSign in with your Microsoft account\nGrant permissions when prompted\nYou'll be redirected to a URL like: http://localhost:8000/callback?code=M.R3_BAY.abc123...\nCopy the entire code after code= (usually a long string starting with M.R3_BAY.)\n\nAgent behavior: Present the URL to the user and explain they need to:\n\nVisit the URL\nComplete the login\nCopy the authorization code from the callback URL\nProvide it to you\nlogin verify — Complete login with authorization code\npython3 scripts/ms-todo-oauth.py login verify <authorization_code>\n\n\nExample:\n\npython3 scripts/ms-todo-oauth.py login verify \"M.R3_BAY.abc123def456...\"\n\n\nOutput on success:\n\n✓ Authentication successful!\n✓ Login information saved, you will be logged in automatically next time.\n\n\nOutput on failure:\n\n❌ Token acquisition failed\nError: invalid_grant\nDescription: AADSTS54005: OAuth2 Authorization code was already redeemed...\n\n\nExit code: 0 on success, 1 on failure.\n\nImportant notes:\n\nEach authorization code can only be used ONCE\nIf verification fails, you need to run login get again to get a new code\nOnce successfully logged in, the token is cached and you won't need to login again unless:\nYou run logout\nYou run --reauth\nThe token expires and cannot be auto-refreshed\nlogout — Clear saved login\npython3 scripts/ms-todo-oauth.py logout\n\n\nOutput: ✓ Login information cleared\n\nOnly use when the user explicitly asks to switch accounts or clear login data. Under normal circumstances, the token is cached and login is automatic.\n\nList Management\nlists — List all task lists\npython3 scripts/ms-todo-oauth.py lists\npython3 scripts/ms-todo-oauth.py -v lists  # with IDs and creation dates\n\n\nOutput example:\n\n📋 Task Lists (3 total):\n\n1. 任务\n   ID: AQMkADAwATYwMAItYTQwZC04OThhLTAwAi0wMAoALgAAA0QJKpxW32BIsIlHaM...\n   Created: 2024-12-15T08:30:00Z\n2. Work\n3. Shopping\n\ncreate-list — Create a new list\npython3 scripts/ms-todo-oauth.py create-list \"<name>\"\n\nArgument\tRequired\tDescription\nname\tYes\tName of the new list (supports Unicode/Chinese)\n\nExample:\n\npython3 scripts/ms-todo-oauth.py create-list \"项目 A\"\n\n\nOutput: ✓ List created: 项目 A\n\ndelete-list — Delete a list\npython3 scripts/ms-todo-oauth.py delete-list \"<name>\" [-y]\n\nArgument/Option\tRequired\tDescription\nname\tYes\tName of the list to delete\n-y, --yes\tNo\tSkip confirmation prompt\n\n⚠️ This is a destructive operation. Without -y, the command will prompt for confirmation. All tasks in the list will be deleted. Consider asking the user before deleting important lists.\n\nOutput: ✓ List deleted: <name>\n\nExit code: 1 if list not found, 0 on success\n\nTask Operations\nadd — Add a new task\npython3 scripts/ms-todo-oauth.py add \"<title>\" [options]\n\nOption\tRequired\tDefault\tDescription\ntitle\tYes\t—\tTask title (positional argument, supports Unicode/Chinese/emojis)\n-l, --list\tNo\t(default list)\tTarget list name. If not specified, uses your Microsoft To Do default list.\n-p, --priority\tNo\tnormal\tPriority:low, normal, high\n-d, --due\tNo\t—\tDue date. Accepts days from now (3 or 3d) or date (2026-02-15). Note: Only date is supported by Microsoft To Do API, not time.\n-r, --reminder\tNo\t—\tReminder datetime. Formats:3h (hours from now), 2d (days from now), 2026-02-15 14:30 (date+time with space, needs quotes), 2026-02-15T14:30:00 (ISO format), 2026-02-15 (date only, defaults to 09:00).\n-R, --recurrence\tNo\t—\tRecurrence pattern. Formats:daily (every day), weekdays (Mon-Fri), weekly (every week), monthly (every month). With interval: daily:2 (every 2 days), weekly:3 (every 3 weeks), monthly:2 (every 2 months).\n-D, --description\tNo\t—\tTask description/notes (supports multiline with quotes)\n-t, --tags\tNo\t—\tComma-separated tags/categories (e.g.,\"work,urgent\")\n--create-list\tNo\tFalse\tCreate the list if it doesn't exist (deprecated, lists auto-create now)\n\nAuto-created lists: If the specified list doesn't exist, it will be automatically created.\n\nOutput example:\n\n✓ Task added: Complete report\n\n\nWith recurrence:\n\n✓ Task added: Daily standup\n🔄 Recurring task created\n\n\nExamples:\n\n# Simple task\npython3 scripts/ms-todo-oauth.py add \"Buy milk\" -l \"Shopping\"\n\n# High priority task due in 3 days\npython3 scripts/ms-todo-oauth.py add \"Submit report\" -l \"Work\" -p high -d 3\n\n# Task with reminder in 2 hours\npython3 scripts/ms-todo-oauth.py add \"Call client\" -r 2h\n\n# Task with specific date and time reminder\npython3 scripts/ms-todo-oauth.py add \"Meeting\" -d 2026-03-15 -r \"2026-03-15 14:30\"\n\n# Daily recurring task\npython3 scripts/ms-todo-oauth.py add \"Daily standup\" -l \"Work\" -R daily\n\n# Weekday recurring task  \npython3 scripts/ms-todo-oauth.py add \"Gym\" -R weekdays -l \"Personal\"\n\n# Task with all options\npython3 scripts/ms-todo-oauth.py add \"Project Review\" \\\n  -l \"Work\" \\\n  -p high \\\n  -d 7 \\\n  -r \"2026-02-20 14:00\" \\\n  -D \"Review Q1 deliverables and prepare presentation\" \\\n  -t \"work,important,meeting\"\n\n# Chinese task with emoji\npython3 scripts/ms-todo-oauth.py add \"🎉 完成项目\" -l \"任务\" -p high\n\ncomplete — Mark a task as completed\npython3 scripts/ms-todo-oauth.py complete \"<title>\" [-l \"<list>\"]\n\nOption\tRequired\tDefault\tDescription\ntitle\tYes\t—\tExact task title\n-l, --list\tNo\t(default list)\tList name where the task resides\n\nTitle matching: Requires exact match. If unsure of exact title, use search first.\n\nOutput: ✓ Task completed: <title>\n\nExit code: 1 if task not found, 0 on success\n\ndelete — Delete a task\npython3 scripts/ms-todo-oauth.py delete \"<title>\" [-l \"<list>\"] [-y]\n\nOption\tRequired\tDefault\tDescription\ntitle\tYes\t—\tExact task title\n-l, --list\tNo\t(default list)\tList name where the task resides\n-y, --yes\tNo\t—\tSkip confirmation prompt\n\n⚠️ Destructive operation. Without -y, will prompt for confirmation.\n\nOutput: ✓ Task deleted: <title>\n\nExit code: 1 if task not found, 0 on success\n\nTask Views\ntasks — List tasks in a specific list\npython3 scripts/ms-todo-oauth.py tasks \"<list>\" [-a]\n\nOption\tRequired\tDescription\nlist\tYes\tList name (exact match)\n-a, --all\tNo\tInclude completed tasks (default: incomplete only)\n\nOutput example:\n\n📋 Tasks in list \"Work\" (2 total):\n\n1. [In Progress] Write documentation ⭐\n2. [In Progress] Review PR\n\n\nWith -a flag:\n\n📋 Tasks in list \"Work\" (3 total):\n\n1. [In Progress] Write documentation ⭐\n2. [Completed] Submit report\n3. [In Progress] Review PR\n\n\nExit code: 1 if list not found, 0 on success\n\npending — All incomplete tasks across all lists\npython3 scripts/ms-todo-oauth.py pending [-g]\n\nOption\tRequired\tDescription\n-g, --group\tNo\tGroup results by list\n\nOutput example (with -g):\n\n📋 All incomplete tasks (3 total):\n\n📂 Work:\n  [In Progress] Write documentation ⭐\n  [In Progress] Review PR\n\n📂 Shopping:\n  [In Progress] Buy groceries\n\n\nWithout -g:\n\n📋 All incomplete tasks (3 total):\n\n[In Progress] Write documentation ⭐\n   List: Work\n[In Progress] Review PR\n   List: Work\n[In Progress] Buy groceries\n   List: Shopping\n\ntoday — Tasks due today\npython3 scripts/ms-todo-oauth.py today\n\n\nLists incomplete tasks with due date matching today's date.\n\nOutput example:\n\n📅 Tasks due today (2 total):\n\n[In Progress] Submit report ⭐\n   List: Work\n[In Progress] Buy groceries\n   List: Shopping\n\n\nIf no tasks: 📅 No tasks due today\n\noverdue — Overdue tasks\npython3 scripts/ms-todo-oauth.py overdue\n\n\nLists incomplete tasks past their due date, sorted by days overdue.\n\nOutput example:\n\n⚠️  Overdue tasks (1 total):\n\n[In Progress] Submit report ⭐\n   List: Work\n   Overdue: 3 days\n\n\nIf no overdue tasks: ✓ No overdue tasks\n\ndetail — View full task details\npython3 scripts/ms-todo-oauth.py detail \"<title>\" [-l \"<list>\"]\n\nOption\tRequired\tDefault\tDescription\ntitle\tYes\t—\tTask title (supportspartial/fuzzy match)\n-l, --list\tNo\t(default list)\tList name\n\nFuzzy matching: Matches tasks containing the search string (case-insensitive).\n\nWhen multiple tasks match:\n\nPrefers incomplete tasks over completed\nReturns most recently modified task\n\nOutput example:\n\n============================================================\n📌 Task Details\n============================================================\n\n📋 Title: Complete Q1 Report\n🔖 Status: [In Progress]\n⚡ Priority: ⭐ High\n📅 Created: 2026-01-15 08:30:00\n📝 Modified: 2026-02-10 14:22:00\n⏰ Due: 2026-02-20 00:00:00\n🔔 Reminder: 2026-02-20 09:00:00\n\n📝 Notes:\n- Review sales figures\n- Include charts\n- Prepare for board meeting\n\n🏷️  Categories: work, important, Q1\n\n🔄 Recurrence:\n   Every week on Monday\n   Start date: 2026-02-17\n   No end date\n\n============================================================\n\nsearch — Search tasks by keyword\npython3 scripts/ms-todo-oauth.py search \"<keyword>\"\n\n\nSearches across all lists in both task titles and descriptions (case-insensitive).\n\nOutput example:\n\n🔍 Search results for \"report\" (2 found):\n\n[In Progress] Complete Q1 Report ⭐\n   List: Work\n   Notes: Review sales figures...\n\n[Completed] Submit weekly report\n   List: Work\n\nstats — Task statistics\npython3 scripts/ms-todo-oauth.py stats\n\n\nShows aggregate statistics across all lists.\n\nOutput example:\n\n📊 Task Statistics:\n\n  Total lists: 3\n  Total tasks: 15\n  Completed: 10\n  Pending: 5\n  High priority: 2\n  Overdue: 1\n\n  Completion rate: 66.7%\n\nexport — Export all tasks to JSON\npython3 scripts/ms-todo-oauth.py export [-o \"<filename>\"]\n\nOption\tRequired\tDefault\tDescription\n-o, --output\tNo\ttodo_export.json\tOutput file path\n\nExports complete task data from all lists in JSON format.\n\nOutput: ✓ Tasks exported to: <filename>\n\nJSON structure:\n\n{\n  \"Work\": [\n    {\n      \"id\": \"AQMkADAwATYwMAItYTQw...\",\n      \"title\": \"Complete report\",\n      \"status\": \"notStarted\",\n      \"importance\": \"high\",\n      \"createdDateTime\": \"2026-01-15T08:30:00Z\",\n      \"dueDateTime\": {\n        \"dateTime\": \"2026-02-20T00:00:00.0000000\",\n        \"timeZone\": \"UTC\"\n      },\n      \"body\": {\n        \"content\": \"Review Q1 numbers\",\n        \"contentType\": \"text\"\n      },\n      \"categories\": [\"work\", \"important\"]\n    }\n  ],\n  \"Shopping\": [...]\n}\n\nError Handling\nExit Codes\nCode\tMeaning\n0\tSuccess\n1\tFailure (not logged in, API error, invalid arguments, resource not found)\n2\tInvalid command-line arguments\nCommon Error Messages\nError\tCause\tResolution\n❌ Not logged in\tNo cached token or token expired\tRun login get then login verify <code>\nModuleNotFoundError: No module named 'msal'\tDependencies not installed\tRun pip install -r requirements.txt\n❌ List not found: <name>\tSpecified list does not exist\tCheck list name with lists command. Note: exact match required.\n❌ Task not found: <name>\tNo task with exact matching title\tUse search to find exact title, or tasks \"<list>\" to list all tasks\n❌ Error: Invalid isoformat string\tDateTime parsing error\tThis should not occur in v1.1.0+. If you see this, report as bug.\n❌ Error: Unsupported HTTP method\tInternal API error\tThis should not occur in v1.1.0+. If you see this, report as bug.\n❌ Error: <API error message>\tMicrosoft Graph API error\tRetry; check network; use --debug for full details\nNetwork error / Connection timeout\tNo internet or API unreachable\tCheck network connection; verify access to graph.microsoft.com\nTesting\n\nThis skill includes a comprehensive test suite to ensure reliability.\n\nAutomated Testing\n\nRun the full test suite:\n\ncd <skill-directory>\npython3 test_ms_todo_oauth.py\n\n\nPrerequisites:\n\nMust be authenticated (logged in) before running tests\nInternet connection required\nApproximately 2-3 minutes to complete\n\nTest Coverage (29 tests):\n\n✅ Authentication (login/logout)\n✅ List management (create, delete, list)\n✅ Basic task operations (add, complete, delete, list)\n✅ Task options (priorities, due dates, reminders, descriptions, tags)\n✅ Recurring tasks (daily, weekly, weekdays, monthly, custom intervals)\n✅ Task views (today, overdue, pending, search, stats)\n✅ Data export and validation\n✅ Error handling (non-existent resources)\n✅ Unicode support (Chinese characters, emojis)\n\nExpected output:\n\n========================================================================\nTEST SUMMARY\n========================================================================\n\nTotal tests: 29\nPassed: 29\nFailed: 0\nPass rate: 100.0%\n\n========================================================================\n🎉 ALL TESTS PASSED! 🎉\n========================================================================\n\nManual Testing\n\nFor manual verification, see MANUAL_TEST_CHECKLIST.txt which provides:\n\nStep-by-step test procedures\nExpected outcomes\n9 test categories covering all functionality\nTest Cleanup\n\nThe automated test suite:\n\nCreates a temporary test list (e.g., 🧪 Test List 14:23:45)\nRuns all tests in isolation\nDeletes the test list on completion\nCleans up any temporary files\n\nIf tests are interrupted, you may need to manually delete leftover test lists.\n\nAgent Usage Guidelines\nCritical Rules\n\nWorking directory: Always cd to the directory containing this SKILL.md before running commands.\n\nDependency installation: Before first use or when encountering import errors, ensure all dependencies are installed.\n\nCheck authentication first: Before any operation, verify authentication status:\n\npython3 scripts/ms-todo-oauth.py lists\n\n\nIf this returns \"Not logged in\" error (exit code 1), initiate the login flow.\n\nTask list organization: When adding tasks:\n\nFirst, run lists to see available task lists\nIf user doesn't specify a list, tasks will be added to their default list (usually \"Tasks\" or \"任务\")\nIntelligently categorize tasks into appropriate lists:\nWork tasks → \"Work\" list\nPersonal errands → \"Personal\" or default list\nShopping → \"Shopping\" list\nProject-specific → Use project name as list\nLists will be auto-created if they don't exist\nSupport Chinese list names and Unicode characters\n\nDestructive operations: For delete and delete-list:\n\nThese commands prompt for confirmation by default (blocking behavior)\nUse -y flag ONLY when:\nUser has explicitly requested to delete without confirmation\nThe deletion intent is unambiguous and confirmed through conversation\nWhen in doubt, ask the user for confirmation instead of using -y\nThese operations return exit code 1 on failure (resource not found)\n\nGlobal option placement: -v, --debug, and --reauth must come BEFORE the subcommand:\n\n✅ python3 scripts/ms-todo-oauth.py -v lists\n❌ python3 scripts/ms-todo-oauth.py lists -v\n\nLogin flow:\n\nDo NOT call login verify until user confirms they've completed browser authentication\nEach authorization code can only be used once\nIf verify fails, you must run login get again for a new code\n\nError handling:\n\nCheck exit codes: 0 = success, 1 = failure, 2 = invalid arguments\nParse error messages to provide helpful guidance\nUse --debug flag when troubleshooting API issues\nRecommended Workflow for Agents\nStep 1: Setup and Authentication Check\n---------------------------------------\ncd <skill_directory>\n\npython3 scripts/ms-todo-oauth.py lists          # Test auth & see available lists\n\nIf exit code is 1 and output contains \"Not logged in\":\n  a. python3 scripts/ms-todo-oauth.py login get\n  b. Present URL to user\n  c. Explain: \"Visit this URL, login, and copy the 'code' parameter from callback URL\"\n  d. Wait for user to provide authorization code\n  e. python3 scripts/ms-todo-oauth.py login verify \"<code>\"\n  f. Verify success (exit code 0)\n\nStep 2: Task Analysis and List Selection\n-----------------------------------------\nWhen user requests to add task(s):\n  a. Analyze task context from user's description\n  b. Review available lists (from Step 1 output)\n  c. Choose appropriate list or use default:\n     - Work-related → \"Work\"\n     - Personal errands → \"Personal\" or default\n     - Shopping items → \"Shopping\"\n     - Project-specific → \"<ProjectName>\"\n  d. If list doesn't exist, it will be auto-created\n\nStep 3: Execute Operation\n--------------------------\nAdd task with appropriate options:\n  python3 scripts/ms-todo-oauth.py add \"Task Title\" \\\n    -l \"Work\" \\\n    -p high \\\n    -d 3 \\\n    -r 2h \\\n    -D \"Detailed description\" \\\n    -t \"tag1,tag2\"\n\nStep 4: Verify and Report\n--------------------------\nCheck exit code:\n  - 0: Success → Confirm to user\n  - 1: Failure → Parse error, provide guidance\n  - 2: Invalid args → Fix command syntax\n\nOptionally verify:\n  python3 scripts/ms-todo-oauth.py tasks \"<list>\"  # Show updated list\n\nTask Title Matching Rules\nExact match required: complete, delete commands\nPartial/fuzzy match supported: detail, search commands\nCase-insensitive: All search operations\nBest practice: Use search first to find exact title, then use it in subsequent commands\n\nExample workflow:\n\n# Find task with fuzzy search\npython3 scripts/ms-todo-oauth.py search \"report\"\n# Output shows: \"Complete Q1 Report\"\n\n# Use exact title from search results\npython3 scripts/ms-todo-oauth.py complete \"Complete Q1 Report\" -l \"Work\"\n\nDefault List Behavior\nWhen -l is not specified, operations use the Microsoft To Do default list\nThe default list is typically named \"Tasks\" (English) or \"任务\" (Chinese)\nTo target a specific list, always provide -l \"<ListName>\"\nExample Task Categorization\n\nUser request: \"Add these tasks: buy milk, finish report, call dentist\"\n\nAgent approach:\n\n# First check available lists\npython3 scripts/ms-todo-oauth.py lists\n\n# Categorize intelligently:\npython3 scripts/ms-todo-oauth.py add \"Buy milk\" -l \"Shopping\"\npython3 scripts/ms-todo-oauth.py add \"Finish report\" -l \"Work\" -p high -d 2\npython3 scripts/ms-todo-oauth.py add \"Call dentist\" -l \"Personal\"\n# Or use default list if no specific context: add \"Call dentist\"\n\nQuick Reference\nCommon Workflows\n\nDaily task review:\n\npython3 scripts/ms-todo-oauth.py today          # Check today's tasks\npython3 scripts/ms-todo-oauth.py overdue        # Check overdue tasks\npython3 scripts/ms-todo-oauth.py -v pending -g  # Review all pending, grouped\n\n\nAdding various task types:\n\n# Simple task (default list)\npython3 scripts/ms-todo-oauth.py add \"Buy milk\"\n\n# Work task with priority and deadline\npython3 scripts/ms-todo-oauth.py add \"Quarterly review\" -l \"Work\" -p high -d 7\n\n# Task with reminder\npython3 scripts/ms-todo-oauth.py add \"Call client\" -r 3h\n\n# Detailed task with all options\npython3 scripts/ms-todo-oauth.py add \"Project meeting\" \\\n  -l \"Work\" \\\n  -p high \\\n  -d 2026-03-15 \\\n  -r \"2026-03-15 14:30\" \\\n  -D \"Discuss Q1 goals and resource allocation\" \\\n  -t \"meeting,important,Q1\"\n\n# Recurring tasks\npython3 scripts/ms-todo-oauth.py add \"Daily standup\" -R daily -l \"Work\"\npython3 scripts/ms-todo-oauth.py add \"Weekly review\" -R weekly -d 7\npython3 scripts/ms-todo-oauth.py add \"Gym\" -R weekdays -l \"Personal\"\npython3 scripts/ms-todo-oauth.py add \"Monthly report\" -R monthly -p high\n\n\nTask completion workflow:\n\n# Search for task\npython3 scripts/ms-todo-oauth.py search \"report\"\n\n# Complete using exact title from search results\npython3 scripts/ms-todo-oauth.py complete \"Quarterly review\" -l \"Work\"\n\n\nData management:\n\n# Export for backup\npython3 scripts/ms-todo-oauth.py export -o \"backup_$(date +%Y%m%d).json\"\n\n# View statistics\npython3 scripts/ms-todo-oauth.py stats\n\nChangelog\nVersion 1.1.0 (Current)\n✅ Fixed: DateTime parsing errors (Microsoft's 7-decimal format)\n✅ Fixed: HTTP method parameter order bugs\n✅ Fixed: Missing start_date parameter in create_task()\n✅ Fixed: Missing complete_task() method\n✅ Fixed: Error exit codes now correctly return 1 on failure\n✅ Added: Comprehensive test suite (29 automated tests)\n✅ Added: Better error messages and troubleshooting\n✅ Improved: OAuth2 authentication flow documentation\n✅ Improved: Unicode and emoji support documentation\n✅ Improved: Agent usage guidelines\nVersion 1.0.2 (Previous)\nInitial release with OAuth2 authentication\nBasic task and list management\nRecurring task support\nMultiple task views\nData export functionality\nTroubleshooting\nAuthentication Issues\n\nProblem: ❌ Not logged in\n\nSolution: Run login get, complete browser flow, then login verify <code>\n\nProblem: ❌ Token acquisition failed: invalid_grant\n\nCause: Authorization code already used or expired\nSolution: Run login get again to get a fresh code\n\nProblem: Login worked but now getting \"Not logged in\" again\n\nCause: Token expired and auto-refresh failed\nSolution: Run --reauth to force fresh login:\npython3 scripts/ms-todo-oauth.py --reauth lists\n\nImport/Dependency Issues\n\nProblem: ModuleNotFoundError: No module named 'msal'\n\nSolution: Install dependencies: pip install -r requirements.txt\nAPI/Network Issues\n\nProblem: Connection timeout or network errors\n\nCheck: Internet connection\nCheck: Can you access https://graph.microsoft.com in browser?\nTry: Using --debug flag to see full API request/response\n\nProblem: Unexpected API errors\n\nTry: Re-authenticate: python3 scripts/ms-todo-oauth.py --reauth lists\nTry: Debug mode: python3 scripts/ms-todo-oauth.py --debug <command>\nTask/List Not Found\n\nProblem: ❌ Task not found: <title>\n\nSolution: Use search to find exact title\nNote: complete and delete require exact title match\n\nProblem: ❌ List not found: <name>\n\nSolution: Run lists to see exact list names\nNote: List names are case-sensitive\nTest Failures\n\nProblem: Tests failing with datetime errors\n\nSolution: Ensure you've applied all v1.1.0 fixes\nCheck: Verify _parse_ms_datetime() helper function exists\n\nProblem: Tests failing with \"Not logged in\"\n\nSolution: Authenticate before running tests:\npython3 scripts/ms-todo-oauth.py login get\n# Complete browser flow\npython3 scripts/ms-todo-oauth.py login verify <code>\n# Then run tests\npython3 test_ms_todo_oauth.py\n\nAdditional Resources\nTest Suite: test_ms_todo_oauth.py - Automated tests\nManual Tests: MANUAL_TEST_CHECKLIST.txt - Step-by-step testing guide\nQuick Reference: QUICK_REFERENCE.txt - Command cheat sheet\nBug Fixes: COMPLETE_FIX_PATCH.txt - Documentation of v1.1.0 fixes\nSupport & Contributing\n\nReporting Issues:\n\nProvide error message and command used\nInclude output from --debug flag if applicable\nNote your Python version: python3 --version\nNote your OS: Windows/Mac/Linux\n\nTesting New Features:\n\nAlways run the test suite after code changes\nAdd new test cases to test_ms_todo_oauth.py for new features\nUpdate MANUAL_TEST_CHECKLIST.txt with manual test procedures\nLicense\n\nMIT License - See LICENSE file for details\n\nVersion: 1.1.0 Last Updated: 2026-02-13 Status: ✅ Fully Tested & Production Ready"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/nathanatgit/ms-todo-oauth",
    "publisherUrl": "https://clawhub.ai/nathanatgit/ms-todo-oauth",
    "owner": "nathanatgit",
    "version": "1.0.4",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/ms-todo-oauth",
    "downloadUrl": "https://openagent3.xyz/downloads/ms-todo-oauth",
    "agentUrl": "https://openagent3.xyz/skills/ms-todo-oauth/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ms-todo-oauth/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ms-todo-oauth/agent.md"
  }
}