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

• esbuild Pre-compilation — 18x faster CLI startup (~50ms vs ~1s) with transparent tsx fallback via shared scripts/run.sh
• 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
• Bulk Sync — Synchronize code changes with Linear via CLI, agents, or hooks
• Image Uploads — Upload images to Linear's S3 storage and attach to issues
• Smoke Tests — Automated verification of build output and CLI behavior
• lin CLI Integration — Optional fast-path via aaronkwhite/linear-cli Rust binary with silent SDK fallback

Quick Start (New Users)

1. Install the Skill

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

2. Run Setup Check

npm run setup

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

3. Get Your API Key (If Needed)

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:

# Add to shell profile
echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc
source ~/.zshrc

4. Verify It Works

npm run ops -- whoami

You should see your name and organization.

5. Build for Faster Startup (Optional)

npm run build

Pre-compiles TypeScript to JavaScript for ~18x faster CLI cold starts. Without building, commands still work via tsx (slower but functional).

6. Start Using It

# Create an initiative
npm run ops -- create-initiative "My Project"

# Create a project
npm run ops -- create-project "Phase 1" "My Project"

# Create a sub-issue under a parent
npm run ops -- create-sub-issue ENG-100 "Add tests" "Unit tests for feature"

# Set parent-child relationships for existing issues
npm run ops -- set-parent ENG-100 ENG-101 ENG-102

# Update issue status
npm run ops -- status Done ENG-123 ENG-124

# See all commands
npm run ops -- help

---

Installation

# 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
• lin CLI (Optional) — Faster execution for status updates, search, and listings:

  brew install aaronkwhite/tap/lin    # macOS (Homebrew)
  cargo install lincli                # Any platform with Rust
  

  Set LINEAR_USE_LIN=0 to disable even when installed.
• Linear MCP Server (Recommended) — Use the official Linear MCP server for best reliability:

{
  "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/
│   ├── run.sh            # Shared runner (dist/ with tsx fallback)
│   ├── build.mjs         # esbuild pre-compilation script
│   ├── linear-ops.ts     # High-level operations (issues, projects, labels)
│   ├── query.ts          # GraphQL query runner
│   ├── setup.ts          # Configuration checker
│   ├── sync.ts           # Bulk sync CLI tool
│   ├── upload-image.ts   # Upload images to Linear S3
│   ├── extract-image.ts  # Extract images from session JSONL
│   ├── linear-api.mjs    # Direct API wrapper
│   ├── __tests__/        # Smoke tests (Node built-in test runner)
│   └── lib/              # Shared utilities (taxonomy, labels, verification)
├── dist/                 # Pre-compiled JS output (gitignored, in npm package)
└── hooks/
    └── post-edit.sh      # Auto-sync hook

Key Patterns

Discovery Before Creation (Critical!)

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

# 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.

Codebase Verification Before Work (Critical!)

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!

# Before starting "implement API" issues:
ls src/pages/api/admin/members/     # Check if files exist
grep -r "test.skip" tests/          # Check if tests