linear-claude-skill

When to Use This Skill

Manage Linear issues, projects, and teams

Use this skill when working with manage linear issues, projects, and teams.

Linear

Tools and workflows for managing issues, projects, and teams in Linear.

---

⚠️ Tool Availability (READ FIRST)

This skill supports multiple tool backends. Use whichever is available:

MCP Tools (mcp__linear) - Use if available in your tool set

Linear CLI (linear command) - Always available via Bash

Helper Scripts - For complex operations

If MCP tools are NOT available, use the Linear CLI via Bash:

# View an issue
linear issues view ENG-123
Create an issue

linear issues create --title "Issue title" --description "Description"
Update issue status (get state IDs first)

linear issues update ENG-123 -s "STATE_ID"
Add a comment

linear issues comment add ENG-123 -m "Comment text"
List issues

linear issues list

Do NOT report "MCP tools not available" as a blocker - use CLI instead.

---

When to Use This Skill

Manage Linear issues, projects, and teams

Use this skill when working with manage linear issues, projects, and teams.

🔐 Security: Varlock Integration

CRITICAL: Never expose API keys in terminal output or Claude's context.

Safe Commands (Always Use)

# Validate LINEAR_API_KEY is set (masked output)
varlock load 2>&1 | grep LINEAR
Run commands with secrets injected

varlock run -- npx tsx scripts/query.ts "query { viewer { name } }"
Check schema (safe - no values)

cat .env.schema | grep LINEAR

Unsafe Commands (NEVER Use)

# ❌ NEVER - exposes key to Claude's context
linear config show
echo $LINEAR_API_KEY
printenv | grep LINEAR
cat .env

Setup for New Projects

Create .env.schema with @sensitive annotation:

# @type=string(startsWith=lin_api_) @required @sensitive
   LINEAR_API_KEY=

Add LINEAR_API_KEY to .env (never commit this file)

Configure MCP to use environment variable:

{
     "mcpServers": {
       "linear": {
         "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
       }
     }
   }

Use varlock load to validate before operations

---

Quick Start (First-Time Users)

1. Check Your Setup

Run the setup check to verify your configuration:

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

This will check:

LINEAR_API_KEY is set and valid

@linear/sdk is installed

Linear CLI availability (optional)

MCP configuration (optional)

2. Get API Key (If Needed)

If setup reports a missing API key:

Open Linear in your browser

Go to Settings (gear icon) -> Security & access -> Personal API keys

Click Create key and copy the key (starts with lin_api_)

Add to your environment:

# Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
export LINEAR_API_KEY="lin_api_your_key_here"
Option B: Add to Claude Code environment

echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env
Then reload your shell or restart Claude Code

3. Test Connection

Verify everything works:

npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"

You should see your name from Linear.

4. Common Operations

# Create issue in a project
npx tsx scripts/linear-ops.ts create-issue "Project" "Title" "Description"
Update issue status

npx tsx scripts/linear-ops.ts status Done ENG-123 ENG-124
Create sub-issue

npx tsx scripts/linear-ops.ts create-sub-issue ENG-100 "Sub-task" "Details"
Update project status

npx tsx scripts/linear-ops.ts project-status "Phase 1" completed
Show all commands

npx tsx scripts/linear-ops.ts help

See Project Management Commands for full reference.

---

When to Use This Skill

Manage Linear issues, projects, and teams

Use this skill when working with manage linear issues, projects, and teams.

Project Planning Workflow

Create Issues in the Correct Project from the Start

Best Practice: When planning a new phase or initiative, create the project and its issues together in a single planning session. Avoid creating issues in a catch-all project and moving them later.

Recommended Workflow

Create the project first:

npx tsx scripts/linear-ops.ts create-project "Phase X: Feature Name" "My Initiative"

Set project state to Planned:

npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" planned

Create issues directly in the project:

npx tsx scripts/linear-ops.ts create-issue "Phase X: Feature Name" "Parent task" "Description"
   npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Description"
   npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 2" "Description"

Update project state when work begins:

npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" in-progress

Why This Matters

Traceability: Issues are linked to their project from creation

Metrics: Project progress tracking is accurate from day one

Workflow: No time wasted moving issues between projects

Organization: Linear views and filters work correctly

Anti-Pattern to Avoid

❌ Creating issues in a "holding" project and moving them later:

# Don't do this
create-issue "Phase 6A" "New feature"  # Wrong project
Later: manually move to Phase X      # Extra work

---

Project Management Commands

project-status

Update a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.

npx tsx scripts/linear-ops.ts project-status <project-name> <state>

Valid States:

Examples:

# Start working on a project
npx tsx scripts/linear-ops.ts project-status "Phase 8: MCP Decision Engine" in-progress
Mark project complete

npx tsx scripts/linear-ops.ts project-status "Phase 8" completed
Partial name matching works

npx tsx scripts/linear-ops.ts project-status "Phase 8" paused

link-initiative

Link an existing project to an initiative.

npx tsx scripts/linear-ops.ts link-initiative <project-name> <initiative-name>

Examples:

# Link a project to an initiative
npx tsx scripts/linear-ops.ts link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"
Partial matching works

