Claude skill - Superthread help center

The Superthread CLI includes a built-in skill for Claude Code. When installed, it teaches Claude how to use st for project management tasks like creating cards, managing sprints, searching, and more.

Install the skill

st claude install

This writes a skill file to ~/.claude/skills/superthread-cli/SKILL.md. The skill is bundled inside the st binary. When you run st update, you’ll be prompted to update the skill automatically if it was previously installed. You can also re-run st claude install at any time to get the latest version.

Skill contents

Below is the full skill that gets installed. This is what Claude Code sees when it uses the Superthread CLI on your behalf.

Quick Start

st auth login                      # OAuth2 browser login
st auth status                     # Verify token + workspace

st boards list -s Engineering      # Boards in a space
st cards create -l LIST -b BOARD --title "Task"
st search "auth bug" --types cards

Essential Patterns

--output json / -o json  # Structured JSON output (for scripts/agents)
-y / --yes               # Skip confirmation prompts
-s SPACE                 # Scope to a space (name or numeric ID)
-b BOARD                 # Scope to a board (name or numeric ID)
me                       # Use as user reference: st projects update ID --owner me

Most commands accept names or IDs for spaces, boards, and users. Space/board/sprint/tag IDs are numeric; user IDs are 8-char alphanumeric starting with u (e.g. uRaEi3th). Any value not matching these patterns is resolved as a name via API lookup. All --content flags accept GitHub Flavored Markdown. --description and --desc are accepted as aliases for --content everywhere. The server converts it to HTML before storage. Use standard markdown: headings, bold, lists, task lists (- [ ]), code blocks, blockquotes, etc. Always use multi-line strings for content with structure — never use literal \n escape sequences. Important: Only set optional fields (priority, estimate, due date, tags) when the user explicitly asks or clearly implies a value. Do not assume defaults for these fields.

Common Workflows

View and manage cards

st cards list -b BOARD                        # List cards on a board
st cards list --sprint current -s SPACE       # List cards in active sprint
st cards list --assignee me                   # List my active cards (excludes done/cancelled)
st cards list --assignee me --status all      # List all my cards including done/cancelled
st cards list --assignee me --status done     # List only my completed cards
st cards list --assignee me --tag bug        # Filter by tag
st cards list --assignee me -t bug,feature   # Filter by multiple tags
st cards list --assignee me --sprint current -s SPACE  # My cards in current sprint
st cards list --project "Q1 Roadmap"          # Cards in a specific project/epic
st cards get CARD_ID
st cards create --title "Fix login bug" -l LIST -b BOARD
st cards create --title "Sprint task" --sprint current -s Engineering --assignee me  # Create in active sprint
st cards create --title "Sprint task" --sprint 90 -s Engineering                   # Create in specific sprint
st cards create --title "Subtask" -l LIST --project "Q1 Roadmap"                   # Create in a project (epic)
st cards create --title "Subtask" -l LIST --parent PARENT_CARD_ID                  # Create with a parent card
st cards create --title "Parent" -l LIST --child CHILD_ID --child CHILD_ID2        # Create with child cards
st cards update CARD_ID --title "New title" --priority 2 --due-date 2026-03-27
st cards update CARD_ID --content "## New description\n\nReplaces existing content."
st cards update CARD_ID --project "Q1 Roadmap"                                     # Add card to a project (epic)
st cards update CARD_ID --project none                                             # Remove card from project
st cards update CARD_ID --parent PARENT_CARD_ID                                    # Set parent card
st cards update CARD_ID --parent none                                              # Remove from parent card
st cards update CARD_ID --child CHILD_CARD_ID                                      # Add a child card
st cards update CARD_ID --child none                                               # Clear all children
st cards update CARD_ID --assignee alice                                           # Add Alice (idempotent if already assigned)
st cards update CARD_ID --assignee none                                            # Clear all assignees
st cards update CARD_ID --tag bug                                                  # Add a tag
st cards update CARD_ID --tag none                                                 # Clear all tags
st cards list --has-blockers                                                       # Cards that are blocked
st cards list --assignee me --has-blocking                                         # My cards that are blocking others
st cards list --relationship-types related,duplicates                              # Cards with related or duplicate relationships
st cards archive CARD_ID
st cards duplicate CARD_ID
st cards delete CARD_ID                       # Prompts for confirmation
st cards delete CARD_ID -y                    # Skip confirmation

