Linear Skills Guide

You have specialized Linear issue management skills. Use these for structured ticket workflows during debugging investigations.

Decision Tree

Skills vs Agents

Simple issue fetch or update? → Use Linear skills

• •linear-issues - Fetch, list, search issues (single linearis command)
• •linear-update - Update issue, add comments
• •Example: "Get details for ENG-1234"
• •Use when: Single issue, straightforward query/update

Complex investigation requiring analysis? → Use Task tool with Linear agents (conserves context)

• •linear-locator - Find issues by criteria, save to /tmp
• •linear-analyzer - Extract debugging context, parse technical details
• •linear-pattern-finder - Find patterns across issues, detect recurring problems
• •Use when: Multi-issue analysis, pattern detection, trend analysis

When to Use Which Agent

Just need to find issues broadly? → Use linear-locator agent only

• •Lists/searches issues by team, label, state, text
• •Saves filtered results to /tmp
• •Example: "Find all FileB-related issues across teams"

Investigating single issue for debugging? → Use linear-locator + linear-analyzer agents

• •Locator: Find issue and related issues
• •Analyzer: Extract error messages, URLs, technical details
• •Example: "Analyze ENG-1234 for debugging context"

Need to find patterns or recurring problems? → Use all three: linear-locator + linear-analyzer + linear-pattern-finder

• •Locator: Fetch issues by criteria
• •Analyzer: Parse each issue for technical details
• •Pattern-finder: Correlate across issues, find recurring themes, temporal trends
• •Example: "Find recurring VCS permission errors across last 2 months"

Adding debugging findings to a ticket? → Use linear-update skill

• •Better than: Running raw linearis comments create commands
• •Example: "Add root cause analysis to ENG-1234"

Updating issue status after investigation? → Use linear-update skill

• •Includes: status, priority, labels updates
• •Example: "Mark ENG-1234 as In Progress"

Available Linear Tools

When to Use Raw linearis

Only use linearis CLI directly when:

• •Running one-off commands not covered by skills
• •User explicitly requests a specific linearis command
• •Creating new issues (linearis issues create)
• •Managing projects, teams, users (non-issue operations)
• •Debugging the skill itself

For systematic ticket workflows (read → debug → update), use the specialized skills above.

Common linearis Commands

Covered by skills:

• •linearis issues read → Use linear-issues
• •linearis issues list → Use linear-issues
• •linearis issues search → Use linear-issues
• •linearis comments create → Use linear-update
• •linearis issues update → Use linear-update

Not covered yet (use directly):

• •linearis issues create (issue creation)
• •linearis projects, linearis teams, linearis users (non-issue operations)

Authentication

Check linearis CLI is available and authenticated:

linearis --version
linearis issues list --limit 1

Note: Set LINEARIS_API_TOKEN environment variable or use --api-token flag.

Integration with Debugging Workflow

Linear skills integrate with platform debugging:

Workflow:

1. •linear-issues → Fetch ticket context
2. •Platform investigation → Use GCP and K8s skills for debugging
3. •linear-update → Add findings to ticket
4. •linear-update → Update status to "Done"

Example:

User: "Debug issue ENG-1234"
Claude: [Checks linear-awareness] → Uses linear-issues
        [Investigates using GCP/K8s skills]
        [Checks linear-awareness] → Uses linear-update