docs: add custom task ID documentation

Author: krodak

README.md

@@ -307,6 +307,23 @@ Environment variables override config file values:
 
 When both are set, the config file is not required. Useful for CI/CD and containerized agents.
 
+## Custom Task IDs
+
+ClickUp workspaces can configure custom task IDs with a prefix per space (e.g., `PROJ-123`, `DEV-42`). The CLI detects these automatically - any ID matching the `PREFIX-DIGITS` format (uppercase letters, hyphen, digits) is treated as a custom task ID.
+
+All commands that accept task IDs work with both native IDs and custom IDs:
+
+```bash
+cu task PROJ-123
+cu update DEV-42 --status done
+cu comment PROJ-456 -m "Fixed in latest commit"
+cu subtasks DEV-100
+```
+
+Custom ID resolution uses the `teamId` from your config, which is required (`cu init` sets it up).
+
+**Task links with custom IDs:** The `cu link` command passes both task IDs in a single API request. When both IDs are custom, this works correctly. However, mixing custom and native IDs in a single link command may not work as expected because the ClickUp API applies the `custom_task_ids` flag to all IDs in the request.
+
 ## Why a CLI and not MCP?
 
 A CLI + skill file has fewer moving parts. No server process, no protocol layer. The agent already knows how to run shell commands - the skill file teaches it which ones exist. For tool-use with coding agents, CLI + instructions tends to work better than MCP in practice.

skills/clickup-cli/SKILL.md

@@ -94,7 +94,7 @@ All commands support `--help` for full flag details.
 
 | Topic                     | Detail                                                                                                 |
 | ------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Task IDs                  | Stable alphanumeric strings (e.g. `abc123def`)                                                         |
+| Task IDs                  | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format        |
 | `--type`                  | Filter by task type: `task` (regular), or custom type name/ID (e.g. `initiative`, `Bug`)               |
 | `--list` on create        | Optional when `--parent` is given (auto-detected)                                                      |
 | `--status`                | Fuzzy matching: exact > starts-with > contains. Prints match to stderr.                                |
@@ -124,6 +124,8 @@ All commands support `--help` for full flag details.
 | `cu comment-edit`         | Edit comment text and resolution status                                                                |
 | `cu comment-delete`       | Delete a comment                                                                                       |
 | `cu replies` / `cu reply` | View and post threaded comment replies                                                                 |
+| Custom task IDs           | Auto-detected by format (`PROJ-123`). Uses `teamId` from config. All commands support them             |
+| `cu link` + custom IDs    | Both IDs must be the same type (both custom or both native). Mixing may not work                       |
 | `cu link`                 | Link/unlink tasks (different from dependencies)                                                        |
 | `cu attach`               | Upload files to tasks. Attachments shown in `cu task` detail view                                      |
 | `cu task`                 | Shows custom fields, checklists, and attachments in detail view                                        |