linear

Linear — issue ops, status transitions, cycle management.

SKILL.md

GitHub

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