Linear

Linear Skill

Manage your Linear workspace from the command line with persistent session memory.

Project Configuration

Before using this skill, read config.json for project-specific values:

• team - The team key to use (e.g., "WIL")
• defaultProject - Default project ID for new issues
• projects - Named project shortcuts with IDs and descriptions
• priorityContext - What priority levels mean for this project's current phase
• labels - Label name to ID mappings
• workflows - Default states/priorities for different issue types

Use these values instead of the generic TEAM placeholders in examples below.

Project Conventions

This section documents agreed-upon conventions for using Linear. Customize these for your project.

Priority Definitions

Key behaviors:

• Urgent: Developer patches immediately; stakeholders notified
• High: Must be completed before production deployment
• Medium: Scheduled alongside feature work
• Low: Kept in backlog, won't delay deadlines

Status Workflow

┌─────────────────┐     ┌─────────────┐
│  CLIENT REVIEW  │     │   TRIAGE    │
│  (Client Inbox) │     │ (Dev Inbox) │
└────────┬────────┘     └──────┬──────┘
         │                     │
         └──────────┬──────────┘
                    ▼
              ┌───────────┐
              │   TO DO   │
              └─────┬─────┘
                    ▼
              ┌───────────┐
              │IN PROGRESS│
              └─────┬─────┘
                    ▼
              ┌───────────┐
              │  DEV DONE │
              └─────┬─────┘
                    ▼
            ┌─────────────┐
            │READY TO TEST│
            └──────┬──────┘
                   ▼
              ┌──────────┐
              │   DONE   │
              └──────────┘

Transition responsibilities:

• → Client Review: Developer creates ticket from planning/meetings
• Client Review → To Do: Client approves after reviewing
• → Triage: Client reports bug directly
• Triage → To Do: Developer reviews, sets priority
• To Do → In Progress: Developer picks up work
• In Progress → Dev Done: Code complete
• Dev Done → Ready to Test: Deployed to staging
• Ready to Test → Done: Client tests successfully

Inbox goal: Both Client Review and Triage should trend toward empty.

Projects

Organize work into projects based on your needs:

Assignment rules:

• Production bugs → Support project
• New features → Appropriate feature project
• Urgent hot fixes → May skip project assignment (priority is enough)

Labels

Communication

• Linear is the primary channel for project work
• Use comments within tickets for discussion
• @ mentions notify via inbox
• Check inbox regularly for messages

Creating Issues from Transcripts

When generating issues from meeting transcripts:

1. Set status to Client Review (not Triage) - Client needs to approve
2. Include in description:
   • Context from discussion
   • Location in app (if applicable)
   • Steps to reproduce (for bugs)
   • Acceptance criteria (for features)
3. Set priority based on meeting discussion
4. Assign to project based on type
5. Add appropriate label (bug/feature/improvement)

Checking Your Inbox

Your Linear inbox contains notifications about issues you're assigned to, mentioned in, or have subscribed to. This is how client feedback and updates reach you.

Commands:

# View all notifications (most recent first)
npx linear-skill inbox

# View only unread notifications
npx linear-skill inbox --unread

# Limit to specific count
npx linear-skill inbox --unread --limit 10

Notification types include:

• issueAssignedToYou - You were assigned to an issue
• issueNewComment - Someone commented on an issue you follow
• issueMention - You were @mentioned in a comment
• issueStatusChanged - Status changed on an issue you follow
• And many more...

Workflow tip: Check your inbox at the start of each session to see client feedback and updates since your last session. This is especially useful for catching comments on recently completed work.

Reading Comments & Client Feedback

Comments contain important client feedback, clarifications, and discussion history. Use them strategically to stay context-efficient.

When to use --comments flag or comments command:

• Planning implementation for specific tickets (1-5 tickets)
• Reviewing client feedback before starting work
• Checking for clarifications or scope changes
• Preparing spec documents that need client context

When NOT to fetch comments:

• Broad searches across many tickets (issues --team TEAM)
• Filtering/triaging tickets by status or priority
• Quick status checks or updates
• Bulk operations

Commands:

# Lightweight - just comments for quick review
npx linear-skill comments TEAM-123

# Full context - issue details + comments for implementation planning
npx linear-skill issue TEAM-123 --comments

Workflow tip: When moving tickets from To Do to In Progress, fetch comments first to ensure you have the latest client context before writing implementation specs.

Viewing Screenshots & Attachments

Issues often include screenshots showing bugs, UI states, or expected behavior. The skill returns signed URLs that are publicly accessible for 1 hour.

Output fields when using --comments:

• inlineImages - Images embedded in description or comments (extracted from markdown ![alt](url))
• attachments - Files attached to the issue

Workflow to view screenshots:

1. Fetch the issue with comments to get signed URLs:

   npx linear-skill issue TEAM-123 --comments
   

2. Download images to the skill's cache directory:

   # Create cache directory if needed
   mkdir -p ~/.linear-skill/images
   
   # Download each image (use the signed URL from output)
   curl -s -o ~/.linear-skill/images/screenshot-1.png "<signed-url>"
   

3. View the image using the Read tool:

   # Claude can view the downloaded image
   Read ~/.linear-skill/images/screenshot-1.png
   

