Shortcut CLI Skill
Manage Shortcut stories, epics, objectives, iterations, docs, labels, teams, and more via the short CLI tool.
Instructions
When invoked with /shortcut $ARGUMENTS:
1. Check Prerequisites
Verify the short CLI is installed and authenticated:
which short && short --version- If not found: Guide user through installation (see Prerequisites), then STOP
- If found but version < 5.0.0: Warn user to upgrade (
brew upgrade shortcut-cliornpm update -g @shortcut-cli/shortcut-cli) - If found and >= 5.0.0: Continue to step 2
2. Parse $ARGUMENTS
Route based on argument pattern (in priority order):
| Pattern | Action |
|---|---|
| No arguments | Show help menu with available commands |
URL containing /story/<id> | Extract numeric ID, run short story <id> |
URL containing /epic/<id> | Extract numeric ID, run short epic view <id> |
search <text> | Run short search -t "<text>" |
my | Run short search -o me |
list | Run short search (no filters) |
create | Ask for entity type + details, run create command (see references/commands.md ## Create) |
objectives [...] | Route to objectives commands (see references/commands.md ## Objectives) |
teams [...] | Route to teams commands (see references/commands.md ## Teams) |
iterations [...] | Route to iterations commands (see references/commands.md ## Iterations) |
docs [...] | Route to docs commands (see references/commands.md ## Docs) |
labels [...] | Route to labels commands (see references/commands.md ## Labels) |
workflows | Run short workflows |
projects | Run short projects |
story <id> <subcommand> | Route to story subcommands: history, comments, tasks, relations (see references/commands.md ## Stories) |
| Numeric value | Treat as story ID, run short story <id> |
Create supports stories, epics, iterations, objectives, docs, and labels — see references/commands.md for each.
Always quote user-provided strings and escape double quotes in input.
3. Present Results
- Story/epic details: Show ID, title, state, owner, description, URL
- Search results: Numbered list with ID, title, state
- Creation: Success message with new item URL
- Lists (teams, labels, iterations, etc.): Clean formatted table
Suggest relevant follow-up actions after presenting results.
4. Handle Errors
| Error | Detection | Response |
|---|---|---|
| CLI not found | which short empty | Show installation instructions, do NOT auto-install |
| Auth failure | "unauthorized" or "invalid token" | Guide user to run short install |
| Not found | "not found" in output | Confirm ID, suggest search |
| Network error | Timeout or connection error | Ask user to check connection |
| Node.js version | ESM/import errors or "unsupported engine" | User needs Node.js >= 20.19.0 |
Prerequisites
- Node.js >= 20.19.0 (required by shortcut-cli v5+)
# Install via Homebrew (preferred)
brew install shortcut-cli
# Or via npm (fallback)
npm install -g @shortcut-cli/shortcut-cli
# Verify version (expect >= 5.0.0)
short --version
# Authenticate
short install
# Or: export SHORTCUT_API_TOKEN="your-api-token"Reference
| Task | Reference |
|---|---|
| CLI commands (stories, epics, objectives, iterations, docs, labels, teams, search, create, API) | references/commands.md — use ## Section headers to find specific command families |
| Shortcut API spec | references/shortcut.swagger.json |