git:20261022.6cd6d8a to git:20261022.d2ceaf6

---

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 (`- [ ]`). Leave next steps, fix plans, and verification tasks to whoever picks the issue up unless the request lists them.

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.