4. Clean up after reviewing (images are not auto-deleted):

   rm ~/.linear-skill/images/*.png
   

Important notes:

• Signed URLs expire after 1 hour - re-fetch the issue if URLs have expired
• macOS does NOT auto-clean /tmp, so use ~/.linear-skill/images/ for predictable cleanup
• Always review screenshots before implementing bug fixes to understand the exact issue
• Multiple screenshots may show different states (before/after, different views, etc.)

Release Workflow

For staging → production releases:

1. All High priority items must be Done
2. Medium items are optional for current release
3. Low items are explicitly deferred
4. Once all required items are Done, deploy to production

Semantic versioning may be adopted for tracking releases.

Starting a Session

Always load context first to see what you were working on:

npx linear-skill context

This shows:

• Recent session summaries
• Focus tickets from last session
• Recent actions taken
• Any notes you left

Quick Start

# Setup (one time)
cp .env.example .env
cp config.example.json config.json
# Edit .env with your LINEAR_API_KEY
npm install && npm run build

# Load previous context
npx linear-skill context

# List your assigned issues
npx linear-skill issues --assignee me

# Create an issue (for transcript-generated tickets, use Client Review state)
npx linear-skill create "Fix login bug" --team TEAM --state "Client Review"

# Update an issue
npx linear-skill update TEAM-123 --state "In Progress"

# Quick actions
npx linear-skill start TEAM-123    # Move to "In Progress"
npx linear-skill done TEAM-123     # Move to "Done"

# Mark tickets as current focus
npx linear-skill focus TEAM-123 TEAM-456

# Save session before ending
npx linear-skill session-save "Completed auth work, PR ready for review"

Session Memory

The skill remembers your recent work across conversations:

• Auto-tracking: All issue interactions are logged automatically
• Focus tickets: Mark what you're actively working on
• Session summaries: 2-3 recent session summaries are kept
• Context command: Loads this into new conversations

Command Categories

Read Commands

• teams - List all teams
• users - List users (use --me for current user)
• states --team TEAM - List workflow states
• projects - List projects
• cycles --team TEAM - List cycles (--active for current)
• issues - List issues with filters
• issue TEAM-123 - Get issue details
• issue TEAM-123 --comments - Get issue details with comments
• comments TEAM-123 - Get comments for an issue
• search "query" - Search issues
• inbox - List notifications from your inbox
• inbox --unread - List only unread notifications

Write Commands

• create "title" --team TEAM - Create issue
• update TEAM-123 --state "Done" - Update issue
• assign TEAM-123 me - Assign issue
• comment TEAM-123 "comment text" - Add comment
• start TEAM-123 - Move to "In Progress"
• done TEAM-123 - Move to "Done"

Session Commands

• context - Load session context (use at start)
• focus TEAM-123 TEAM-456 - Set focus tickets
• notes "reminder text" - Set session notes
• session-save "summary" - Save session summary
• sessions - View session history
• session-clear --older-than 7 - Clear old data

Config Commands

• init - Initialize configuration
• config - Show current config
• cache-refresh - Refresh teams/users/states cache
• cache-status - Show cache status

Issue Filtering

The issues command supports flexible filtering with multiple values for most parameters.

Available Filter Options

Priority Values

Filtering Examples

# Basic filters
npx linear-skill issues --team TEAM
npx linear-skill issues --assignee me
npx linear-skill issues --state "To Do"

# Priority filtering (CRITICAL for hotfix workflow)
npx linear-skill issues --team TEAM --priority 1              # Urgent only
npx linear-skill issues --team TEAM --priority urgent         # Same as above
npx linear-skill issues --team TEAM --priority 1,2            # Urgent and High
npx linear-skill issues --team TEAM -P urgent -P high         # Same as above

# Multiple states
npx linear-skill issues --team TEAM -s "To Do" -s "In Progress"
npx linear-skill issues --state "Triage,Client Review"        # Comma syntax

# Label filtering (matches issues with ANY of the labels)
npx linear-skill issues --team TEAM --label "Bug"
npx linear-skill issues --team TEAM -L "Bug" -L "Feature"

# Combined filters
npx linear-skill issues --team TEAM --priority 1 --state "To Do"
npx linear-skill issues --team TEAM --assignee me --priority 1,2 --limit 20

# Find all inbox items (Triage + Client Review)
npx linear-skill issues --team TEAM -s "Triage" -s "Client Review"

# Production hotfix query
npx linear-skill issues --team TEAM --priority urgent --state "To Do"

Bulk Operations for Transcript Processing

When creating multiple issues from a meeting transcript:

# Create each ticket with Client Review status
npx linear-skill create "Ticket title" --team TEAM --state "Client Review" --priority 2 -d "Description here"

# After client reviews, they move approved tickets to To Do
npx linear-skill update TEAM-123 --state "To Do"

Setup

1. Copy .env.example to .env
2. Add your Linear API key: LINEAR_API_KEY=lin_api_xxxx
3. Copy config.example.json to config.json
4. Set your default team in config.json
5. Run npm install && npm run build
6. Test: npx linear-skill teams

Skill Initialization

If this skill has not been configured for the current project, help the user set it up:

Check if initialized

npx linear-skill config

If team is "YOUR_TEAM_KEY" or missing, initialization is needed.

Initialization steps

1. Verify .env has LINEAR_API_KEY set

2. Discover workspace:

   npx linear-skill teams      # Get team key
   npx linear-skill projects   # Get project IDs and names
   npx linear-skill states --team TEAM_KEY  # Check workflow states
   

3. Ask the user:

   • Which team to use as default?
   • How to categorize their projects (support, feature phases)?
   • What does "High priority" mean for their current work?
   • What is their current project phase?

4. Update config.json with discovered values

5. Check for missing workflow states (Client Review, Dev Done, Ready to Test) and guide user to create them in Linear UI

6. Refresh cache:

   npx linear-skill cache-refresh
   

Documentation

• README.md - Developer setup guide
• REFERENCE.md - Full command reference
• CONFIG.md - Configuration guide
• SESSION.md - Session memory details