Shortcut Epic Update

Updates Shortcut epics via the Shortcut API when the MCP server doesn't provide update functionality.

When to Use

•Linking epics to objectives (objective_ids)
•Changing epic state or workflow state
•Updating epic name or description
•Changing epic owner
•Any other epic field updates not supported by MCP

Permissions Required

This skill requires Bash tool permission to:

•Read API tokens from ~/.claude/skills/shortcut-tokens.json using jq
•Execute curl commands to update epics via Shortcut API
•User should approve curl commands that modify external data

API Tokens

CRITICAL: Tokens are stored in ~/.claude/skills/shortcut-tokens.json

File format (see shortcut-tokens.sample.json for template):

json

{
  "coherentpath": "your_coherentpath_token",
  "movableink": "your_movableink_token"
}

Use the correct token key for the workspace:

•CoherentPath → coherentpath
•Movable Ink → movableink

Instructions

•
Determine the workspace from context or ask the user
- •CoherentPath (CP) = default/primary
- •Movable Ink (MI) = legacy

•

Read the API token from the config file:

bash

TOKEN=$(jq -r '.coherentpath' ~/.claude/skills/shortcut-tokens.json)
# or
TOKEN=$(jq -r '.movableink' ~/.claude/skills/shortcut-tokens.json)

•
Get the epic ID to update
•
Build the update payload with only the fields to change:
json
```
{
  "objective_ids": [186645],
  "name": "New epic name",
  "description": "Updated description",
  "state": "in progress",
  "owner_ids": ["uuid-here"]
}
```
CRITICAL JSON Formatting:
- •Avoid special characters like ! in bash strings (causes history expansion)
- •Use single quotes for JSON payloads with variables: PAYLOAD='{"key":"value"}'
- •Then reference with double quotes: -d "$PAYLOAD"
- •Test JSON validity before sending: echo "$PAYLOAD" | jq .

•

Execute the curl command:

bash

curl -X PUT "https://api.app.shortcut.com/api/v3/epics/{epic_id}" \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $TOKEN" \
  -d '{json_payload}'

•
Verify the update by checking the response JSON

Common Update Operations

Link to Objective

json

{
  "objective_ids": [186645]
}

Change State

json

{
  "state": "in progress"
}

Update Owner

json

{
  "owner_ids": ["69696143-c308-4c11-a058-ee700eb89122"]
}

Update Name and Description

json

{
  "name": "New Epic Name",
  "description": "Updated description text"
}

Important Guidelines

•Only include fields you want to change - omitted fields remain unchanged
•Use proper JSON formatting in the curl -d parameter
•Validate epic ID exists before updating
•Check the response for errors (4xx/5xx status codes)
•Never expose API tokens in output - they're embedded in curl commands

Tool Usage

•Bash: Execute curl commands to call Shortcut API
•Read: Optional - read shortcut-workspaces skill for reference

Examples

<example> User: "Link epic 186646 to objective 186645 in CoherentPath"

Steps:

•Workspace: CoherentPath → read coherentpath token
•Read token: TOKEN=$(jq -r '.coherentpath' ~/.claude/skills/shortcut-tokens.json)
•Epic ID: 186646
•Build payload: PAYLOAD='{"objective_ids": [186645]}'
•Validate JSON: echo "$PAYLOAD" | jq .

•Execute curl:

bash

curl -X PUT "https://api.app.shortcut.com/api/v3/epics/186646" \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $TOKEN" \
  -d "$PAYLOAD"

•Verify response contains "objective_ids": [186645] </example>

Notes

•API tokens stored in ~/.claude/skills/shortcut-tokens.json (gitignored)
•Sample format in shortcut-tokens.sample.json (committed for reference)
•This skill and tokens file are excluded from git via .gitignore
•Future: Submit PR to useshortcut/mcp-server-shortcut to add epic update support
•Shortcut API docs: https://developer.shortcut.com/api/rest/v3#Update-Epic