Browse structure

st spaces list
st spaces get Engineering                     # By name
st boards list -s Engineering                 # Boards in a space
st sprints list -s Engineering
st users list
st users me

Search

st search "auth bug"
st search "auth bug" --types cards,pages -s Engineering
st search "auth bug" --count 50 -a            # Include archived

Checklists

st checklists list -c CARD_ID                  # List checklists on a card
st checklists create -c CARD_ID --title "QA"   # Create checklist
st checklists add-item CL_ID -c CARD_ID --title "Step 1"
st checklists check ITEM_ID -c CARD_ID --checklist CL_ID
st checklists uncheck ITEM_ID -c CARD_ID --checklist CL_ID

Comments

st comments list -c CARD_ID
st comments list --page PAGE_ID
st comments create --content "**Important:** check the logs" -c CARD_ID
st comments create --content "Note" --page PAGE_ID
st comments reply COMMENT_ID --content "Reply with **markdown**"
st comments react COMMENT_ID --unicode "👍"
st comments delete COMMENT_ID

Project Health

st projects health update PROJECT_ID --status at-risk -m "Blocked on dependency"
st projects health list PROJECT_ID                     # View health update history
st projects health delete COMMENT_ID                   # Revert to previous status
st projects health set-period PROJECT_ID --days 14     # Configure staleness period ('none' to disable)
st projects get PROJECT_ID --health                    # Project details with inline health history

Health statuses: on-track, at-risk, off-track, not-expected

Full Command Reference

Auth

st auth login                                 # Browser OAuth2
st auth status                                # Show token + workspace info
st auth logout                                # Remove stored credentials
st whoami                                     # Alias for `auth status`

Spaces

st spaces list
st spaces get SPACE
st spaces create --title "Name"
  # Options: --description, --private
st spaces update SPACE --title "New"
  # Options: --description
st spaces delete SPACE                        # Confirms
st spaces add-member SPACE -u USER            # User: name, email, or ID
st spaces remove-member SPACE -u USER

Boards

st boards list -s SPACE
  # Options: --archived
st boards get BOARD
  # Options: --space/-s (required when BOARD is a name; numeric IDs skip the check)
st boards create -s SPACE --title "Name"
  # Options: --default-lists
  # --default-lists creates standard lists: Backlog, Todo, Doing, Done, Cancelled
st boards create -s SPACE --title "Sprint Board" --default-lists
st boards update BOARD --title "New"
  # Options: --space/-s (required when BOARD is a name)
st boards delete BOARD                        # Confirms
  # Options: --space/-s (required when BOARD is a name)
st boards duplicate BOARD
  # Options: --space/-s (required when BOARD is a name)
st boards create-list -b BOARD --title "Column"
  # Options: --color, --status, --space/-s (required when --board is a name)
  # --status sets the list status type (backlog, todo, doing, done, canceled)
  # Status is auto-inferred from common titles (e.g. "To Do" → committed, "Done" → completed)
st boards create-list -b BOARD --title "QA" --status doing
st boards update-list LIST_ID --title "New"
  # Options: --color

Board name resolution scopes through the workspace’s spaces, so a name lookup needs the parent space ID. The CLI returns a clear validation failed: space_id error if --space is missing on a name-based call. Numeric board IDs short-circuit and don’t need --space.

Cards

