linear-claude-skill

---
name: linear-claude-skill
description: Use when driving Linear from Claude Code — MCP tools plus GraphQL automation, sub-issue hierarchies, subagent worktrees, and an esbuild-compiled CLI for 18x faster startup.
source: https://github.com/wrsmith108/linear-claude-skill
generated: 2026-05-17T04:18:28.217Z
category: platform
audience: engineers
---

## When to use

- Managing Linear issues, projects, and initiatives from Claude Code
- Creating sub-issues, parents, and initiative trees programmatically
- Bulk-syncing issue states across many tickets at once
- Posting Linear project status reports with health (onTrack/atRisk/offTrack)
- Attaching external resource links to projects or initiatives
- Spawning subagents to update issues in parallel without blocking the main thread
- Avoiding deprecated community Linear MCP servers

## Key concepts

### Official MCP server (mcp.linear.app)

The skill standardizes on Linear's official MCP server hosted at mcp.linear.app and explicitly warns against deprecated community servers: 'Always use Linear's official MCP server...Do NOT use deprecated community servers like linear-mcp-server (npm).' This avoids stale schemas and broken auth flows.

### GraphQL automation layer

On top of MCP, the skill exposes direct GraphQL access for operations MCP does not cover well: project status mutations using workspace-specific status UUIDs, external resource links attached to projects/initiatives, project milestones for Definition-of-Done tracking, and status report creation with health indicators.

### Subagent worktree workflow

Long-running sync jobs spawn subagents via Task tools so the primary agent stays responsive. Pattern: kick off 'Update ENG-432,433,434 to Done' as a subagent, keep coding in the main thread, and let the subagent reconcile state asynchronously.

### esbuild pre-compilation

Running npm run build pre-compiles the CLI with esbuild and yields '18x faster CLI startup (~50ms vs ~1s).' If the build artifact is missing, a shared runner script transparently falls back to tsx so functionality is preserved without manual intervention.

### description vs content fields

Linear projects carry two text fields the skill keeps distinct: description (max 255 chars, shown in list views) and content (unlimited, rendered in the main project panel). Conflating them is a common source of truncated or duplicated copy.

### Workspace-specific status UUIDs

Status IDs (e.g., 'Done', 'In Review') are not global — they vary per Linear workspace and must be queried per environment before mutations. The skill bakes this lookup into its ops commands so updates do not hardcode the wrong UUID.

## API reference

```
Installation
```

Clone the skill into ~/.claude/skills/linear, install dependencies, validate config, optionally build the fast CLI.

```
git clone <repo> ~/.claude/skills/linear
cd ~/.claude/skills/linear
npm install
npm run setup
npm run build   # optional, enables esbuild fast path
```

```
npm run ops -- create-initiative <name>
```

Create a Linear initiative from the CLI.

```
npm run ops -- create-initiative "My Project"
```

```
npm run ops -- create-sub-issue <parent> <title>
```

Create a sub-issue under an existing Linear issue.

```
npm run ops -- create-sub-issue ENG-100 "Add tests"
```

```
npm run ops -- set-parent <child> <parent>
```

Re-parent an existing issue under another issue.

```
npm run ops -- set-parent ENG-100 ENG-101
```

```
npm run ops -- status <state> <id...>
```

Move one or more issues to a named workflow state. State name is resolved to the workspace-specific UUID at call time.

```
npm run ops -- status Done ENG-123
```

```
npm run sync -- --issues <ids> --state <name>
```

Bulk-sync issue states. Designed to be invoked as a subagent so the main agent does not block.

```
npm run sync -- --issues ENG-432,ENG-433 --state Done
```

## Gotchas

- ALWAYS check Linear before creating projects or issues — the skill explicitly warns about duplicate creation when agents skip discovery
- Issue descriptions may be outdated or speculative — verify against the codebase before acting, since APIs or features may already be implemented
- description (255 chars, list view) and content (unlimited, main panel) are different fields; mixing them is a common bug
- Status UUIDs are workspace-specific — never hardcode them, always resolve by name per workspace
- Do not use deprecated community servers like linear-mcp-server (npm); the official MCP at mcp.linear.app is the only supported path
- Without npm run build, the CLI runs through tsx (~1s startup); run the build step before driving many operations in a row
- Image uploads go to Linear's S3 storage — large attachments and rate limits apply, batch them when bulk-syncing

---
Generated by SkillMake from https://github.com/wrsmith108/linear-claude-skill on 2026-05-17T04:18:28.217Z.
Verify against source before relying on details.

File: ~/.claude/skills/linear-claude-skill/SKILL.md