linear

name	linear
description	Linear — issue ops, status transitions, cycle management.

Detection

Activate this skill when any of the following are present:

• LINEAR_API_KEY environment variable is set
• User mentions a Linear issue key (e.g., ENG-123, INFRA-456)
• User says "create a Linear issue", "update the Linear ticket", or similar

---

Status Flow

Backlog → Todo → In Progress → In Review → Done
                                         → Cancelled (if abandoned)

• Move to In Progress when work begins on the branch
• Move to In Review when a PR is opened
• Move to Done only after the PR is merged and deployed (or as agreed with the team)
• Do not skip statuses — Linear's cycle metrics depend on accurate transitions

---

Operations

Before creating an issue — fetch team context first

# Get teams, projects, and cycles
query {
  teams {
    nodes {
      id
      name
      states { nodes { id name type } }
      labels { nodes { id name } }
      activeCycle { id number startsAt endsAt }
    }
  }
}

Use the returned state.id, label.id, and cycle.id when creating issues — never hardcode IDs.

Create issue

mutation CreateIssue($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { id identifier title url }
  }
}

Required fields: teamId, title Recommended fields: description, priority, labelIds, assigneeId, cycleId

Priority values: 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low

Update status

mutation UpdateIssue($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue { id identifier state { name } }
  }
}

Add comment

mutation AddComment($issueId: String!, $body: String!) {
  commentCreate(input: { issueId: $issueId, body: $body }) {
    success
    comment { id }
  }
}

---

Branch Naming

When creating a branch for a Linear issue, use:

feat/ENG-123-short-description
fix/ENG-456-bug-description
chore/ENG-789-task-description

• Use the Linear issue key as the prefix after the type
• Keep the description slug short (3–5 words, kebab-case)
• Linear auto-links branches that contain the issue identifier

---

Comment Format

When adding a progress comment to a Linear issue, use this structure:

**Done:** [what was implemented or changed]

**Decisions:** [key choices made and why — omit if none]

**Blockers:** [anything blocking next steps — omit if none]

**Next:** [remaining work or recommended next action]

---

Cycle Management

• Always assign issues to the active cycle when starting work, not when creating
• Use activeCycle.id from the team query — do not ask the user for the cycle ID
• If there is no active cycle, assign to the next upcoming cycle or leave unassigned and note it
• Do not create new cycles — that is a team lead responsibility

---

Checklist

• Team context fetched before creating any issue (to get valid IDs)
• Issue assigned to active cycle when work begins
• Branch name includes the issue identifier (ENG-123)
• Status updated to In Review when PR is opened
• Comment added to the issue summarizing what was done