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:

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

# Check if installed
which short

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

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

Authentication

# Interactive setup
short install

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

Commands Reference

View Story Details

short story <id>

Update Story

# 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

# 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

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

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

Epics

# 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:

# 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

1. Extract story ID: 10220
2. Fetch story details:

   short story 10220
   

3. 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

short search -o me

Example 3: Search Stories

User: /shortcut search authentication

short search -t "authentication"

Example 4: Create a New Story

User: /shortcut create

1. Ask for title (required)
2. Ask for state/workflow (required)
3. Ask for description (optional)
4. Ask for story type (optional, default: feature)
5. Execute:

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

6. Display created story URL