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:

1. MCP Tools (mcp__linear) - Use if available in your tool set
2. Linear CLI (linear command) - Always available via Bash
3. 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.

🔐 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

1. Create .env.schema with @sensitive annotation:

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

2. Add LINEAR_API_KEY to .env (never commit this file)

3. Configure MCP to use environment variable:

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

4. 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 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)

Key Location: LINEAR_API_KEY lives in your project root .env file. The MCP server reads it via environment injection—shell exports don't reach MCP subprocesses. Use varlock load to validate setup.

If setup reports a missing API key:

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

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

Add LINEAR_API_KEY to your project's .env file using your preferred secure editor. Never paste API keys directly in terminal commands or Claude's context. See the Security section above for details.

Common Team UUIDs

When creating or linking issues, projects, and initiatives, use these team UUIDs:

3. Test Connection

Verify everything works:

npx tsx 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.

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

1. Create the project first:

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

2. Set project state to Planned:

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

3. 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"
   

4. 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/lin