Agent-Skills.md

Agent Skills: Linear Issue Tracking - Complete Reference

Linear issue tracking - MUST READ before using Linear commands

UncategorizedID: alienfast/claude/linear

Repository

alienfast/claude
alienfastLicense: MIT

Install this agent skill to your local

pnpm dlx add-skill https://github.com/alienfast/claude/tree/HEAD/skills/linear

Skill Files

Browse the full folder contents for linear.

Download Skill

Loading file tree…

skills/linear/SKILL.md

Skill Metadata

Name
linear
Description
Linear issue tracking - MUST READ before using Linear commands

Linear Issue Tracking - Complete Reference

READ THIS FIRST - Token-efficient CLI for managing issues, dependencies, and cycles.

⚠️ INSTALL ALL SKILLS FOR FULL WORKFLOW AUTOMATION

Run linear skills install --all to get specialized workflows:

  • /prd - Create agent-friendly tickets with PRDs
  • /triage - Prioritize backlog by staleness and blockers
  • /cycle-plan - Plan cycles using velocity analytics
  • /retro - Generate sprint retrospectives
  • /deps - Analyze dependency chains and blockers
  • /link-deps - Discover and link related issues

Without these skills, you're only using basic commands. Install them to unlock full agentic capabilities.

Authentication Modes

When you run linear auth login, you choose:

  • User mode: --assignee me assigns to your personal Linear account
  • Agent mode: --assignee me assigns to the OAuth app (delegate), visible as a separate entity

Check current mode:

linear auth status   # Shows: Mode: User or Mode: Agent

Important: If you see "Auth mode not set", re-run linear auth login to configure.

Command Reference

# Setup
linear init                              # Set default team (.linear.yaml)
linear onboard                           # Show teams, states, quick reference
linear auth login|logout|status          # OAuth authentication (sets user/agent mode)

# Issues (alias: i)
linear i list [flags]                    # List issues
linear i get <ID>                        # Get details (CEN-123)
linear i create <title> [flags]          # Create issue
linear i update <ID> [flags]             # Update issue
linear i comment <ID> -b "text"          # Add comment
linear i react <ID> 👍                   # Add reaction

# Projects (alias: p)
linear p list [--mine]                   # List projects
linear p create <name> [flags]           # Create project

# Cycles (alias: c)
linear c list [--active]                 # List cycles
linear c get <number>                    # Get cycle (requires init)
linear c analyze --team <KEY>            # Velocity analytics

# Teams, Users
linear teams list                        # List teams
linear teams states <KEY>                # Workflow states
linear users list [--team <KEY>]         # List users

# Search & Dependencies
linear search <query> [flags]            # Semantic search across all entities
linear deps <ID>                         # Dependency graph
linear deps --team <KEY>                 # All team dependencies

Output Formats

All commands support JSON output for automation:

# Text output (default) - token-efficient ASCII
linear i list
linear i get CEN-123

# JSON output - machine-readable
linear i list --output json
linear i get CEN-123 --output json

# Control detail level with --format
linear i list --format minimal --output json   # Essential fields (~50 tokens)
linear i list --format compact --output json   # Key metadata (~150 tokens, default)
linear i list --format full --output json      # Complete details (~500 tokens)

# Pipe to jq for filtering
linear i list --priority 1 --output json | jq '.[] | select(.state == "In Progress")'

# Export for processing
linear cycles analyze --team CEN --output json > velocity.json

When to use JSON:

  • Parsing data programmatically
  • Filtering results with jq
  • Storing/processing bulk data
  • Integrating with other tools

Supported commands:

  • issues list, issues get
  • cycles list, cycles get, cycles analyze
  • projects list, projects get
  • teams list, teams get, teams labels, teams states
  • users list, users get, users me
  • search (all operations)

Semantic Search

The search is SEMANTIC - finds related issues even without exact matches.

# Basic semantic search
linear search "authentication"           # Finds: auth, login, OAuth, SSO, etc.

# Cross-entity search
linear search "sprint planning" --type all     # Search issues, cycles, projects, users

# Entity-specific
linear search "database migration" --type issues
linear search "john" --type users

Dependency Management

Finding Blocked Work (Critical for Unblocking)

# Find ALL blocked issues (run this weekly!)
linear search --has-blockers --team CEN

# Find high-priority blocked work
linear search --priority 1 --has-blockers --team CEN

# What's blocked by a specific bottleneck?
linear search --blocked-by CEN-123

# What blocks a critical feature?
linear search --blocks CEN-456

Dependency Analysis

# Visualize full dependency graph for issue
linear deps CEN-123

# See all team dependencies (detect circular deps)
linear deps --team CEN

# Find issues with circular dependencies
linear search --has-circular-deps --team CEN

# Find deep dependency chains
linear search --max-depth 5 --team CEN

Cycle Analytics & Velocity

Analyze past cycles to predict capacity:

# Analyze last 10 cycles
linear c analyze --team CEN --count 10

# Output shows:
# - Completed vs planned points
# - Velocity trend
# - Completion rate
# - Recommendations for next cycle capacity

Use before sprint planning to set realistic goals!

Powerful Filter Combinations

# High-priority in-progress work assigned to me
linear i list --priority 1 --state "In Progress" --assignee me

# Backlog items with blockers (prioritize removing blockers!)
linear search --state Backlog --has-blockers --team CEN

# Customer-facing bugs in current cycle
linear i list --labels customer,bug --cycle 65 --format full

# Unassigned high-priority work
linear search --priority 1 --assignee none --team CEN

# Work depending on other issues (check before starting)
linear search --has-dependencies --state "In Progress" --team CEN

Creating Issues with Dependencies

# Simple issue
linear i create "Fix login bug" --team CEN --priority 1