st cards list
  # Requires one of: --board/-b, --sprint, --assignee/-a, or a views-path filter
  # Options: --space/-s (required with --sprint), --status, --tag/-t, --archived
  # --assignee/-a supports 'me', user name, email, or ID
  # --sprint supports 'current' or sprint name/ID
  # --status: comma-separated statuses or 'all'
  #   Canonical: backlog, committed, started, completed, cancelled
  #   Aliases:   backlog, todo,      doing,   done,      canceled
  #              (also: in-progress, in_progress, active, finished,
  #               closed, deployed, production, live, shipped, complete)
  # When --assignee is used, defaults to backlog+committed+started (hides done/cancelled)
  # --tag/-t: comma-separated tag names or IDs (cards matching any listed tag)
  #
  # Views-path filters (stand alone or compose with --assignee; don't combine with --board/--sprint):
  #   --content TEXT          substring match across task title + description
  #   --title TEXT            substring match against title only
  #   --priority N[,N...]     comma-separated priorities (0=none..4=urgent)
  #   --creator REF           filter by creator (name, email, ID, or 'me')
  #   --project REF[,REF...]  comma-separated project/epic names or IDs (alias: --epic)
  #   --due-before DATE       due date strictly before DATE; absolute or date-math (e.g. 'now+7d')
  #   --due-after  DATE       due date strictly after DATE
  #   --sort-by FIELD         due_date | estimate | priority | status | time_created | time_updated
  #   --sort-desc             sort descending (default ascending)
  #   --has-due-date          tasks that do/don't have a due date (=false to invert)
  #   --has-priority          tasks that do/don't have a priority
  #   --has-estimate          tasks that do/don't have an estimate
  #   --has-tags              tasks that do/don't have tags
  #   --has-assignees         tasks that do/don't have assignees
  #   --has-status            tasks that do/don't have a status set (no status = backlog)
  #   --has-parent-card       equivalent to --is-child
  #   --is-child              subtasks only (=false for top-level only)
  #   --is-parent             tasks that have at least one subtask
  #   Relationship filters:
  #     --has-blockers        tasks that ARE blocked. Use =false to invert.
  #     --has-blocking        tasks that ARE blocking others. Use =false to invert.
  #     --has-relationship    tasks with ANY relationship to another task. Use =false to invert.
  #     --relationship-types  OR list: blocks, blocked_by, related, duplicates.
  # Mutually exclusive: --has-blockers=true + --has-blocking=true (wire would OR
  # them, returning "blocked OR blocking" — use --relationship-types=blocked_by,blocks
  # if OR is what you want); --relationship-types with either semantic flag.
st cards get CARD_ID
st cards create --title "Task" -l LIST -b BOARD
  # Options: --content, --priority (0-4), --estimate, --due-date (YYYY-MM-DD), --sprint, --space/-s, --assignee/-a, --project/--epic, --parent, --child, --tag/-t
  # When --sprint is set, --list is optional (defaults to sprint's Todo list)
  # --space/-s always required with --sprint
  # --project/--epic: project name or ID to add the card to
  # --parent: parent card ID
  # --child: child card ID (repeatable; clearing children after create is done via `cards update --child none`)
st cards update CARD_ID
  # Options: --title, --content, --list/-l, --board/-b, --sprint, --space/-s, --assignee/-a, --priority, --estimate, --due-date (YYYY-MM-DD), --project/--epic, --parent, --child, --tag/-t
  # --list/-l: list name or ID; --sprint/-s not needed when moving within the card's current sprint/board
  # --content replaces existing content entirely
  # --sprint: name, ID, or 'current'; --space/-s always required with --sprint
  # --board: name or ID. For names: scoped by --space if given, else lazy-fetches the card's current space.
  # --project/--epic: project name or ID; use 'none' to remove from project
  # --parent: parent card ID; use 'none' to remove from parent
  # --assignee/-a: comma-separated. Adds to existing assignees (idempotent on re-add); use 'none' to clear all.
  # --tag/-t: comma-separated. Adds to existing tags; use 'none' to clear all.
  # --child: comma-separated child card IDs. Adds to existing children; use 'none' to clear all.
st cards delete CARD_ID                       # Confirms
st cards archive CARD_ID
st cards duplicate CARD_ID

Priority levels: 0=None, 1=Low, 2=Medium, 3=High, 4=Urgent

Cards — Tags

st cards tags list
  # Options: --space/-s
