linear-skill

name	linear-skill
description	Read and manage Linear issues, projects, and cycles. Use when the user asks to check Linear, view issues, find tasks, check sprint status, or manage work items. Helps inform daily standups and work planning.
allowed-tools	Bash, Read

Linear Skill - Issue & Project Management

Read, search, and manage Linear issues. Access teams, cycles, and projects to inform daily work.

First-Time Setup (~2 minutes)

1. Create a Personal API Key

1. Go to Linear Settings
2. Or: Settings > Account > Security & Access > Personal API keys
3. Click Create key
4. Name it (e.g., "Claude Assistant")
5. Select permissions: Read (minimum), or Read + Write for full access
6. Click Create and copy the key (starts with lin_api_)

2. Save API Key

Create the config file:

echo '{"api_key": "lin_api_YOUR_KEY_HERE"}' > ~/.claude/skills/linear-skill/config.json

Commands

My Issues (Assigned to Me)

python3 ~/.claude/skills/linear-skill/linear_skill.py my-issues [--limit N] [--status STATUS]

Shows issues assigned to you, perfect for daily standup prep.

List Teams

python3 ~/.claude/skills/linear-skill/linear_skill.py teams

Team Issues

python3 ~/.claude/skills/linear-skill/linear_skill.py issues TEAM [--limit N] [--status STATUS] [--priority PRIORITY]

Arguments:

• TEAM - Team key (e.g., ENG, EPO) or team name
• --status / -s - Filter by status: backlog, todo, in_progress, done, canceled
• --priority / -p - Filter by priority: urgent, high, medium, low, none
• --limit / -l - Number of issues (default: 20)

Get Issue Details

python3 ~/.claude/skills/linear-skill/linear_skill.py issue ISSUE_ID

ISSUE_ID can be the issue identifier (e.g., EPO-123) or the UUID.

Current Cycle (Sprint)

python3 ~/.claude/skills/linear-skill/linear_skill.py cycle TEAM

Shows the active cycle/sprint for a team with progress stats.

List Cycles

python3 ~/.claude/skills/linear-skill/linear_skill.py cycles TEAM [--limit N]

Search Issues

python3 ~/.claude/skills/linear-skill/linear_skill.py search "query" [--limit N]

Create Issue

python3 ~/.claude/skills/linear-skill/linear_skill.py create TEAM --title "Title" [--description "Desc"] [--priority PRIORITY] [--project PROJECT]

Arguments:

• TEAM - Team key (e.g., EPO)
• --title / -t - Issue title (required)
• --description / -d - Issue description
• --priority / -p - Priority: urgent, high, medium, low, none
• --project - Project name to assign issue to

Update Issue

python3 ~/.claude/skills/linear-skill/linear_skill.py update ISSUE_ID [--status STATUS] [--project PROJECT]

Arguments:

• ISSUE_ID - Issue identifier (e.g., EPO-123)
• --status / -s - New status
• --project - Move issue to a different project

Reorder Issues

python3 ~/.claude/skills/linear-skill/linear_skill.py reorder ISSUE1 ISSUE2 ISSUE3...

Reorder issues within their lane by setting sortOrder. Issues are listed in priority order (first = top of list).

Arguments:

• ISSUE1 ISSUE2... - Issue identifiers in desired order
• --base - Starting sortOrder value (default: 0.0)
• --increment - Increment between issues (default: 1.0)

Example:

# Reorder In Progress lane: EPO-485 at top, then EPO-480, then EPO-397
python3 ~/.claude/skills/linear-skill/linear_skill.py reorder EPO-485 EPO-480 EPO-397

List Projects

python3 ~/.claude/skills/linear-skill/linear_skill.py projects [TEAM]

Workflow Examples

Morning Standup Prep

# See what's assigned to you
python3 ~/.claude/skills/linear-skill/linear_skill.py my-issues --status in_progress

# Check current sprint status
python3 ~/.claude/skills/linear-skill/linear_skill.py cycle EPO

Check Team Backlog

python3 ~/.claude/skills/linear-skill/linear_skill.py issues EPO --status todo --priority high

Find Specific Work

python3 ~/.claude/skills/linear-skill/linear_skill.py search "authentication bug"

Quick Issue Creation

python3 ~/.claude/skills/linear-skill/linear_skill.py create EPO --title "Fix login timeout" --priority high

Board Grooming (Reorder Lanes)

# Reorder In Progress by priority
python3 ~/.claude/skills/linear-skill/linear_skill.py reorder EPO-485 EPO-480 EPO-397 EPO-457

# Reorder Todo backlog
python3 ~/.claude/skills/linear-skill/linear_skill.py reorder EPO-435 EPO-472 EPO-451

Create Issue in Project

python3 ~/.claude/skills/linear-skill/linear_skill.py create EPO --title "New feature" --project "Zerg AI Platform"

Move Issue to Project

python3 ~/.claude/skills/linear-skill/linear_skill.py update EPO-123 --project "Zerg AI Platform"

Output

All commands output JSON for easy parsing. Issue output includes:

• identifier - e.g., EPO-123
• title
• status - Current workflow state
• priority - 0 (none) to 1 (urgent)
• assignee - Who it's assigned to
• cycle - Sprint/cycle info if applicable
• labels - Applied labels
• estimate - Story points if set

Status Values

Linear workflow states map to these common statuses:

• backlog - Not yet planned
• todo - Planned but not started
• in_progress - Currently being worked on
• in_review - Under review
• done - Completed
• canceled - Won't do

Priority Values

• urgent (1) - Drop everything
• high (2) - Important
• medium (3) - Normal
• low (4) - Nice to have
• none (0) - No priority set

Requirements

No external dependencies - uses Python standard library only.

Security Notes

• API keys don't expire but can be revoked from Linear settings
• Token stored locally in ~/.claude/skills/linear-skill/config.json
• Revoke access: Settings > Account > Security & Access > Personal API keys

Sources

• Linear API Docs
• GraphQL Reference
• Filtering