npx tsx scripts/linear-ops.ts link-initiative "Phase 8" "Q1 Goals"

unlink-initiative

Remove a project from an initiative.

npx tsx scripts/linear-ops.ts unlink-initiative <project-name> <initiative-name>

Examples:

# Remove incorrect link
npx tsx scripts/linear-ops.ts unlink-initiative "Phase 8" "Linear Skill"
Clean up test links

npx tsx scripts/linear-ops.ts unlink-initiative "Test Project" "Q1 Goals"

Error Handling:

Returns error if project is not linked to the specified initiative

Returns error if project or initiative not found

Complete Project Lifecycle Example

# 1. Create project linked to initiative
npx tsx scripts/linear-ops.ts create-project "Phase 11: New Feature" "Q1 Goals"
2. Set state to planned

npx tsx scripts/linear-ops.ts project-status "Phase 11" planned
3. Create issues in the project

npx tsx scripts/linear-ops.ts create-issue "Phase 11" "Parent task" "Description"
npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Details"
4. Start work - update to in-progress

npx tsx scripts/linear-ops.ts project-status "Phase 11" in-progress
5. Mark issues done

npx tsx scripts/linear-ops.ts status Done ENG-XXX ENG-YYY
6. Complete project

npx tsx scripts/linear-ops.ts project-status "Phase 11" completed
7. (Optional) Link to additional initiative

npx tsx scripts/linear-ops.ts link-initiative "Phase 11" "Q2 Goals"

---

When to Use This Skill

Manage Linear issues, projects, and teams

Use this skill when working with manage linear issues, projects, and teams.

Tool Selection

Choose the right tool for the task:

MCP Server Configuration

Use the official Linear MCP server at mcp.linear.app:

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

> WARNING: Do NOT use deprecated community servers. See troubleshooting.md for details.

MCP Reliability (Official Server)

Quick Status Update

# Via MCP - use human-readable state names
update_issue with id="issue-uuid", state="Done"
Via helper script (bulk operations)

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

Helper Script Reference

For detailed helper script usage, see troubleshooting.md.

Parallel Agent Execution

For bulk operations or background execution, use the Linear-specialist subagent:

Task({
  description: "Update Linear issues",
  prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
  subagent_type: "Linear-specialist"
})

When to use Linear-specialist (parallel):

Bulk status updates (3+ issues)

Project status changes

Creating multiple issues

Sync operations after code changes

When to use direct execution:

Single issue queries

Viewing issue details

Quick status checks

Operations needing immediate results

See sync.md for parallel execution patterns.

Critical Requirements

Issues → Projects → Initiatives

Every issue MUST be attached to a project. Every project MUST be linked to an initiative.

See projects.md for complete project creation checklist.

---

Conventions

Issue Status

Assigned to me: Set state: "Todo"

Unassigned: Set state: "Backlog"

Labels

Uses domain-based label taxonomy. See docs/labels.md.

Key rules:

ONE Type label: feature, bug, refactor, chore, spike

1-2 Domain labels: security, backend, frontend, etc.

Scope labels when applicable: blocked, breaking-change, tech-debt

# Validate labels
npx tsx scripts/linear-ops.ts labels validate "feature,security"
Suggest labels for issue

npx tsx scripts/linear-ops.ts labels suggest "Fix XSS vulnerability"

SDK Automation Scripts

Use only when MCP tools are insufficient. For complex operations involving loops, mapping, or bulk updates, write TypeScript scripts using @linear/sdk. See sdk.md for:

Complete script patterns and templates

Common automation examples (bulk updates, filtering, reporting)

Tool selection criteria

Scripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.

GraphQL API

Fallback only. Use when operations aren't supported by MCP or SDK.

See api.md for complete documentation including:

Authentication and setup

Example queries and mutations

Timeout handling patterns

MCP timeout workarounds

Shell script compatibility

Quick ad-hoc query:

npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"

Projects & Initiatives

For advanced project and initiative management patterns, see projects.md.

Quick reference - common project commands:

# Create project linked to initiative
npx tsx scripts/linear-ops.ts create-project "Phase X: Name" "My Initiative"
Update project status

npx tsx scripts/linear-ops.ts project-status "Phase X" in-progress
npx tsx scripts/linear-ops.ts project-status "Phase X" completed
Link/unlink projects to initiatives

npx tsx scripts/linear-ops.ts link-initiative "Phase X" "My Initiative"
npx tsx scripts/linear-ops.ts unlink-initiative "Phase X" "Old Initiative"

Key topics in projects.md:

Project creation checklist (mandatory steps)

Content vs Description fields

Discovery before creation

Codebase verification before work

Sub-issue management

Project status updates

Project updates (status reports)

---

When to Use This Skill

Manage Linear issues, projects, and teams

Use this skill when working with manage linear issues, projects, and teams.

Sync Patterns (Bulk Operations)

For bulk synchronization of code changes to Linear, see sync.md.

Quick sync commands:

# Bulk update issues to Done
npx tsx scripts/linear-ops.ts status Done ENG-101 ENG-102 ENG-103
Update project status

npx tsx scripts/linear-ops.ts project-status "My Project" completed

---

Reference

External: Linear MCP Documentation