linear-core-workflow-a

Issue lifecycle management with Linear: create, update, and transition issues.Use when implementing issue CRUD operations, state transitions,or building issue management features.Trigger with phrases like "linear issue workflow", "linear issue lifecycle","create linear issues", "update linear issue", "linear state transition".

⭐939stars🔀114forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill automates the Linear issue lifecycle, enabling developers and teams to programmatically create, update, and transition issues. It simplifies complex project management tasks such as managing sub-issues, establishing blocking relationships, and synchronizing comments, ensuring a streamlined and consistent workflow within the Linear ecosystem. By leveraging the Linear SDK, it provides a robust framework for building custom issue management features and automating repetitive project tracking tasks.

Use Cases

  • Automated Issue Generation: Automatically create and categorize Linear issues from external triggers such as bug reports, customer feedback, or system alerts.
  • Dynamic Workflow Transitions: Programmatically move issues through custom workflow states (e.g., moving a task to 'Done' upon a successful PR merge) to maintain real-time project status.
  • Dependency & Hierarchy Mapping: Organize complex development tasks by automatically generating sub-issues and establishing 'blocking' relationships to visualize project bottlenecks.
  • Centralized Communication Sync: Update issue descriptions and append comments automatically to sync technical discussions from external tools directly into the Linear record.
namelinear-core-workflow-a
description|
Issue lifecycle management with Linearcreate, update, and transition issues.
allowed-toolsRead, Write, Edit, Grep
version1.0.0
licenseMIT
authorJeremy Longshore <jeremy@intentsolutions.io>

Linear Core Workflow A: Issue Lifecycle

Overview

Master issue lifecycle management: creating, updating, transitioning, and organizing issues.

Prerequisites

  • Linear SDK configured
  • Access to target team(s)
  • Understanding of Linear's issue model

Instructions

Step 1: Create Issues

import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

async function createIssue(options: {
  teamKey: string;
  title: string;
  description?: string;
  priority?: 0 | 1 | 2 | 3 | 4; // 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low
  estimate?: number;
  labelIds?: string[];
  assigneeId?: string;
}) {
  const teams = await client.teams({ filter: { key: { eq: options.teamKey } } });
  const team = teams.nodes[0];

  if (!team) throw new Error(`Team ${options.teamKey} not found`);

  const result = await client.createIssue({
    teamId: team.id,
    title: options.title,
    description: options.description,
    priority: options.priority ?? 0,
    estimate: options.estimate,
    labelIds: options.labelIds,
    assigneeId: options.assigneeId,
  });

  if (!result.success) {
    throw new Error("Failed to create issue");
  }

  return result.issue;
}

Step 2: Update Issues

async function updateIssue(
  issueId: string,
  updates: {
    title?: string;
    description?: string;
    priority?: number;
    stateId?: string;
    assigneeId?: string;
    estimate?: number;
  }
) {
  const result = await client.updateIssue(issueId, updates);

  if (!result.success) {
    throw new Error("Failed to update issue");
  }

  return result.issue;
}

// Update by identifier (e.g., "ENG-123")
async function updateByIdentifier(identifier: string, updates: Record<string, unknown>) {
  const issue = await client.issue(identifier);
  return client.updateIssue(issue.id, updates);
}

Step 3: State Transitions

async function getWorkflowStates(teamKey: string) {
  const teams = await client.teams({ filter: { key: { eq: teamKey } } });
  const team = teams.nodes[0];

  const states = await team.states();
  return states.nodes.sort((a, b) => a.position - b.position);
}

async function transitionIssue(issueId: string, stateName: string) {
  const issue = await client.issue(issueId);
  const team = await issue.team;
  const states = await team?.states();

  const targetState = states?.nodes.find(
    s => s.name.toLowerCase() === stateName.toLowerCase()
  );

  if (!targetState) {
    throw new Error(`State "${stateName}" not found`);
  }

  return client.updateIssue(issueId, { stateId: targetState.id });
}

// Common transitions
async function markInProgress(issueId: string) {
  return transitionIssue(issueId, "In Progress");
}

async function markDone(issueId: string) {
  return transitionIssue(issueId, "Done");
}

Step 4: Issue Relationships

// Create sub-issue
async function createSubIssue(parentId: string, title: string) {
  const parent = await client.issue(parentId);
  const team = await parent.team;

  return client.createIssue({
    teamId: team!.id,
    title,
    parentId,
  });
}

// Link issues (blocking relationship)
async function addBlockingRelation(blockingId: string, blockedById: string) {
  return client.createIssueRelation({
    issueId: blockingId,
    relatedIssueId: blockedById,
    type: "blocks",
  });
}

// Get sub-issues
async function getSubIssues(parentId: string) {
  const parent = await client.issue(parentId);
  const children = await parent.children();
  return children.nodes;
}

Step 5: Comments and Activity

async function addComment(issueId: string, body: string) {
  return client.createComment({
    issueId,
    body,
  });
}

async function getComments(issueId: string) {
  const issue = await client.issue(issueId);
  const comments = await issue.comments();
  return comments.nodes;
}

Output

  • Issue creation with all metadata
  • Bulk update capabilities
  • State transition handling
  • Parent/child relationships
  • Blocking relationships
  • Comments and activity

Error Handling

Error Cause Solution
Issue not found Invalid ID or identifier Verify issue exists
State not found Team workflow mismatch List states for correct team
Validation error Invalid field value Check field constraints
Circular dependency Self-blocking issue Validate relationships

Examples

Complete Issue Creation Flow

async function createFeatureIssue(options: {
  teamKey: string;
  title: string;
  description: string;
  priority: 1 | 2 | 3 | 4;
}) {
  // Get team and default state
  const teams = await client.teams({ filter: { key: { eq: options.teamKey } } });
  const team = teams.nodes[0];

  // Get "Backlog" state
  const states = await team.states();
  const backlog = states.nodes.find(s => s.name === "Backlog");

  // Create issue
  const result = await client.createIssue({
    teamId: team.id,
    title: options.title,
    description: options.description,
    priority: options.priority,
    stateId: backlog?.id,
  });

  const issue = await result.issue;

  // Add initial comment
  await client.createComment({
    issueId: issue!.id,
    body: "Issue created via API integration",
  });

  return issue;
}

Resources

Next Steps

Continue to linear-core-workflow-b for project and cycle management.