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

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

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