Linear

Query and manage Linear issues, projects, and team workflows.

Security Scan

The skill's code and instructions align with its stated purpose (a Linear API CLI); it only requires a Linear API key and talks to api.linear.app, but there are a few minor metadata/operational notes to review before installing.

Purpose & Capability

The skill is a CLI wrapper around Linear's GraphQL API and legitimately needs LINEAR_API_KEY. However, the included bash script requires curl, jq, and cksum at runtime (and the SKILL.md mentions curl/jq), while the registry metadata lists no required binaries — that's a metadata mismatch that could confuse installers.

Instruction Scope

Runtime instructions and the script confine activity to the Linear GraphQL endpoint (https://api.linear.app/graphql) and local caching. The script does not attempt to read arbitrary user files, send data to unexpected third-party endpoints, or perform obfuscated actions. It does create a cache file in /tmp by default (derived from a checksum of your API key).

Install Mechanism

No install spec (instruction-only plus an included bash script). Nothing is downloaded from external URLs and no archives are extracted. Risk from installation is low — but the script assumes curl and jq are available on the system.

Credentials

The only required environment variable declared in the registry is LINEAR_API_KEY, which is appropriate. The SKILL.md and script also reference optional vars (LINEAR_DEFAULT_TEAM and LINEAR_TEAMS_CACHE) that are not listed in the registry metadata; this is not a security problem but is a documentation gap. The script derives a cache filename from the API key (cksum) and writes cached team data to /tmp by default, which could leave a recoverable artifact tied to your key.

Persistence & Privilege

The skill is not always: true and does not attempt to modify other skills or system-wide settings. It writes only its own cache file and has no elevated privileges.

Assessment

This skill appears to do what it says: it calls Linear's GraphQL API and requires your LINEAR_API_KEY. Before installing: 1) Inspect the included scripts (scripts/linear.sh) yourself — they use curl and jq, so ensure those binaries are present. 2) Be aware the script caches team info in /tmp by default using a filename derived from a checksum of your API key; if that is a concern set LINEAR_TEAMS_CACHE to a safer path or clear the cache after use. 3) Only provide an API key with the minimum necessary permissions and rotate it if you suspect misuse. 4) Note the registry metadata omits required binaries and optional env vars (LINEAR_DEFAULT_TEAM, LINEAR_TEAMS_CACHE); this is a documentation mismatch, not an indicator of malicious behavior.

Manage issues, check project status, and stay on top of your team's work.

Setup

export LINEAR_API_KEY="your-api-key"
# Optional: default team key used when a command needs a team
export LINEAR_DEFAULT_TEAM="TEAM"

Discover team keys:

{baseDir}/scripts/linear.sh teams

If LINEAR_DEFAULT_TEAM is set, you can omit the team key in team and call:

{baseDir}/scripts/linear.sh create "Title" ["Description"]

Quick Commands

# My stuff
{baseDir}/scripts/linear.sh my-issues          # Your assigned issues
{baseDir}/scripts/linear.sh my-todos           # Just your Todo items
{baseDir}/scripts/linear.sh urgent             # Urgent/High priority across team

# Browse
{baseDir}/scripts/linear.sh teams              # List available teams
{baseDir}/scripts/linear.sh team <TEAM_KEY>    # All issues for a team
{baseDir}/scripts/linear.sh project <name>     # Issues in a project
{baseDir}/scripts/linear.sh issue <TEAM-123>   # Get issue details
{baseDir}/scripts/linear.sh branch <TEAM-123>  # Get branch name for GitHub

# Actions
{baseDir}/scripts/linear.sh create <TEAM_KEY> "Title" ["Description"]
{baseDir}/scripts/linear.sh comment <TEAM-123> "Comment text"
{baseDir}/scripts/linear.sh status <TEAM-123> <todo|progress|review|done|blocked>
{baseDir}/scripts/linear.sh assign <TEAM-123> <userName>
{baseDir}/scripts/linear.sh priority <TEAM-123> <urgent|high|medium|low|none>

# Overview
{baseDir}/scripts/linear.sh standup            # Daily standup summary
{baseDir}/scripts/linear.sh projects           # All projects with progress

Common Workflows

Morning Standup

{baseDir}/scripts/linear.sh standup

Shows: your todos, blocked items across team, recently completed, what's in review.

Quick Issue Creation (from chat)

{baseDir}/scripts/linear.sh create TEAM "Fix auth timeout bug" "Users getting logged out after 5 min"

Triage Mode

{baseDir}/scripts/linear.sh urgent    # See what needs attention

Git Workflow (Linear ↔ GitHub Integration)

Always use Linear-derived branch names to enable automatic issue status tracking.

Getting the Branch Name

{baseDir}/scripts/linear.sh branch TEAM-212
# Returns: dev/team-212-fix-auth-timeout-bug

Creating a Worktree for an Issue

# 1. Get the branch name from Linear
BRANCH=$({baseDir}/scripts/linear.sh branch TEAM-212)

# 2. Pull fresh main first (main should ALWAYS match origin)
cd /path/to/repo
git checkout main && git pull origin main

# 3. Create worktree with that branch (branching from fresh origin/main)
git worktree add .worktrees/team-212 -b "$BRANCH" origin/main
cd .worktrees/team-212

# 4. Do your work, commit, push
git push -u origin "$BRANCH"

⚠️ Never modify files on main. All changes happen in worktrees only.

Why This Matters

• Linear's GitHub integration tracks PRs by branch name pattern
• When you create a PR from a Linear branch, the issue automatically moves to "In Review"
• When the PR merges, the issue automatically moves to "Done"
• Manual branch names break this automation
• Keeping main clean = no accidental pushes, easy worktree cleanup

Quick Reference

# Full workflow example
ISSUE="TEAM-212"
BRANCH=$({baseDir}/scripts/linear.sh branch $ISSUE)

# Always start from fresh main
cd ~/workspace/your-repo
git checkout main && git pull origin main

# Create worktree (inside .worktrees/)
git worktree add .worktrees/${ISSUE,,} -b "$BRANCH" origin/main
cd .worktrees/${ISSUE,,}

# ... make changes ...
git add -A && git commit -m "fix: implement $ISSUE"
git push -u origin "$BRANCH"
gh pr create --title "$ISSUE: <title>" --body "Closes $ISSUE"

Priority Levels

Level	Value	Use for
urgent	1	Production issues, blockers
high	2	This week, important
medium	3	This sprint/cycle
low	4	Nice to have
none	0	Backlog, someday

Teams (cached)

Team keys and IDs are discovered via the API and cached locally after the first lookup. Use linear.sh teams to refresh and list available teams.

Notes

• Uses GraphQL API (api.linear.app/graphql)
• Requires LINEAR_API_KEY env var
• Issue identifiers are like TEAM-123

Attribution

Inspired by schpet/linear-cli by Peter Schilling (ISC License). This is an independent bash implementation for Clawdbot integration.