Linear Workflow Management

Manage Linear issues and projects through the bundled CLI at {baseDir}/scripts/linear-cli.js.

Scope and Runtime Model

• This skill runs node {baseDir}/scripts/linear-cli.js ....
• The CLI uses the official @linear/sdk.
• Authentication is LINEAR_API_KEY from the local environment.
• Expected API destination is Linear GraphQL (https://api.linear.app/graphql) through the official SDK.

Prerequisites

1. Node.js and npm are installed.
2. Install script dependencies once:
• cd {baseDir}/scripts && npm install
3. Set your API key:
• export LINEAR_API_KEY="lin_api_..."

If dependencies or LINEAR_API_KEY are missing, stop and complete setup before issue/project operations.

Authentication and Credentials

• Required credential: LINEAR_API_KEY.
• Get it from https://linear.app/settings/api.
• Use least-privilege access and a dedicated token for automation.

Required Workflow

1. Clarify intent and scope:
• Team/project, labels, cycle, assignee, due date, priority.
2. Read current state first:
• List/get issues, projects, statuses, labels, users, cycles.
3. Apply mutations second:
• Create/update issues, comments, projects, milestones, labels.
4. Summarize exactly what changed:
• Mention IDs, states, assignees, blockers, and follow-up actions.

Command Coverage

• Teams and projects:

teams, projects, createProject

• Issues:

issues, issue, createIssue, updateIssue

• Comments:

createComment

• States and labels:

states, labels

• User:

user

Quick Examples

node {baseDir}/scripts/linear-cli.js teams
node {baseDir}/scripts/linear-cli.js projects
node {baseDir}/scripts/linear-cli.js issues
node {baseDir}/scripts/linear-cli.js issue ENG-123
node {baseDir}/scripts/linear-cli.js createIssue "Title" "Description" "team-id" '{"priority":2}'
node {baseDir}/scripts/linear-cli.js updateIssue "issue-id" '{"stateId":"state-id"}'

Practical Workflows

• Triage urgent bugs:

list high-priority open issues, assign owners, move state to In Progress, add triage comments.

• Sprint planning:

review cycle scope, create missing issues, set priorities and estimates, align assignees.

• Release prep:

verify blockers, update project status, create milestone tasks, add rollout comments.

• Documentation cleanup:

find stale docs/issues, open follow-up tasks, link related records.

Safety and Operational Rules

• Never invent IDs; fetch and confirm before updates.
• Prefer narrow updates over broad bulk edits.
• For bulk edits, explain grouping logic before applying changes.
• Do not include secrets in issue comments or descriptions.
• Do not send data to endpoints outside Linear API scope for this skill.

References

• references/API.md for priority values and workflow patterns.