Linear

Linear Skill

You can read, search, and update Linear issues, list workflow states, and post comments. Use this skill as the entry point for ticket-driven workflows — turn ENG-123 into a structured payload, transition state, comment on progress.

When to use this skill

• The user references a Linear issue by identifier (ENG-123, OPS-7, etc.).
• The user asks for "my tickets" / "open issues" / "what's assigned to me".
• An automation needs to mark work started, post a PR link as a comment, or move a ticket through workflow states.

Issue identifier format

Linear identifiers look like <TEAM_KEY>-<NUMBER> — ENG-123, OPS-7. They are not GraphQL UUIDs. The Linear API accepts both forms on issue(id:), so always pass the human identifier the user gave you. Never invent or normalise identifiers — use them verbatim.

State transition pattern (hard rule)

You MUST call linear_get_workflow_states first and use the resolved id when calling linear_update_issue_state. State IDs are per-team UUIDs; state names like "Todo" or "In Progress" are not portable across teams and cannot be passed to linear_update_issue_state directly.

Workflow:

1. linear_get_issue to find the issue's team.id.
2. linear_get_workflow_states with that team_id to enumerate the team's states.
3. Pick the state by matching its name (case-insensitive) or type (unstarted, started, completed, canceled, triage, backlog).
4. linear_update_issue_state with the issue identifier and the resolved state_id.

Commenting etiquette

Post a comment when:

• Work has been picked up (one comment, e.g. "Working on this.").
• A pull request has been opened (one comment with the PR URL).
• Work is blocked and the user should know.
• Work is complete (one comment summarising what shipped).

Do not chatter. Post no more than one comment per agent action. Do not narrate intermediate tool calls, file edits, or reasoning into Linear comments — the channel-side conversation is the place for that. Comments are durable artifacts on the ticket; treat them like git commit messages, not Slack messages.

Safety rules

• Never include secrets, tokens, or environment variable values in comment bodies.
• Never transition an issue to a "Done" or "Completed" state without explicit user confirmation.
• Never delete issues, comments, or projects through this skill — the tools don't support it. If the user asks, tell them this skill is read/comment/transition only.
• When the user asks for "my tickets", default to state filter "Todo" or "In Progress" (state types unstarted, started) unless they specify otherwise.

Tool: linear_get_issue

Fetch a Linear issue by its human identifier.

Input:

Output:

{
  "identifier": "ENG-123",
  "title": "...",
  "description": "...",
  "state": { "id": "...", "name": "In Progress", "type": "started" },
  "assignee": { "email": "...", "name": "..." },
  "team": { "id": "...", "key": "ENG", "name": "Engineering" },
  "labels": ["bug", "p1"],
  "priority": 2,
  "url": "https://linear.app/..."
}

Tool: linear_search_issues

Filter issues across one team — or across all teams the API key can see, if no team is supplied. All parameters are optional. Call this tool with {} when the user asks something broad like "list open issues" or "what's in the backlog" — do not ask for a team_id first; the result will include the team key in each issue's identifier (e.g. ENG-12 vs OPS-7) and the user can drill down from there.

Input:

Examples — call the tool directly, do not ask the user for an ID:

Output:

{
  "count": 3,
  "issues": [
    { "identifier": "ENG-1", "title": "...", "state": "Todo", "assignee_email": "...", "url": "..." }
  ]
}

Tool: linear_list_my_issues

List issues assigned to the API key's owner (viewer).

Input:

Output: same shape as linear_search_issues.

Tool: linear_get_workflow_states

Enumerate a team's workflow states. Required before linear_update_issue_state.

Input:

Output:

{
  "team_id": "...",
  "states": [
    { "id": "...", "name": "Todo",        "type": "unstarted", "position": 0 },
    { "id": "...", "name": "In Progress", "type": "started",   "position": 1 },
    { "id": "...", "name": "Done",        "type": "completed", "position": 2 }
  ]
}

States are sorted by position.

Tool: linear_update_issue_state

Transition an issue to a different workflow state. The state_id must come from linear_get_workflow_states — do not invent or guess it.

Input:

Output:

{
  "success": true,
  "identifier": "ENG-123",
  "state": { "id": "...", "name": "In Progress", "type": "started" }
}

Tool: linear_add_comment

Post a markdown comment to an issue.

Input:

Output:

{
  "success": true,
  "comment": { "id": "...", "url": "https://linear.app/...", "created_at": "2026-05-20T..." }
}