Shortcut

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: 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/ | Extract numeric ID, run short story | | URL containing /epic/ | Extract numeric ID, run short epic view | | search | Run short search -t "" | | 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 | Route to story subcommands: history, comments, tasks, relations (see references/commands.md ## Stories) | | Numeric value | Treat as story ID, run short story |

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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hefgi
• Source: hefgi/skills
• License: MIT

Install and usage instructions live in the source repository linked above.