# Full issue with dependencies
linear i create "Add OAuth integration" \
  --team CEN \
  --state "In Progress" \
  --priority 2 \
  --assignee me \
  --parent CEN-100 \
  --depends-on CEN-99 \
  --blocked-by CEN-98 \
  --labels backend,security \
  --estimate 5 \
  --cycle 65 \
  --project "Auth Revamp" \
  --due 2026-02-01

# With description from file (use linear-stdin.sh to avoid permission prompts)
~/.claude/scripts/linear-stdin.sh spec.md i create "Feature title" --team CEN -d -

Passing File Content to Linear CLI

All description and body flags support stdin via -. Use ~/.claude/scripts/linear-stdin.sh to pass file content — it wraps the stdin redirect so Bash permission wildcards match correctly.

# Usage: ~/.claude/scripts/linear-stdin.sh <file> <linear-args...>

# Create issue with description from file
~/.claude/scripts/linear-stdin.sh tmp/description.md i create "Feature title" \
  --team CEN \
  --priority 1 \
  -d -

# Update issue description
~/.claude/scripts/linear-stdin.sh tmp/linear-description-cen-123.md i update CEN-123 -d -

# Add comment from file
~/.claude/scripts/linear-stdin.sh tmp/linear-comment-cen-123.md i comment CEN-123 -b -

Standard workflow for any command that passes file content:

  1. Use the Write tool to save content to tmp/<descriptive-name>.md
  2. Run ~/.claude/scripts/linear-stdin.sh tmp/<file>.md <linear-args> -d - (or -b - for comments)

Why not use shell redirects directly? Claude Code's Bash permission wildcards don't match through shell operators (<, |, $()). The helper script wraps the redirect internally so permissions work.

For short inline values (no file needed):

# Short descriptions/comments can be passed directly as arguments
linear i create "Fix login bug" --team CEN --priority 1 -d "Brief description here"
linear i comment CEN-123 -b "Quick status update"

Output Formats (Token Efficiency)

# Minimal - most token-efficient (IDs only)
linear i list --format minimal

# Compact - balanced (default)
linear i list --format compact

# Full - all details (use for single issues)
linear i get CEN-123 --format full
linear search "auth" --limit 5 --format full

Real-World Workflows

Weekly Unblocking Routine

# 1. Find all blocked work
linear search --has-blockers --team CEN --format full

# 2. For each blocker, check status
linear i get CEN-123 --format full

# 3. Update blockers or reassign blocked work
linear i update CEN-123 --state "In Progress" --assignee me

Sprint Planning

# 1. Check velocity
linear c analyze --team CEN --count 5

# 2. Find backlog candidates
linear search --state Backlog --team CEN --format compact

# 3. Check dependencies before committing
linear deps --team CEN

# 4. Assign to cycle
linear i update CEN-456 --cycle 66 --assignee alice@co.com

Dependency Discovery (Before Creating Issues)

# 1. Search for related work
linear search "authentication refactor" --team CEN

# 2. Check what depends on foundation work
linear search --depends-on CEN-100

# 3. Link new issue to dependencies
linear i create "Add JWT refresh" --depends-on CEN-100,CEN-101

Finding Work Order

# 1. Visualize dependencies
linear deps --team CEN

# 2. Start with issues that have no blockers
linear search --state Backlog --team CEN | grep -v "Blocked by"

# 3. Work that unblocks the most
linear search --blocking <critical-feature-id>

Common Patterns

# Find work for specific person
linear i list --assignee alice@company.com --format compact

# High-priority work in active cycle
linear i list --priority 1 --cycle current --team CEN

# All bugs
linear i list --labels bug --team CEN

# Overdue issues
linear i list --state "In Progress" --team CEN # Check due dates manually

# Issues I created
linear i list --creator me --team CEN

Tips for LLMs

  1. Always run linear init first - sets default team
  2. Use semantic search liberally - finds related work without exact keywords
  3. Check blockers weekly - linear search --has-blockers prevents stalled work
  4. Analyze velocity before planning - linear c analyze gives realistic estimates
  5. Visualize dependencies - linear deps --team <KEY> shows work order
  6. Use --format full sparingly - token-expensive, use for single issues only
  7. Combine filters - search is powerful with multiple constraints
  8. Issue IDs work everywhere - CEN-123 format, no team context needed
  9. Cycle numbers need init - Run linear init before using cycle numbers

Flag Reference

Issue Flags:

  • -t, --team <KEY> - Team (from init or manual)
  • -s, --state <name> - Workflow state
  • -p, --priority <0-4> - 0=none, 1=urgent, 2=high, 3=normal, 4=low
  • -a, --assignee <email|me> - Assign to user
  • -c, --cycle <number> - Cycle number
  • -P, --project <name> - Project name
  • -e, --estimate <points> - Story points
  • -l, --labels <list> - Comma-separated
  • -d, --description <text|-> - Description (- for stdin)
  • --parent <ID> - Parent issue
  • --depends-on <IDs> - Comma-separated dependencies
  • --blocked-by <IDs> - Comma-separated blockers
  • --due <date> - Due date (YYYY-MM-DD)
  • --attach <file> - Attach file

Search Flags:

  • --type <entity> - issues, cycles, projects, users, all
  • --blocked-by <ID> - Issues blocked by this
  • --blocks <ID> - Issues that block this
  • --has-blockers - Any blockers
  • --has-dependencies - Any dependencies
  • --has-circular-deps - Circular dependency chains
  • --max-depth <n> - Max dependency depth
  • -n, --limit <n> - Results limit
  • -f, --format <type> - minimal, compact, full

Output Formats:

  • --format minimal - IDs only (most token-efficient)
  • --format compact - Balanced (default)
  • --format full - All details (use sparingly)