nicksteffens/shortcut-epic-update

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)
• Assigning epics to teams (group_ids - teams are called "groups" in the API)
• 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):

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

Use the correct token key for the workspace:

• CoherentPath → coherentpath
• Movable Ink → movableink

Instructions

1. Determine the workspace from context or ask the user

   • CoherentPath (CP) = default/primary
   • Movable Ink (MI) = legacy

2. Read the API token from the config file:

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

3. Get the epic ID to update

4. Build the update payload with only the fields to change:

   {
     "objective_ids": [186645],
     "group_ids": ["698e17ad-ae60-4ddd-af00-37d5ca5810a2"],
     "name": "New epic name",
     "description": "Updated description",
     "state": "in progress",
     "owner_ids": ["uuid-here"]
   }
   

   Note: Teams are called "groups" in Shortcut's API, so use group_ids to assign teams.

   CRITICAL JSON Formatting:

   • Avoid exclamation marks (!) 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 .

5. Execute the curl command:

   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}'
   

6. Verify the update by checking the response JSON

Common Update Operations

Link to Objective

{
  "objective_ids": [186645]
}

Assign to Team

IMPORTANT: In Shortcut's API, teams are called "groups". Use group_ids (not team_ids):

{
  "group_ids": ["698e17ad-ae60-4ddd-af00-37d5ca5810a2"]
}

Change State

{
  "state": "in progress"
}

Update Owner

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

Update Name and Description

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

Important Guidelines

• Only include fields you want to change - omitted fields remain unchanged
• Teams = Groups: In Shortcut's API, teams are called "groups" - always use group_ids not team_ids
• 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:

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

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

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

<example> User: "Assign epic 187449 to Design System & Front End Guild Team"

Steps:

1. Workspace: CoherentPath → read coherentpath token
2. Read token: TOKEN=$(jq -r '.coherentpath' ~/.claude/skills/shortcut-tokens.json)
3. Epic ID: 187449
4. Team ID: 698e17ad-ae60-4ddd-af00-37d5ca5810a2 (from shortcut-workspaces skill)
5. Build payload (teams use group_ids):

   cat > /tmp/epic_update.json << 'EOF'
   {"group_ids": ["698e17ad-ae60-4ddd-af00-37d5ca5810a2"]}
   EOF
   

6. Execute curl:

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

7. Verify response contains "group_ids": ["698e17ad-ae60-4ddd-af00-37d5ca5810a2"] </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