Linear Skill for Claude Code

A comprehensive Claude Code skill for managing Linear issues, projects, and teams. Provides patterns for MCP tools, SDK automation, and GraphQL API access.

Features

- Label Taxonomy System — Domain-based labels for consistent categorization and agent routing
- First-Time Setup Check — Automatic configuration validation with actionable guidance
- High-Level Operations — Simple commands for initiatives, projects, and status updates
- Sub-Issue Management — Create and manage parent-child issue relationships
- Discovery Before Creation — Mandatory checks to prevent duplicate projects/issues
- MCP Tool Integration — Simple operations via Linear MCP server
- SDK Automation — Complex operations with TypeScript scripts
- GraphQL API — Direct API access for advanced queries
- Project Management — Content, descriptions, milestones, resource links
- Status Management — Project status UUIDs for workflow automation
- MCP Reliability Workarounds — Fallback patterns for timeout/failure scenarios
- Bulk Sync — Synchronize code changes with Linear via CLI, agents, or hooks

Quick Start (New Users)

$3

``bash


Option A: Claude Plugin (Recommended)

claude plugin install github:wrsmith108/linear-claude-skill

Option B: Manual Installation

git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
cd ~/.claude/skills/linear && npm install
`

$3

`bash
npx tsx ~/.claude/skills/linear/scripts/setup.ts
`

This checks your configuration and tells you exactly what's missing.

$3

1. Open Linear in your browser
2. Go to Settings → Security & access → Personal API keys
3. Click Create key and copy it (starts with lin_api_)
4. Add to your environment:

`bash


Add to shell profile


echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc
source ~/.zshrc
`

$3

`bash
npx tsx ~/.claude/skills/linear/scripts/linear-ops.ts whoami
`

You should see your name and organization.

$3

`bash


Create an initiative

npx tsx scripts/linear-ops.ts create-initiative "My Project"

Create a project

npx tsx scripts/linear-ops.ts create-project "Phase 1" "My Project"

Create a sub-issue under a parent

npx tsx scripts/linear-ops.ts create-sub-issue ENG-100 "Add tests" "Unit tests for feature"

Set parent-child relationships for existing issues

npx tsx scripts/linear-ops.ts set-parent ENG-100 ENG-101 ENG-102

Update issue status

node scripts/linear-helpers.mjs update-status Done 123 124

See all commands

npx tsx scripts/linear-ops.ts help
`

---

Installation

$3

`bash
claude plugin add github:wrsmith108/linear-claude-skill
`

$3

`bash


Clone directly to your skills directory


git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
cd ~/.claude/skills/linear && npm install
`

Prerequisites

- Linear API Key — Generate at Linear → Settings → Security & access → Personal API keys
- Linear MCP Server (Recommended) — Use the official Linear MCP server for best reliability:

`json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.linear.app/sse"],
"env": {
"LINEAR_API_KEY": "your_api_key"
}
}
}
}
`

> Important: Always use Linear's official MCP server at mcp.linear.app. Do NOT use deprecated community servers like linear-mcp-server (npm) or jerhadf/linear-mcp-server (GitHub).

Directory Structure

`
linear-claude-skill/
├── SKILL.md # Main skill instructions (Claude Code discovers this)
├── api.md # GraphQL API reference
├── sdk.md # SDK automation patterns
├── sync.md # Bulk sync patterns
├── docs/
│ └── labels.md # Label taxonomy documentation
├── scripts/
│ ├── linear-ops.ts # High-level operations (issues, projects, labels)
│ ├── query.ts # GraphQL query runner
│ ├── setup.ts # Configuration checker
│ ├── sync.ts # Bulk sync CLI tool
│ ├── linear-api.mjs # Direct API wrapper
│ └── lib/ # Shared utilities (taxonomy, labels, verification)
└── hooks/
└── post-edit.sh # Auto-sync hook
`

Key Patterns

$3

ALWAYS check Linear before creating projects or issues. This prevents duplicates:

`bash


Check for existing projects

linear projects list | grep -i "phase\|feature-name"

Check for existing issues

linear issues list --filter "title:keyword"
`

See SKILL.md → "Discovery Before Creation" for the full checklist.

$3

ALWAYS verify codebase state before accepting issue scope at face value.

Issue descriptions may be outdated or speculative. APIs or features may already be implemented!

`bash


Before starting "implement API" issues:


ls src/pages/api/admin/members/ # Check if files exist
grep -r "test.skip" tests/ # Check if tests are just skipped
`

Key Lesson: Issues describing "missing" features may already be implemented. The real work is often un-skipping tests and fixing assertions, not reimplementing.

See SKILL.md → "Codebase Verification Before Work" for the full checklist.

$3

The Linear MCP server has known reliability issues (34% timeout rate due to SSE idle timeouts):

| Operation | MCP Reliability | Recommendation |
|-----------|----------------|----------------|
| Create issue | ✅ Reliable | Use MCP |
| Search issues | ⚠️ Times out | Use GraphQL |
| Update status | ⚠️ Unreliable | Use GraphQL |
| Add comment | ❌ Broken | Use GraphQL |

See SKILL.md for GraphQL workaround patterns and root cause explanation.

$3

Linear has TWO text fields — using the wrong one causes blank displays:

| Field | Limit | Shows In |
|-------|-------|----------|
| description | 255 chars | List views, tooltips |
| content | Unlimited | Main detail panel |

Always set BOTH when creating projects.

$3

Status UUIDs are workspace-specific. Query your workspace:

`graphql
query { projectStatuses { nodes { id name } } }
`

Common statuses: Backlog, Planned, In Progress, Completed, Canceled

$3

Organize issues into parent-child hierarchies for better tracking:

`bash


Create a sub-issue under a parent issue

Inherits team and project from parent automatically

npx tsx scripts/linear-ops.ts create-sub-issue