Shortcut

Manage stories on Shortcut.com kanban boards. Use when creating, updating, or listing tasks/stories on Shortcut project management boards. Supports creating stories with descriptions and types (feature/bug/chore), updating story status, and listing active/completed stories. Includes full checklist task management and comment support.

Security Scan

The skill's scripts appear to do exactly what the description claims (manage Shortcut stories) but the package metadata omits required environment variables and required binaries, which is an important inconsistency you should resolve before installing.

Purpose & Capability

The skill's name and description align with the included scripts: all scripts call Shortcut's API and implement create/list/update/delete for stories, tasks, and comments. However, the skill registry metadata declares no required environment variables or binaries even though the SKILL.md and scripts require a Shortcut API token (SHORTCUT_API_TOKEN or ~/.config/shortcut/api-token) and runtime tools (bash, curl, jq). That mismatch between claimed requirements and actual needs is unexpected and should be fixed or explained by the author.

Instruction Scope

SKILL.md and the scripts stay within the expected scope: they call the official Shortcut API (https://api.app.shortcut.com/api/v3), read/write SSH-local config files under ~/.config/shortcut, and do not attempt to read unrelated system data. The scripts create ~/.config/shortcut/workflow-states and use /tmp for transient responses; SKILL.md suggests optionally adding the token to ~/.bashrc (user-facing guidance). There are no hidden endpoints or broad data-collection steps in the scripts.

Install Mechanism

There is no install spec (instruction-only), which is low risk from supply-chain downloads. However, the skill includes many shell scripts bundled in the skill itself; installing the skill will place those scripts on disk. The scripts are plain bash and use curl/jq; the metadata should list these runtime dependencies but does not.

Credentials

Functionally the skill only needs a single Shortcut API token and workspace permissions (proportional to the stated purpose). But the registry metadata lists no required env vars while SKILL.md and every script require SHORTCUT_API_TOKEN or a token file. Additionally the manifest does not declare required binaries (curl, jq). This omission is a practical and security-relevant inconsistency: users may not realize they must supply a token and may be surprised that scripts access ~/.config/shortcut and ~/.bashrc (if they follow the optional guidance).

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide agent settings. It writes and reads its own configuration under ~/.config/shortcut and suggests optionally sourcing that file from ~/.bashrc — these are standard, limited local config actions. Autonomous invocation is allowed by default (normal for skills) but not combined with other high-risk behaviors here.

What to consider before installing

This skill's code matches its description (it talks to Shortcut's official API and manages stories, tasks, comments), but the package metadata omits important operational requirements. Before installing: 1) Verify you trust the skill author (owner ID provided) because the skill will use your Shortcut API token. 2) Expect to provide SHORTCUT_API_TOKEN (or create ~/.config/shortcut/api-token) — the skill does not declare this in metadata. 3) Ensure curl and jq are available on the agent host (scripts depend on them). 4) Inspect the scripts locally (they're plain bash) to confirm behavior; the scripts write ~/.config/shortcut/workflow-states and may advise adding a source to ~/.bashrc — do not blindly modify your shell rc files. 5) Prefer creating a token with the least privileges necessary and rotate/revoke it if you uninstall or stop using the skill. The omissions in metadata are likely sloppy packaging rather than malicious intent, but they are security-relevant and should be corrected before use.

Shortcut Kanban Integration

Manage tasks and stories on Shortcut.com project boards via API.

Prerequisites

• Shortcut API token configured via one of:
  • Environment variable: SHORTCUT_API_TOKEN
  • File: ~/.config/shortcut/api-token
• Access to a Shortcut workspace with appropriate permissions

Setup

1. Get your API token from Shortcut.com (Settings → API Tokens)
2. Store it either:
   • As environment variable: export SHORTCUT_API_TOKEN="your-token"
   • In a file: echo "your-token" > ~/.config/shortcut/api-token && chmod 600 ~/.config/shortcut/api-token
3. Initialize workflow states for your workspace:

   scripts/shortcut-init-workflow.sh
   

   This creates ~/.config/shortcut/workflow-states with your workspace's actual state IDs.
4. Optionally add to ~/.bashrc for persistence:

   export SHORTCUT_API_TOKEN=$(cat ~/.config/shortcut/api-token 2>/dev/null | tr -d '\n')
   source ~/.config/shortcut/workflow-states
   

Available Operations

List Stories

scripts/shortcut-list-stories.sh [--active|--completed|--all] [--json]

Options:

• --active - Show only incomplete stories (default)
• --completed - Show only completed stories
• --all - Include archived stories
• --json - Output raw JSON

Show Story Details

scripts/shortcut-show-story.sh <story-id>

Displays full story information including:

• Story name and status
• Description (if present)
• Checklist items with completion status

Create Story

scripts/shortcut-create-story.sh "Story name" [--description "text"] [--type feature|bug|chore]

Story types:

• feature (default) - New functionality
• bug - Bug fix
• chore - Maintenance task

Update Story

scripts/shortcut-update-story.sh <story-id> [--complete|--todo|--in-progress] [--description "new text"]

Workflow states: The script uses state IDs from ~/.config/shortcut/workflow-states (created by shortcut-init-workflow.sh). If not configured, it falls back to common defaults:

• Backlog: 500000006
• To Do: 500000007
• In Progress: 500000008
• In Review: 500000009
• Done: 500000010

Note: Different Shortcut workspaces may use different state IDs. Always run shortcut-init-workflow.sh to configure your workspace's actual IDs.

Manage Checklist Tasks

Create a task:

scripts/shortcut-create-task.sh <story-id> "task description"

Update task completion status:

scripts/shortcut-update-task.sh <story-id> <task-id> [--complete|--incomplete]

Edit task description:

scripts/shortcut-edit-task.sh <story-id> <task-id> "new description"

Delete a task:

scripts/shortcut-delete-task.sh <story-id> <task-id>

Use shortcut-show-story.sh to see task IDs.

Manage Comments

Add a comment:

scripts/shortcut-add-comment.sh <story-id> "comment text"

Update a comment:

scripts/shortcut-update-comment.sh <story-id> <comment-id> "new text"

Delete a comment:

scripts/shortcut-delete-comment.sh <story-id> <comment-id>

Use shortcut-show-story.sh to see comment IDs.

Workflow

1. List existing stories to understand current board state
2. Create new stories with descriptive names and appropriate types
3. Update story status as work progresses

Notes

• Scripts use SHORTCUT_API_TOKEN environment variable or fall back to ~/.config/shortcut/api-token
• Stories are created in "Unstarted" state by default (workflow_state_id: 500000006)
• If your workspace uses different workflow state IDs, you may need to adjust the scripts
• The token must have permissions for the workspace you want to manage