home / skills / idanbeck / claude-skills / linear-skill

linear-skill skill

safe

/linear-skill

This skill helps you manage Linear issues, cycles, and projects to streamline standups and sprint planning.

npx playbooks add skill idanbeck/claude-skills --skill linear-skill

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

6.1 KB

---
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](https://linear.app/settings/api)
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:
```bash
echo '{"api_key": "lin_api_YOUR_KEY_HERE"}' > ~/.claude/skills/linear-skill/config.json
```

## Commands

### My Issues (Assigned to Me)

```bash
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

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

### Team Issues

```bash
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

```bash
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)

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

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

### List Cycles

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

### Search Issues

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

### Create Issue

```bash
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

```bash
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

```bash
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:**
```bash
# 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

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

## Workflow Examples

### Morning Standup Prep
```bash
# 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
```bash
python3 ~/.claude/skills/linear-skill/linear_skill.py issues EPO --status todo --priority high
```

### Find Specific Work
```bash
python3 ~/.claude/skills/linear-skill/linear_skill.py search "authentication bug"
```

### Quick Issue Creation
```bash
python3 ~/.claude/skills/linear-skill/linear_skill.py create EPO --title "Fix login timeout" --priority high
```

### Board Grooming (Reorder Lanes)
```bash
# 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
```bash
python3 ~/.claude/skills/linear-skill/linear_skill.py create EPO --title "New feature" --project "Zerg AI Platform"
```

### Move Issue to Project
```bash
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](https://linear.app/developers)
- [GraphQL Reference](https://linear.app/developers/graphql)
- [Filtering](https://linear.app/developers/filtering)

Overview

This skill lets you read, search, and manage Linear issues, projects, teams, and cycles from the command line. It streamlines daily standup prep, sprint checks, ticket creation, and board grooming. Setup is quick: create a Linear personal API key and save it to the local config file. Commands return JSON for easy automation and integration.

How this skill works

The skill calls the Linear API using a personal API key stored in a local config file to list teams, fetch issues, view cycle progress, search, create, update, and reorder issues. All outputs are JSON objects including identifier, title, status, priority, assignee, cycle, labels, and estimates. Operations support filters (status, priority, limit) and accept team keys or names and issue identifiers. No external Python packages are required; the tool uses the standard library.

When to use it

Prepare for daily standups by listing issues assigned to you or your team.
Check current sprint (cycle) progress and capacity for planning or retrospectives.
Search for specific bugs, features, or tasks across projects and teams.
Create or update issues quickly from scripts or terminal during triage.
Reorder backlog or in-progress lanes when grooming boards.

Best practices

Store the personal API key in the local config file and grant minimum permissions (Read or Read+Write as needed).
Use team keys (e.g., ENG, EPO) for consistent filtering and faster lookups.
Filter by status and priority to reduce noise when preparing standups or planning.
Use the JSON output to integrate with CI scripts, automation, or dashboards.
Revoke or rotate the API key from Linear settings if the key is exposed or when access is no longer needed.

Example use cases

Morning standup: python3 linear_skill.py my-issues --status in_progress to list current work.
Sprint check: python3 linear_skill.py cycle EPO to view active sprint progress and velocity indicators.
Find work: python3 linear_skill.py search "authentication bug" to locate relevant tickets and context.
Create a quick ticket: python3 linear_skill.py create EPO --title "Fix login timeout" --priority high.
Board grooming: python3 linear_skill.py reorder EPO-485 EPO-480 EPO-397 to set priority order in a lane.

FAQ

How do I set up the API key?

Create a personal API key in Linear settings (Account > Security & Access > Personal API keys), then save it in ~/.claude/skills/linear-skill/config.json as {"api_key":"lin_api_YOUR_KEY"}.

What permissions does the key need?

Read permission is sufficient for viewing teams, issues, and cycles. Grant Read+Write to create, update, or reorder issues.