/linear

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

Environment

The connector and MCP paths need no CLI. Before a CLI-only operation (relations without the connector, bulk work), run `linear --version`, and stay on the connector when it fails. Check CLI subcommands and flags with `linear <cmd> --help` or the `linear-cli:linear-cli` skill.

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 code and traces, and put a repro command in a `sh` block even when it is one line. 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.

Keep the title under 10 words. 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.

Answering a Query

Answer a list query with one line per issue, each its linked identifier, title, and state, with no grouping headers, blank lines, or closing summary.

Saving a Structured Issue File

When another skill (issue refinement, project planning) hands off a Markdown file with YAML frontmatter, follow [references/structured-file.md](references/structured-file.md) to map it onto `save_issue` params.

Conventions

Apply [references/conventions.md](references/conventions.md) on every create, update, comment, or query: issue references and collapsible markers by write path, default state, CLI flags, and labels.