st cards tags add CARD_ID TAG [TAG...]         # TAG: name or ID
st cards tags remove CARD_ID TAG

st cards related add CARD_ID RELATED_CARD_ID          # --type/-t: related (default), blocks, blocked_by, duplicates
st cards related remove CARD_ID RELATED_CARD_ID

Checklists

st checklists list -c CARD_ID                  # List checklists on a card
st checklists get CHECKLIST_ID -c CARD_ID      # Get checklist with items
st checklists create -c CARD_ID --title "QA Steps"
  # Options: --content
st checklists update CHECKLIST_ID -c CARD_ID
  # Options: --title, --content
st checklists delete CHECKLIST_ID -c CARD_ID   # Confirms
st checklists add-item CHECKLIST_ID -c CARD_ID --title "Step 1"
  # Options: --content, --checked
st checklists update-item ITEM_ID -c CARD_ID --checklist CHECKLIST_ID
  # Options: --title, --content, --checked
st checklists delete-item ITEM_ID -c CARD_ID --checklist CHECKLIST_ID  # Confirms
st checklists check ITEM_ID -c CARD_ID --checklist CHECKLIST_ID
st checklists uncheck ITEM_ID -c CARD_ID --checklist CHECKLIST_ID

Projects (Epics)

st projects list
st projects get PROJECT_ID
  # Options: --health (include health update history)
st projects create --title "Q1 Roadmap"
  # Options: --list/-l (name or ID; defaults to first project list), --content, --owner, --assignee/-a, --priority, --due-date (YYYY-MM-DD)
  # Projects live on a dedicated roadmap board. --list refers to columns on that board (e.g. "Backlog", "Planned").
st projects create --title "Sprint goal" -l "In progress"  # Create in a specific project list by name
st projects update PROJECT_ID
  # Options: --title, --content, --list/-l (name or ID), --owner, --assignee/-a, --priority, --archived, --due-date (YYYY-MM-DD)
  # --content replaces existing content entirely
  # --assignee/-a: comma-separated. Adds to existing assignees (idempotent on re-add); use 'none' to clear all.
st projects delete PROJECT_ID                 # Confirms
st projects archive PROJECT_ID
st projects related add PROJECT_ID RELATED_ID         # --type/-t: related (default), blocks, blocked_by, duplicates
st projects related remove PROJECT_ID RELATED_ID
st projects tags list
st projects tags add PROJECT_ID TAG [TAG...]   # TAG: name or ID
st projects tags remove PROJECT_ID TAG
st projects health update PROJECT_ID --status STATUS -m "Message"
  # --status: on-track, at-risk, off-track, not-expected
  # -m/--message: required explanation for the status change (markdown)
st projects health list PROJECT_ID             # List health update history
st projects health delete COMMENT_ID           # Delete a health update (reverts status); confirms
st projects health set-period PROJECT_ID --days N
  # Days between expected check-ins; project is marked stale if no update within this window
  # Use 'none' to disable staleness tracking

st projects get includes health status info. Use --health to also show the health update history inline. st projects list includes a HEALTH column showing each project’s current health status.

Pages

st pages list -s SPACE                        # --space/-s required
st pages get PAGE_ID
st pages create -s SPACE
  # Options: --title, --content, --parent-page
st pages update PAGE_ID
  # Options: --title, --content, --parent-page
  # --content replaces existing content entirely
  # --parent-page: page ID to nest this page under (reparent); use 'none' to move it to the top level
st pages delete PAGE_ID                       # Confirms
st pages archive PAGE_ID
st pages duplicate PAGE_ID

Notes

st notes list
st notes get NOTE_ID
st notes create --title "Meeting Notes"
st notes delete NOTE_ID                       # Confirms

Comments & Replies

st comments list -c CARD_ID                    # List comments on a card
st comments list --page PAGE_ID                # List comments on a page
  # Options: --filter (resolved, open, orphaned)
