name: linear-pm description: Linear project management - issues, projects, cycles, and roadmaps. Use for Linear-related tasks like managing issues, tracking sprints, and organizing projects. version: 1.0.0 model: sonnet invoked_by: both user_invocable: true tools: [Read, Bash, WebFetch] best_practices:

• Verify LINEAR_API_KEY is set
• Use filters to reduce API calls
• Cache team and project metadata error_handling: graceful streaming: supported

Mode: Cognitive/Prompt-Driven — No standalone utility script; use via agent context.

Linear PM Skill

Overview

This skill provides comprehensive Linear project management capabilities with progressive disclosure for optimal context usage.

Context Savings: ~92% reduction

• Direct API Mode: ~15,000 tokens for full API documentation
• Skill Mode: ~300 tokens metadata + on-demand loading

Requirements

• LINEAR_API_KEY environment variable set
• Internet connectivity for Linear API access

Toolsets

The skill provides 18+ tools across 5 toolsets:

Quick Reference

# List issues
linear-pm list-issues --team-id "TEAM-123" --state "In Progress"

# Get issue details
linear-pm get-issue --issue-id "ISSUE-456"

# Create new issue
linear-pm create-issue --title "Bug fix" --description "Details" --team-id "TEAM-123"

# Update issue
linear-pm update-issue --issue-id "ISSUE-456" --state "Done"

# Add comment
linear-pm add-comment --issue-id "ISSUE-456" --comment "Fixed in PR #123"

# List projects
linear-pm list-projects --team-id "TEAM-123"

# Get current cycle
linear-pm current-cycle --team-id "TEAM-123"

# List cycle issues
linear-pm cycle-issues --cycle-id "CYCLE-789"

Tools by Category

Issue Operations (Confirmation Required for Mutations)

Project Operations

Cycle Operations (Sprints)

Team Operations

Label & State Operations

Implementation

Tool Execution Pattern

All tools use the Linear GraphQL API with progressive disclosure:

#!/usr/bin/env bash
# Example: list-issues tool

LINEAR_API_KEY="${LINEAR_API_KEY}"
if [[ -z "$LINEAR_API_KEY" ]]; then
  echo "Error: LINEAR_API_KEY environment variable not set"
  exit 1
fi

QUERY='query {
  issues(filter: { state: { name: { eq: "In Progress" } } }) {
    nodes {
      id
      title
      state { name }
      assignee { name }
      priority
      createdAt
    }
  }
}'

curl -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"query\": \"$QUERY\"}"

Common Filters

Issue Filters:

• state: Filter by workflow state (e.g., "In Progress", "Done")
• assignee: Filter by assigned user ID
• priority: Filter by priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)
• label: Filter by label name
• team: Filter by team ID

Project Filters:

• state: Filter by project state (planned, started, paused, completed)
• lead: Filter by project lead user ID

Cycle Filters:

• isActive: Get only active cycles
• team: Filter by team ID

Security

API Key Protection:

• Never expose LINEAR_API_KEY in logs or output
• API key should have minimal required permissions
• Use read-only API key when possible for queries

Mutation Confirmation: All tools that modify data require confirmation:

• Issue creation/updates
• Comment additions
• Project modifications
• Label creation

Read-Only Operations (No Confirmation):

• Listing issues, projects, cycles
• Getting details
• Searching

Error Handling

If tool execution fails:

1. Verify API Key: Check LINEAR_API_KEY is set correctly

   echo $LINEAR_API_KEY
   

2. Check API Rate Limits: Linear enforces rate limits

   • GraphQL: 1500 requests per hour per API key
   • REST: 500 requests per hour per API key

3. Validate Query Syntax: Ensure GraphQL queries are well-formed

4. Check Team/Issue IDs: Verify IDs exist and are accessible

Agent Integration

Primary Agents:

• pm - Product management and backlog prioritization
• analyst - Issue analysis and sprint planning

Secondary Agents:

• developer - Issue implementation and status updates
• architect - Technical issue decomposition
• qa - Issue testing and validation

Common Workflows

Sprint Planning

1. current-cycle - Get current sprint
2. list-issues --state "Backlog" - Get backlog items
3. update-issue --cycle-id "..." - Assign issues to sprint

Issue Triage

1. list-issues --state "Backlog" - Get unplanned issues
2. set-priority --issue-id "..." --priority 2 - Set priority
3. add-label --issue-id "..." --label "bug" - Categorize

Project Tracking

1. list-projects --team-id "..." - Get all projects
2. project-issues --project-id "..." - Get project issues
3. cycle-progress --cycle-id "..." - Check sprint progress

Related

• Official Linear API Documentation: https://developers.linear.app/docs/graphql/working-with-the-graphql-api
• Linear GraphQL Explorer: https://studio.apollographql.com/public/Linear-API/home
• Linear Webhook Documentation: https://developers.linear.app/docs/graphql/webhooks

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.