sloanelybutsurely/linear-skill
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
linear-skill/SKILL.md
sloane 3fbe53f8c1
initial commit
2025-11-04 15:28:18 -05:00

7.2 KiB
Raw Blame History

name description tags version
linear Expert guidance for Linear issue management and workflows using linear-cli - streamline issue tracking, project planning, and team collaboration from the command line
linear
issue-tracking
project-management
workflow
productivity
1.0.0

Linear CLI Skill

Expert assistance for managing Linear issues, projects, and teams using the linear-cli tool. This skill helps you work efficiently with Linear's issue tracking platform directly from your terminal, with built-in awareness of Git and Jujutsu version control workflows.

What is Linear?

Linear is a purpose-built software development platform for modern product teams. It provides:

  • Issue & Task Tracking: Optimized for fast, focused work
  • Project Planning: Visual timelines, milestones, and specifications
  • Sprint Management: Cycles for building healthy team routines
  • Triage: Manage incoming bugs and feature requests
  • Analytics: Real-time insights and reporting
  • Integrations: 100+ external tools including Git, Figma, and AI assistants

What is linear-cli?

linear-cli is a command-line tool that bridges Linear issue tracking with development workflows. It's VCS-aware (works with both Git and Jujutsu) to keep you in the right views in Linear based on your current branch or commit.

Key Benefits:

  • Manage issues without leaving the terminal
  • Automatic issue detection from Git branches (e.g., eng-123-my-feature)
  • Jujutsu integration via Linear-issue trailers in commit descriptions
  • Create pull requests with auto-populated issue details
  • Quick navigation to issues in browser, desktop app, or terminal

Core Capabilities

Issue Management

View and Navigate Issues:

# View issue details (auto-detects from current branch/commit)
linear issue view
linear issue view ENG-123

# Open issue in browser or Linear app
linear issue view --web
linear issue view --app

# Get issue information
linear issue id              # Print issue ID from current branch
linear issue title           # Print issue title
linear issue url             # Print issue URL
linear issue describe        # Print title and Linear-issue trailer

List and Search:

# List your issues
linear issue list

# Filter and search options available via the list command

Create and Update:

# Create a new issue (interactive)
linear issue create

# Update an issue
linear issue update          # Updates current issue
linear issue update ENG-123  # Updates specific issue

# Delete an issue
linear issue delete ENG-123

Workflow Actions:

# Start working on an issue
linear issue start           # Start current issue
linear issue start ENG-123   # Start specific issue

# Create GitHub PR with Linear issue details
linear issue pr              # For current issue
linear issue pr ENG-123      # For specific issue

Team Management

# List teams
linear team list

# Get configured team ID
linear team id

# List team members
linear team members          # Current team
linear team members ENG      # Specific team

# Create a team
linear team create

# Configure GitHub repository autolinks
linear team autolinks

Project Management

# List projects
linear project list

# View project details
linear project view PROJECT-123
linear project v PROJECT-123  # Shorthand

Configuration

# Initial setup (creates .linear.toml)
linear config

# Generate shell completions
linear completions

Configuration Setup

First-time setup requires:

  1. Linear API key (get from Linear settings)
  2. Workspace selection
  3. Default team selection

The tool creates a .linear.toml file with these settings.

Version Control Integration

Git Integration

  • Automatically detects issue IDs from branch names
  • Common patterns: eng-123-feature-name, ENG-123-bug-fix
  • Commands like linear issue view auto-detect the current issue

Jujutsu (jj) Integration

  • Reads Linear-issue trailers from commit descriptions
  • Use linear issue describe to generate proper trailer format
  • Seamless workflow with jj's change-centric model

Common Workflows

Starting Work on an Issue

# 1. List available issues
linear issue list

# 2. Start working on an issue (updates status)
linear issue start ENG-123

# 3. Create branch (if using Git)
git checkout -b eng-123-feature-name

# 4. Or with jj, add trailer to description
jj describe -m "Implement feature\n\nLinear-issue: ENG-123"

Creating a Pull Request

# Auto-populate PR with Linear issue details
linear issue pr

# This creates a GitHub PR with:
# - Issue title in PR title
# - Issue description in PR body
# - Automatic linking back to Linear

Quick Issue Lookup

# From any branch, quickly check what you're working on
linear issue title
linear issue url --web  # Open in browser

Tips and Best Practices

  1. Branch Naming: Use consistent patterns like team-key-123-description for automatic issue detection
  2. Configuration: Run linear config in each project directory for project-specific settings
  3. Shell Completions: Install completions for faster command entry
  4. Issue IDs: Most commands accept optional issueId - omit it to use current branch/commit
  5. PR Integration: Use linear issue pr to maintain Linear ↔ GitHub linkage
  6. Quick Access: Alias common commands (e.g., alias li='linear issue')

Command Reference

Command Alias Description
linear issue linear i Manage issues
linear team linear t Manage teams
linear project linear p Manage projects
linear issue view linear i v View issue details
linear issue pull-request linear i pr Create GitHub PR
linear issue delete linear i d Delete issue

Help and Documentation

Common Issues and Solutions

Issue ID Not Detected:

  • Check branch name format matches expected patterns
  • Use explicit issue ID: linear issue view ENG-123
  • For jj, ensure Linear-issue trailer is in description

Configuration Not Found:

  • Run linear config in project directory
  • Verify .linear.toml exists and has correct API key

Permission Errors:

  • Check Linear API key has correct permissions
  • Verify team/workspace access

Assistant Guidelines

When helping users with Linear CLI:

  1. Context Awareness: Check if they're using Git or Jujutsu and provide appropriate guidance
  2. Issue Detection: Remind users that many commands auto-detect issues from current branch/commit
  3. Workflow Integration: Suggest ways to integrate Linear CLI into their development workflow
  4. Configuration First: If errors occur, verify linear config has been run
  5. Shell Integration: Recommend completions and aliases for power users
  6. Best Practices: Encourage consistent branch naming and proper issue linking

Always use the actual linear-cli commands available on the system rather than making assumptions about functionality.