st comments get COMMENT_ID
st comments create --content "Text" -c CARD_ID
st comments create --content "Text" --page PAGE_ID
st comments edit COMMENT_ID --content "Updated"
st comments delete COMMENT_ID                 # Confirms
st comments reply COMMENT_ID --content "Reply text"
st comments react COMMENT_ID --unicode "👍"
st comments unreact COMMENT_ID --reaction REACTION_ID

st comments replies list COMMENT_ID
st comments replies edit COMMENT_ID REPLY_ID --content "Updated"
st comments replies delete COMMENT_ID REPLY_ID   # Confirms

Sprints

st sprints list -s SPACE                      # --space/-s required
  # Options: --archived
st sprints get SPRINT_ID -s SPACE              # --space/-s required
st sprints create -s SPACE
  # Options: --title
st sprints update SPRINT_ID -s SPACE          # --space/-s required
  # Options: --title, --state (planned|active|completed|cancelled), --start-date, --end-date
  # --start-date / --end-date: epoch seconds

Sprint Settings

st sprints settings get -s SPACE
st sprints settings update -s SPACE --enabled --length 14 --cooldown 0 --start-day 1
  # All flags required. --length: 7-56 days (multiples of 7)
  # --cooldown: 0,7,14,21,28 days. --start-day: 0=Sun..6=Sat

Users

st users me
st users list
st users update-me
  # Options: --first-name, --last-name, --display-name
st users update-member USER --role ROLE       # --role required
st users delete-member USER                   # Confirms

Search

st search QUERY
  # Options: --types (cards,pages,boards,...), --count N, --space/-s, --archived

Completion & Utility

st completion                                  # Interactive guided setup
st completion install                          # Detect shell and install completions
st completion generate bash|zsh|fish|powershell  # Print script to stdout
st claude install                              # Install/update this skill at ~/.claude/skills/superthread-cli/SKILL.md
  # Options: -y to skip confirmation
st version
st update                                     # Options: --force

Global Options

Flag	Short	Description
`--token`		API token override
`--api-url`		API base URL override
`--output`	`-o`	Output format: json, text
`--yes`	`-y`	Skip confirmations

Flag Aliases

Long	Short	Description
`--space`	`-s`	Space (name or numeric ID)
`--board`	`-b`	Board (name or numeric ID)
`--list`	`-l`	List (name or ID)
`--card`	`-c`	Card ID
`--assignee`	`-a`	Assignee — card commands (name, email, ID, or ‘me’)
`--tag`	`-t`	Tag filter — cards list (comma-separated names or IDs)
`--owner`		Owner — projects/epics only (name, email, or user ID)
`--user`	`-u`	User (name, email, or user ID)
`--archived`		Include archived items

Configuration

Precedence (highest first):

CLI flags (--token, --api-url, --output/-o)
Environment variables (ST_TOKEN, ST_API_URL, ST_OUTPUT_FORMAT)
Config file ~/.config/superthread/config.yaml (created by st auth login)

Delete Confirmation

All delete commands prompt before executing. Use --yes/-y to skip (useful for scripts). Confirmed deletes: spaces, boards, cards, projects, pages, notes, comments, replies, team members.

​Install the skill

​Skill contents

​Quick Start

​Essential Patterns

​Common Workflows

​View and manage cards

​Browse structure

​Search

​Tags

​Checklists

​Comments

​Project Health

​Full Command Reference

​Auth

​Spaces

​Boards

​Cards

​Cards — Tags

​Cards — Related

​Checklists

​Projects (Epics)

​Pages

​Notes

​Comments & Replies

​Sprints

​Sprint Settings

​Users

​Search

​Completion & Utility

​Global Options

​Flag Aliases

​Configuration

​Delete Confirmation

Install the skill

Skill contents

Quick Start

Essential Patterns

Common Workflows

View and manage cards

Browse structure

Search

Tags

Checklists

Comments

Project Health

Full Command Reference

Auth

Spaces

Boards

Cards

Cards — Tags

Cards — Related

Checklists

Projects (Epics)

Pages

Notes

Comments & Replies

Sprints

Sprint Settings

Users

Search

Completion & Utility

Global Options

Flag Aliases

Configuration

Delete Confirmation