Shortcut CLI Skill

Interact with Shortcut stories and epics via the short CLI tool.

Instructions

When invoked with /shortcut $ARGUMENTS:

1. Check Prerequisites

First, verify the short CLI is installed and authenticated:

bash

which short

•If command not found: Guide user through installation (see Prerequisites section), then STOP
•If found: Continue to step 2

2. Parse $ARGUMENTS

Route based on the argument pattern (in priority order):

Pattern	Action
No arguments	Show help menu with available commands
URL starting with `https://app.shortcut.com/` containing `/story/`	Extract story ID (number after `/story/`), fetch and display details
URL starting with `https://app.shortcut.com/` containing `/epic/`	Extract epic ID (number after `/epic/`), fetch and display details
`search <text>`	Search stories by text
`my`	List my assigned stories
`list`	List all stories (uses `short search` without filters)
`create`	Start interactive story creation flow
Numeric value only	Treat as story ID, fetch and display details

URL Parsing:

•Story URL regex: https://app\.shortcut\.com/[^/]+/story/(\d+) → Extract group 1 as ID
•Epic URL regex: https://app\.shortcut\.com/[^/]+/epic/(\d+) → Extract group 1 as ID

3. Execute Command

Run the appropriate short CLI command from the Commands Reference section below.

Input handling:

•Always quote user-provided strings in commands
•Escape double quotes in user input by replacing " with \"

4. Present Results

Format output for readability:

•For story/epic details: Show ID, title, state, owner, description, and URL
•For search results: Show as a numbered list with ID, title, state
•For creation: Show success message with new story URL

After presenting results, suggest relevant follow-up actions.

5. Handle Errors

Error Type	Detection	Response
CLI not found	`which short` returns empty	Show installation instructions, do NOT auto-install
Auth failure	Output contains "unauthorized" or "invalid token"	Guide user to run `short install`
Not found	Output contains "not found"	Confirm ID, suggest search command
Network error	Timeout or connection error	Ask user to check connection, retry

Prerequisites

Installation

bash

# Check if installed
which short

# Install via Homebrew (preferred)
brew install shortcut-cli

# Or via npm (fallback)
npm install -g shortcut-cli

Authentication

bash

# Interactive setup
short install

# Or set environment variable
export SHORTCUT_API_TOKEN="your-api-token"

Commands Reference

View Story Details

bash

short story <id>

Update Story

bash

# Update state/workflow
short story <id> -s "<state>"

# Update title
short story <id> -t "<title>"

# Update description
short story <id> -d "<description>"

# Add comment
short story <id> -c "<comment>"

# Open in browser
short story <id> -O

Search Stories

bash

# Search by text
short search -t "<text>"

# My assigned stories
short search -o me

# By workflow state
short search -s "<state>"

# By label
short search -l "<label>"

Create Story

bash

short create -t "<title>" -s "<state>" [options]

# Options:
#   -d "<description>"  - Story description
#   -y "<type>"         - Story type (feature, bug, chore)

Epics

bash

# List all epics
short epics

# View epic details
short epic view <id>

# Create epic
short epic create -n "<name>" [-d "<description>"]

# Update epic
short epic update <id> [-n "<name>"] [-d "<description>"]

Raw API Access (Advanced)

For operations not covered by CLI commands, use direct API access:

bash

# GET request
short api <path>

# POST request
short api <path> -X POST -f "key=value"

# PUT request
short api <path> -X PUT -f "key=value"

# DELETE request
short api <path> -X DELETE

Reference the Swagger spec at reference/shortcut.swagger.json for available endpoints.

Workflow Examples

Example 1: View and Update a Story

User: /shortcut https://app.shortcut.com/myorg/story/10220/some-story-title

•Extract story ID: 10220
•
Fetch story details:
bash
```
short story 10220
```
•
Display story info and ask what action the user wants:
- •Update state
- •Update title/description
- •Add comment
- •Open in browser

Example 2: Find My Stories

User: /shortcut my

bash

short search -o me

Example 3: Search Stories

User: /shortcut search authentication

bash

short search -t "authentication"

Example 4: Create a New Story

User: /shortcut create

•Ask for title (required)
•Ask for state/workflow (required)
•Ask for description (optional)
•Ask for story type (optional, default: feature)

•Execute:

bash

short create -t "<title>" -s "<state>" -d "<description>" -y "<type>"

•Display created story URL