@doist/twist-cli 2.31.2 → 2.32.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [2.32.0](https://github.com/Doist/twist-cli/compare/v2.31.2...v2.32.0) (2026-04-19)
+
+### Features
+
+- **skill:** align with agentskills.io spec and validate in CI ([#179](https://github.com/Doist/twist-cli/issues/179)) ([4fda70e](https://github.com/Doist/twist-cli/commit/4fda70e9812f2e8db443decc7a8a6c71d77043c1))
+
 ## [2.31.2](https://github.com/Doist/twist-cli/compare/v2.31.1...v2.31.2) (2026-04-16)
 
 ### Bug Fixes

package/dist/lib/skills/content.d.ts

@@ -1,5 +1,8 @@
 export declare const SKILL_NAME = "twist-cli";
-export declare const SKILL_DESCRIPTION = "Twist messaging CLI for team communication";
+export declare const SKILL_DESCRIPTION = "Twist messaging CLI. View and respond to inbox threads, channel threads, direct messages, and group conversations; search, react, archive, mute, and manage workspaces. Use when the user mentions Twist, asks about their inbox, threads, DMs, channels, or wants to read or send Twist messages.";
+export declare const SKILL_AUTHOR = "Doist";
+export declare const SKILL_LICENSE = "MIT";
+export declare const SKILL_VERSION: string;
 export declare const SKILL_CONTENT = "# Twist CLI (tw)\n\nAccess Twist messaging via the `tw` CLI. Use when the user asks about their Twist workspaces, threads, messages, or wants to interact with Twist in any way.\n\n## Setup\n\n```bash\ntw auth login                    # OAuth login (opens browser, read-write)\ntw auth login --read-only        # OAuth login with read-only scope\ntw auth token                    # Save API token manually (prompts securely; scope unknown, assumed write-capable)\ntw auth status                   # Verify authentication + show mode\ntw auth status --json            # JSON output: { id, email, name }\ntw auth logout                   # Remove saved token and auth metadata\ntw workspaces                    # List available workspaces\ntw workspace use <ref>           # Set current workspace\ntw completion install            # Install shell completions\ntw doctor                        # Diagnose CLI setup and environment issues\ntw update                        # Update CLI to latest version\ntw changelog                     # Show recent changelog entries\n```\n\nStored auth uses the system credential manager when available. If secure storage is unavailable, `tw` warns and falls back to `~/.config/twist-cli/config.json`. `TWIST_API_TOKEN` always takes priority over the stored token, and legacy plaintext config tokens are migrated automatically when secure storage is available.\n\nIn read-only mode (`tw auth login --read-only`), commands that modify Twist data (reply, archive, react, delete, etc.) are blocked by the CLI. Externally provided tokens (`TWIST_API_TOKEN` or `tw auth token`) are treated as unknown scope and assumed write-capable.\n\n## View by URL\n\n```bash\ntw view <url>                    # View any Twist entity by URL\n```\n\nRoutes automatically based on URL structure:\n- Message URL \u2192 `tw msg view`\n- Conversation URL \u2192 `tw conversation view`\n- Thread+comment URL \u2192 `tw thread view` (comment ID extracted from URL)\n- Thread URL \u2192 `tw thread view`\n\nAll target command flags pass through (e.g. `--json`, `--raw`, `--full`).\n\n## Inbox\n\n```bash\ntw inbox                         # Show inbox threads\ntw inbox --unread                # Only unread threads\ntw inbox --archive-filter all      # Show active + done threads\ntw inbox --archive-filter archived # Show only done threads\ntw inbox --channel <filter>      # Filter by channel name (fuzzy)\ntw inbox --since <date>          # Filter by date (ISO format)\ntw inbox --limit <n>             # Max items (default: 50)\n```\n\n## Threads\n\n```bash\ntw thread <thread-ref>           # View thread (shorthand for view)\ntw thread view <thread-ref>      # View thread with comments\ntw thread view <ref> --comment <id> # View a specific comment\ntw thread view <url-with-/c/id>  # Comment ID extracted from URL\ntw thread view <ref> --unread    # Show only unread comments\ntw thread view <ref> --context 3 # Include 3 read comments before unread\ntw thread view <ref> --limit 20  # Limit number of comments\ntw thread view <ref> --since <date> # Comments newer than date\ntw thread view <ref> --raw       # Show raw markdown\ntw thread create <channel-ref> \"Title\" \"content\"    # Create a new thread\ntw thread create <channel-ref> \"Title\" \"content\" --json       # Create and return as JSON\ntw thread create <channel-ref> \"Title\" \"content\" --json --full # Include all thread fields\ntw thread create <channel-ref> \"Title\" \"content\" --notify 123,456  # Notify specific users\ntw thread create <channel-ref> \"Title\" \"content\" --dry-run  # Preview without posting\ntw thread reply <ref> \"content\"  # Post a comment (notifies EVERYONE_IN_THREAD by default)\ntw thread reply <ref> \"content\" --notify EVERYONE  # Notify all workspace members\ntw thread reply <ref> \"content\" --notify 123,id:456   # Notify specific user IDs\ntw thread reply <ref> \"content\" --json  # Post and return comment as JSON\ntw thread reply <ref> \"content\" --json --full  # Include all comment fields\ntw thread reply <ref> \"content\" --close       # Reply and close the thread\ntw thread reply <ref> \"content\" --reopen      # Reply and reopen a closed thread\ntw thread done <ref>             # Archive thread (mark done)\ntw thread done <ref> --json      # Archive and return status as JSON\ntw thread mute <ref>             # Mute thread for 60 minutes (default)\ntw thread mute <ref> --minutes 480  # Mute for custom duration\ntw thread mute <ref> --json      # Mute and return { id, mutedUntil } as JSON\ntw thread mute <ref> --json --full  # Mute and return full thread as JSON\ntw thread unmute <ref>           # Unmute a muted thread\ntw thread unmute <ref> --json    # Unmute and return { id, mutedUntil } as JSON\ntw thread delete <ref>             # Preview thread deletion (requires --yes to execute)\ntw thread delete <ref> --yes       # Permanently delete a thread\ntw thread delete <ref> --yes --json # Delete and return status as JSON\ntw thread rename <ref> \"New title\"  # Rename a thread (change its title)\ntw thread rename <ref> \"New title\" --json  # Rename and return { id, title } as JSON\ntw thread rename <ref> \"New title\" --json --full  # Rename and return full thread as JSON\ntw thread update <ref> \"New body\"   # Update a thread's body (the first post)\necho \"New body\" | tw thread update <ref>  # Update body from stdin\ntw thread update <ref> \"New body\" --dry-run  # Preview without updating\ntw thread update <ref> \"New body\" --json  # Update and return { id, content } as JSON\ntw thread update <ref> \"New body\" --json --full  # Update and return full thread as JSON\n```\n\nDefault `--notify` for reply is EVERYONE_IN_THREAD, which may notify more people than intended. Before posting, confirm with the user whether specific people should be notified instead (via `--notify <user-ids>`). Options: EVERYONE, EVERYONE_IN_THREAD, or comma-separated ID refs.\n\n`--notify` automatically resolves IDs: group IDs are routed to the `groups` API field, user IDs to `recipients`. No special syntax needed.\n\n## Thread Comments\n\n```bash\ntw comment <comment-ref>                       # View a comment (shorthand for view)\ntw comment view <comment-ref>                  # View a single thread comment\ntw comment view <comment-ref> --raw            # Show raw markdown\ntw comment view <comment-ref> --json           # Output as JSON\ntw comment view <comment-ref> --ndjson         # Output as newline-delimited JSON\ntw comment view <comment-ref> --json --full    # Include all fields in JSON output\ntw comment update <comment-ref> \"new content\"  # Update a thread comment\ntw comment update <comment-ref> \"content\" --json  # Update and return updated comment as JSON\ntw comment update <comment-ref> \"content\" --json --full  # Include all comment fields\ntw comment delete <comment-ref>                # Delete a thread comment\ntw comment delete <comment-ref> --json         # Delete and return status as JSON\n```\n\n## Conversations (DMs/Groups)\n\n```bash\ntw conversation unread                    # List unread conversations\ntw conversation <conversation-ref>        # View conversation (shorthand for view)\ntw conversation view <conversation-ref>   # View conversation messages\ntw conversation with <user-ref>           # Find your 1:1 DM with a user\ntw conversation with <user-ref> --snippet # Include the latest message preview\ntw conversation with <user-ref> --include-groups # List any conversations with that user\ntw conversation reply <ref> \"content\"     # Send a message\ntw conversation reply <ref> \"content\" --json  # Send and return message as JSON\ntw conversation reply <ref> \"content\" --json --full  # Include all message fields\ntw conversation done <ref>                # Archive conversation\ntw conversation done <ref> --json         # Archive and return status as JSON\ntw conversation mute <ref>               # Mute conversation for 60 minutes (default)\ntw conversation mute <ref> --minutes 480 # Mute for custom duration\ntw conversation mute <ref> --json        # Mute and return { id, mutedUntil } as JSON\ntw conversation mute <ref> --json --full # Mute and return full conversation as JSON\ntw conversation unmute <ref>             # Unmute a muted conversation\ntw conversation unmute <ref> --json      # Unmute and return { id, mutedUntil } as JSON\n```\n\nAlias: `tw convo` works the same as `tw conversation`.\n\n## Conversation Messages\n\n```bash\ntw msg <message-ref>             # View a message (shorthand for view)\ntw msg view <message-ref>        # View a single conversation message\ntw msg update <ref> \"content\"    # Edit a conversation message\ntw msg update <ref> \"content\" --json  # Edit and return updated message as JSON\ntw msg update <ref> \"content\" --json --full  # Include all message fields\ntw msg delete <ref>              # Delete a conversation message\ntw msg delete <ref> --json       # Delete and return status as JSON\n```\n\nAlias: `tw message` works the same as `tw msg`.\n\n## Search\n\n```bash\ntw search \"query\"                # Search content\ntw search \"query\" --type threads # Filter: threads, messages, or all\ntw search \"query\" --author <ref> # Filter by author\ntw search \"query\" --to <ref>     # Messages sent to user\ntw search \"query\" --title-only   # Search thread titles only\ntw search \"query\" --mention-me   # Results mentioning current user\ntw search \"query\" --conversation <refs> # Limit to conversations (comma-separated refs)\ntw search \"query\" --since <date> # Content from date\ntw search \"query\" --until <date> # Content until date\ntw search \"query\" --channel <refs> # Filter by channel refs (comma-separated)\ntw search \"query\" --limit <n>    # Max results (default: 50)\ntw search \"query\" --cursor <cur> # Pagination cursor\n```\n\n## Users, Channels & Groups\n\n```bash\ntw user                          # Show current user info\ntw user --json                   # JSON output\ntw user --json --full            # Include all fields in JSON output\ntw users                         # List workspace users\ntw users --search <text>         # Filter by name/email\ntw channels                      # List active joined workspace channels\ntw channels --state all          # Include archived joined channels too\ntw channels --scope discoverable # Active public channels you can see but have not joined\ntw channels --scope public --state all --json # All visible public channels, with joined status\ntw groups                        # List workspace groups\ntw groups --search \"frontend\"    # Filter groups by name (case-insensitive)\ntw groups --json                 # JSON output\ntw groups --json --full          # Include all fields in JSON output\n```\n\nIf a channel is not found in `tw channels`, widen with broader listings such as `tw channels --scope public`, then `tw channels --scope public --state all`. Check `tw channels --help` for other available filters.\n\n## Away Status\n\n```bash\ntw away                          # Show current away status\ntw away set <type> [until]       # Set away (type: vacation, parental, sickleave, other)\ntw away set vacation 2026-03-20  # Away until March 20\ntw away set vacation 2026-03-20 --from 2026-03-15  # Custom start date\ntw away clear                    # Clear away status\n```\n\n## Reactions\n\n```bash\ntw react thread <ref> \uD83D\uDC4D         # Add reaction to thread\ntw react comment <ref> +1        # Add reaction (shortcode)\ntw react message <ref> heart     # Add reaction to DM message\ntw react thread <ref> \uD83D\uDC4D --json  # Output result as JSON\ntw unreact thread <ref> \uD83D\uDC4D       # Remove reaction\ntw unreact thread <ref> \uD83D\uDC4D --json # Output result as JSON\n```\n\nSupported shortcodes: +1, -1, heart, tada, smile, laughing, thinking, fire, check, x, eyes, pray, clap, rocket, wave\n\n## Shell Completions\n\n```bash\ntw completion install            # Install tab completions (prompts for shell)\ntw completion install bash       # Install for specific shell\ntw completion install zsh\ntw completion install fish\ntw completion uninstall          # Remove completions\n```\n\n### Diagnostics\n\n```bash\ntw doctor                        # Run local + network diagnostics\ntw doctor --offline              # Skip Twist and npm network checks\ntw doctor --json                 # JSON output with per-check results\n```\n\n### Update\n\n```bash\ntw update                        # Update CLI to latest version\ntw update --check                # Check for updates without installing, show channel\ntw update --channel              # Show current update channel\ntw update switch --stable        # Switch to stable release channel\ntw update switch --pre-release   # Switch to pre-release (next) channel\n```\n\n### Changelog\n```bash\ntw changelog                     # Show last 5 versions\ntw changelog -n 3                # Show last 3 versions\ntw changelog --count 10          # Show last 10 versions\n```\n\n## Global Options\n\n```bash\n--no-spinner       # Disable loading animations\n--progress-jsonl   # Machine-readable progress events (JSONL to stderr)\n--accessible       # Add text labels to color-coded output (also: TW_ACCESSIBLE=1)\n--non-interactive  # Disable interactive prompts (auto-detected when stdin is not a TTY)\n--interactive      # Force interactive mode even when stdin is not a TTY\n```\n\n## Output Formats\n\nAll list/view commands support:\n\n```bash\n--json    # Output as JSON\n--ndjson  # Output as newline-delimited JSON (for streaming)\n--full    # Include all fields (default shows essential fields only)\n```\n\n## Dry Run\n\nMutating commands accept `--dry-run` to preview the operation without making the change. Where a command performs pre-flight validation (e.g. fetching the target thread to check channel access or ownership), those checks still run in dry-run \u2014 only the mutating write is skipped. Commands that have no pre-flight validation parse the reference and print the preview without hitting the API. The preview is structured:\n\n```\n[dry-run] Would <action>:\n  <Key>: <resolved value>\n  ...\nRun without --dry-run to execute.\n```\n\n## Reference System\n\nCommands accept flexible references:\n- **Numeric IDs**: `123` or `id:123`\n- **Twist URLs**: Full `https://twist.com/...` URLs (parsed automatically)\n- **Fuzzy names**: For workspaces/users - `\"My Workspace\"` or partial matches\n\n## Piping Content\n\nCommands that accept content (`thread create`, `thread reply`, `comment update`, `conversation reply`, `msg update`) auto-detect piped stdin:\n\n```bash\ncat notes.md | tw thread reply <ref>\ntw thread create <channel-ref> \"Title\" < body.md\necho \"Quick reply\" | tw conversation reply <ref>\n```\n\nIf no content argument is provided and no stdin is piped, the CLI opens `$EDITOR` for interactive input. In non-TTY environments (e.g. when called by an agent or in a pipeline), the editor is automatically skipped and the command fails fast with an actionable error message. Use `--non-interactive` to force this behavior even in a TTY, or `--interactive` to override auto-detection.\n\n## Common Workflows\n\n**View by URL (auto-routes to the right command):**\n```bash\ntw view https://twist.com/a/1585/ch/100/t/200          # View thread\ntw view https://twist.com/a/1585/ch/100/t/200/c/300     # View comment\ntw view https://twist.com/a/1585/msg/400                 # View conversation\ntw view https://twist.com/a/1585/msg/400/m/500 --json    # View message as JSON\n```\n\n**Check inbox and respond:**\n```bash\ntw inbox --unread --json\ntw thread view <id> --unread\ntw thread reply <id> \"Thanks, I'll look into this.\"\ntw thread done <id>\n```\n\n**Search and review:**\n```bash\ntw search \"deployment\" --type threads --json\ntw thread view <thread-id>\n```\n\n**Check DMs:**\n```bash\ntw conversation unread --json\ntw conversation view <conversation-id>\ntw conversation with \"Alice Example\"\ntw conversation reply <id> \"Got it, thanks!\"\n```\n";
 export declare const SKILL_FILE_CONTENT: string;
 //# sourceMappingURL=content.d.ts.map

package/dist/lib/skills/content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/content.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,cAAc,CAAA;AAErC,eAAO,MAAM,iBAAiB,+CAA+C,CAAA;AAE7E,eAAO,MAAM,aAAa,8rfA0UzB,CAAA;AAED,eAAO,MAAM,kBAAkB,QAKd,CAAA"}
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/content.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,cAAc,CAAA;AAErC,eAAO,MAAM,iBAAiB,uSAC0Q,CAAA;AAExS,eAAO,MAAM,YAAY,UAAU,CAAA;AAEnC,eAAO,MAAM,aAAa,QAAQ,CAAA;AAElC,eAAO,MAAM,aAAa,QAAsB,CAAA;AAEhD,eAAO,MAAM,aAAa,8rfA0UzB,CAAA;AAED,eAAO,MAAM,kBAAkB,QASd,CAAA"}

package/dist/lib/skills/content.js

@@ -1,5 +1,9 @@
+import packageJson from '../../../package.json' with { type: 'json' };
 export const SKILL_NAME = 'twist-cli';
-export const SKILL_DESCRIPTION = 'Twist messaging CLI for team communication';
+export const SKILL_DESCRIPTION = 'Twist messaging CLI. View and respond to inbox threads, channel threads, direct messages, and group conversations; search, react, archive, mute, and manage workspaces. Use when the user mentions Twist, asks about their inbox, threads, DMs, channels, or wants to read or send Twist messages.';
+export const SKILL_AUTHOR = 'Doist';
+export const SKILL_LICENSE = 'MIT';
+export const SKILL_VERSION = packageJson.version;
 export const SKILL_CONTENT = `# Twist CLI (tw)
 
 Access Twist messaging via the \`tw\` CLI. Use when the user asks about their Twist workspaces, threads, messages, or wants to interact with Twist in any way.
@@ -334,6 +338,10 @@ tw conversation reply <id> "Got it, thanks!"
 export const SKILL_FILE_CONTENT = `---
 name: ${SKILL_NAME}
 description: ${JSON.stringify(SKILL_DESCRIPTION)}
+license: ${SKILL_LICENSE}
+metadata:
+  author: ${SKILL_AUTHOR}
+  version: ${JSON.stringify(SKILL_VERSION)}
 ---
 
 ${SKILL_CONTENT}`;

package/dist/lib/skills/content.js.map

@@ -1 +1 @@
-{"version":3,"file":"content.js","sourceRoot":"","sources":["../../../src/lib/skills/content.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CAAA;AAErC,MAAM,CAAC,MAAM,iBAAiB,GAAG,4CAA4C,CAAA;AAE7E,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0U5B,CAAA;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG;QAC1B,UAAU;eACH,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC;;;EAG9C,aAAa,EAAE,CAAA"}
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../../src/lib/skills/content.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,uBAAuB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAErE,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CAAA;AAErC,MAAM,CAAC,MAAM,iBAAiB,GAC1B,oSAAoS,CAAA;AAExS,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAA;AAEnC,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA;AAElC,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,CAAA;AAEhD,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0U5B,CAAA;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG;QAC1B,UAAU;eACH,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC;WACrC,aAAa;;YAEZ,YAAY;aACX,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC;;;EAGxC,aAAa,EAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/twist-cli",
-    "version": "2.31.2",
+    "version": "2.32.0",
     "description": "TypeScript CLI for Twist",
     "type": "module",
     "main": "dist/index.js",