linear git:20261022.cfbb8d7A

Immutable. This exact content never changes and is served at /api/v1/blob/55fe95f3968990e3.

---
name: linear
description: Load before any Linear write or query, whether through the connector tools (save_issue, create_comment, list_issues) or the linear CLI. Direct calls get Linear-specific formatting wrong (issue references that chip, collapsible markers, relations as params). Use when filing, updating, commenting on, or listing Linear issues, projects, or backlogs.
argument-hint: "[create | update | list | view | comment] [issue ...]"
allowed-tools:
  - mcp__linear
  - mcp__claude_ai_Linear
  - WebFetch(domain:linear.app)
  - Bash
---

# Linear

Tools and workflows for managing issues, projects, and teams in Linear.

## Environment

The connector and MCP paths need no CLI. Before a CLI-only operation (relations without the connector, bulk work), run `linear --version`. When it fails, stay on the connector. Confirm the installed CLI's subcommands and flags with `linear <cmd> --help` or the `linear-cli:linear-cli` skill rather than assuming them.

## Arguments

`$0` is an optional verb (`create`, `update`, `list`, `view`, `comment`) and the rest are its params. With no verb, infer the operation from the request.

## Tool Selection

1. **Claude.ai connector** (`mcp__claude_ai_Linear__*`) is the primary path. `save_issue` creates or updates, and takes relations (`blocks`, `blockedBy`, `relatedTo`, `duplicateOf`), `parentId`, `project`, `milestone`, `cycle`, `estimate`, `dueDate`, and `links` as params.
2. **Local or plugin MCP** splits `save_issue` into `create_issue` and `update_issue` with the same flat fields. Use it when the connector is unavailable.
3. **`linear` CLI and GraphQL** covers bulk work, complex queries, and relations without the connector. Defer to the `linear-cli:linear-cli` skill for the CLI surface and [api.md](api.md) for raw GraphQL.

## Saving an Issue

`save_issue` creates when `id` is absent and updates when it is present. An update sends only the fields that change. Relation params are append-only, so a save never removes a relation you did not name. Pass `duplicateOf`, `parentId`, `project`, or `cycle` as `null` to clear one. `milestone` and `dueDate` have no `null` clear.

The `description` body is GFM and renders Linear's first-class constructs directly. Author them inline instead of using a workaround:

- Fence commands, code, and traces. Fold a pasted log or trace over about 15 lines into a [collapsible](references/conventions.md#collapsible-sections) titled for its source, and keep shorter ones inline.
- Draw a mermaid sequence diagram when the report describes several actors interleaving, such as a race or a handoff. A bug in one component doesn't need one.
- Turn criteria or tasks the request supplies into a check list (`- [ ]`).

Size the body to the request. A one-line report gets one or two sentences under 40 words, with no headings and no sections the request never supplied.

## Saving a Structured Issue File

Skills that emit a Markdown file with YAML frontmatter (issue refinement, project planning) hand off here. [references/structured-file.md](references/structured-file.md) maps that frontmatter onto connector `save_issue` params, relations included, covers routing fields taken from the user at save time, and keeps the `linear` CLI as the fallback when the connector is unavailable.

## Conventions

Apply [references/conventions.md](references/conventions.md) whenever you create, update, comment, or query: issue references by write path, collapsible markers, default state, queries, and labels.