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:

issues

projects

cycles

teams

labels

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)

list-issues

get-issue

create-issue

update-issue

add-comment

search-issues

assign-issue

set-priority

add-label

Project Operations

list-projects

get-project

project-issues

create-project

update-project

Cycle Operations (Sprints)

list-cycles

current-cycle

cycle-issues

cycle-progress

Team Operations

list-teams

get-team

team-members

Label & State Operations

list-labels

list-states

create-label

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.