shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

managing-linear-issues

使用Linearis CLI进行Linear.app问题管理，支持JSON输出和智能ID解析。在创建、查看、更新或搜索Linear问题，管理冲刺/周期，或列出团队/项目时使用。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

Linear Integration Skill

Purpose: Issue management for Linear.app using Linearis CLI with JSON output optimized for LLM agents.

Tool: Linearis CLI - npm package linearis

Table of Contents

  1. Prerequisites
  2. Decision Tree
  3. Quick Command Reference
  4. Pattern Recognition - Auto-Invocation
  5. Workflow Examples
  6. Error Handling
  7. Authentication Strategy
  8. JSON Output Handling

Prerequisites

Verify Installation

# Check CLI installed
linearis --version

Authentication (Priority Order)

IMPORTANT: Always check for project-specific credentials first. Different projects may use different Linear workspaces.

  1. Project .env (PREFERRED - project-specific):

    # Check project .env for LINEAR_API_KEY
grep LINEAR_API_KEY .env

# Run commands with project token
export LINEAR_API_TOKEN="$(grep LINEAR_API_KEY .env | cut -d= -f2)"
linearis teams list

  2. Environment Variable (session override):

    export LINEAR_API_TOKEN="lin_api_xxx"

Running Commands with Project Credentials

# Inline token from project .env (recommended)
LINEAR_API_TOKEN=$(grep LINEAR_API_KEY .env | cut -d= -f2) linearis <command>

# Or export for session
export LINEAR_API_TOKEN=$(grep LINEAR_API_KEY .env | cut -d= -f2)
linearis <command>

Decision Tree

Issue Operations

User wants to...
├── View issue details
│   └── linearis issues read <ISSUE-ID>
├── Create new issue
│   └── linearis issues create "Title" --team <Team> [options]
├── Update existing issue
│   └── linearis issues update <ISSUE-ID> [--state|--assignee|--priority]
├── Search issues
│   └── linearis issues search "query" [--team|--limit]
├── List recent issues
│   └── linearis issues list [--limit N] [--team Name]
└── Delete issue (soft)
    └── linearis issues update <ISSUE-ID> --trashed

Metadata Operations

User wants to...
├── List teams
│   └── linearis teams list
├── List projects
│   └── linearis projects list
├── List cycles/sprints
│   └── linearis cycles list [--team Name] [--active]
├── List labels
│   └── linearis labels list [--team Name]
└── List users
    └── linearis users list [--active]

Comments

Add a comment to an issue
└── linearis comments create <ISSUE-ID> --body "Comment text"

Quick Command Reference

Issues CRUD

| Operation | Command | Example | |-----------|---------|---------| | List | linearis issues list | linearis issues list --limit 10 --team TractionBD | | Search | linearis issues search "query" | linearis issues search "auth bug" | | Read | linearis issues read <ID> | linearis issues read TBD-456 | | Create | linearis issues create "Title" | linearis issues create "Fix login" --team TractionBD --priority 1 | | Update | linearis issues update <ID> | linearis issues update TBD-123 --state "In Review" |

Create Issue Options

linearis issues create "Title" \
  --team "TractionBD" \
  --assignee "user-id-or-name" \
  --labels "Bug,Critical" \
  --priority 1 \
  --project "Project Name" \
  --description "Detailed description" \
  --parent-ticket TBD-100

Priority values: 0 (none), 1 (urgent), 2 (high), 3 (medium), 4 (low)

Update Issue Options

linearis issues update TBD-123 \
  --state "In Review" \
  --assignee "new-user" \
  --priority 2 \
  --labels "Bug,P1" \
  --clear-labels \
  --parent-ticket TBD-200 \
  --trashed

Metadata Queries

# Teams
linearis teams list

# Projects
linearis projects list

# Labels (optionally by team)
linearis labels list --team TractionBD

# Users
linearis users list --active

# Cycles/Sprints
linearis cycles list --team TractionBD --active
linearis cycles list --team TractionBD --around-active 3

Comments

linearis comments create TBD-123 --body "This is a comment"

Pattern Recognition - Auto-Invocation

High Confidence Triggers (invoke immediately)

