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:

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

```bash

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

LINEAR_API_KEY=

```

```json

{

"mcpServers": {

"linear": {

"env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }

}

}

}

```

---

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:

2. Get API Key (If Needed)

If setup reports a missing API key:

# 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](#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

```bash

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

```

```bash

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

```

```bash

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"

```

```bash

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

```

#### Why This Matters

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

| Input | Description | API Value |

|-------|-------------|-----------|

| backlog | Not yet started | backlog |

| planned | Scheduled for future | planned |

| in-progress | Currently active | started |

| paused | Temporarily on hold | paused |

| completed | Successfully finished | completed |

| canceled | Will not be done | canceled |

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:

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:

| Tool | When to Use |

|------|-------------|

| MCP (Official Server) | Most operations - PREFERRED |

| Helper Scripts | Bulk operations, when MCP unavailable |

| SDK scripts | Complex operations (loops, conditionals) |

| GraphQL API | Operations not supported by MCP/SDK |

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](troubleshooting.md) for details.

MCP Reliability (Official Server)

| Operation | Reliability | Notes |

|-----------|-------------|-------|

| Create issue | ✅ High | Full support |

| Update status | ✅ High | Use state: "Done" directly |

| List/Search issues | ✅ High | Supports filters, queries |

| Add comment | ✅ High | Works with issue IDs |

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](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):

When to use direct execution:

See [sync.md](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.

| Entity | Must Link To | If Missing |

|--------|--------------|------------|

| Issue | Project | Not visible in project board |

| Project | Initiative | Not visible in roadmap |

See [projects.md](projects.md) for complete project creation checklist.

---

Conventions

Issue Status

Labels

Uses domain-based label taxonomy. See [docs/labels.md](docs/labels.md).

Key rules:

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

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](api.md) for complete documentation including:

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](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:

---

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](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

| Document | Purpose |

|----------|---------|

| [api.md](api.md) | GraphQL API reference, timeout handling |

| [sdk.md](sdk.md) | SDK automation patterns |

| [sync.md](sync.md) | Bulk sync patterns |

| [projects.md](projects.md) | Project & initiative management |

| [troubleshooting.md](troubleshooting.md) | Common issues, MCP debugging |

| [docs/labels.md](docs/labels.md) | Label taxonomy |

External: [Linear MCP Documentation](https://linear.app/docs/mcp.md)