Issue Operations:
  - "Create a Linear issue for..."
  - "Open a ticket in Linear..."
  - "Log this as a Linear bug..."
  - "Check Linear issue TBD-123"
  - "What's the status of TBD-123?"
  - "Update TBD-123 to..."
  - "Move TBD-123 to In Review"
  - "Assign TBD-123 to..."
  - "Close Linear issue..."
  - "Search Linear for..."
  - "Find issues about..."

Sprint/Cycle Operations:
  - "What's in the current sprint?"
  - "Show active cycle for..."
  - "List team's cycles"

Metadata:
  - "List Linear teams"
  - "Show all projects in Linear"
  - "What labels are available?"
  - "Who can I assign this to?"

Issue ID Detection

# Linear issue ID pattern
[A-Z]{2,10}-\d+

# Examples: TBD-123, DEV-456, BACKEND-789

Context Signals

Strong indicators:
  - .env contains LINEAR_API_KEY
  - Recent messages mention "Linear"
  - Issue IDs in ABC-123 format present
  - User mentions "sprint", "cycle", "backlog"

Workflow Examples

Create Issue from Bug Report

User: "Create a Linear issue for the login timeout bug"

Steps:
  1. Parse request: title=login timeout bug
  2. Execute: linearis issues create "Login timeout bug" --team TractionBD --labels "Bug"
  3. Return: Issue ID and details from JSON response

Check Issue Status

User: "What's the status of TBD-123?"

Steps:
  1. Parse issue ID: TBD-123
  2. Execute: linearis issues read TBD-123
  3. Return: Issue title, state, assignee, priority from JSON

Update Issue State

User: "Move TBD-123 to In Review and assign to John"

Steps:
  1. Get user list: linearis users list --active
  2. Find John's ID from JSON
  3. Update: linearis issues update TBD-123 --state "In Review" --assignee john-id
  4. Confirm: linearis issues read TBD-123

Sprint Planning

User: "What issues are in the current sprint?"

Steps:
  1. Get active cycle: linearis cycles list --team TractionBD --active
  2. Parse cycle from JSON
  3. List issues: linearis issues list --team TractionBD --limit 50
  4. Filter by cycle in results

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | command not found: linearis | CLI not installed | npm install -g linearis | | No API token found | Missing authentication | Add LINEAR_API_KEY to project .env, then export as LINEAR_API_TOKEN | | Unauthorized | Invalid/expired token | Token may be for wrong workspace; check project .env | | Issue not found | Invalid issue ID or wrong workspace | Verify ID format and that you're using the correct project token | | Team not found | Invalid team name or wrong workspace | Run linearis teams list - may need different project token | | Rate limited | Too many requests | Wait 60s, retry with backoff |

Authentication Troubleshooting

Wrong workspace issues:
  Problem: Commands return unexpected teams/issues
  Cause: Using global token instead of project-specific token
  Fix: Check project .env and use that token

  # Verify which workspace you're connected to
  LINEAR_API_TOKEN=$(grep LINEAR_API_KEY .env | cut -d= -f2) linearis teams list

Graceful Fallback

If Linearis unavailable:
  1. Log the error for visibility
  2. Provide web URL: https://linear.app/[workspace]/issue/ABC-123
  3. Suggest manual action with instructions

Authentication Strategy

Priority Order:
  1. Project .env (LINEAR_API_KEY) - project-specific workspaces
  2. LINEAR_API_TOKEN env var - session override

Before Running Commands:
  1. Check if project has .env with LINEAR_API_KEY
  2. Export token for session
  3. If no project .env, prompt user to add LINEAR_API_KEY

Example:
  export LINEAR_API_TOKEN="$(grep LINEAR_API_KEY .env | cut -d= -f2)"
  linearis teams list

JSON Output Handling

Linearis outputs JSON. Parse and extract relevant fields:

# Get issue title
linearis issues read TBD-123 | jq -r '.title'

# Get issue state
linearis issues read TBD-123 | jq -r '.state.name'

# List issue identifiers and titles
linearis issues list --limit 10 | jq -r '.[] | "\(.identifier): \(.title)"'