Linear

SKILL.md

---
name: Linear
description: "Access Linear project management with managed OAuth. Create, search, update, and manage issues, projects, and cycles. Use when the user wants to create a Linear issue, search tasks, update issue status, list projects, manage sprints/cycles, or query Linear data."
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: LINEAR_ACCESS_TOKEN
        type: oauth2
        integration_id: linear
        description: Linear OAuth access
        scopes:
          - read
          - write
          - issues:create
          - comments:create
    primaryEnv: LINEAR_ACCESS_TOKEN
---

# Linear Connector

Access Linear project management through the Linear GraphQL API using managed OAuth.

## First-Time Setup

If Linear is not connected yet, run:

`manage_auth(action="connect", integration_id="linear", auth_env="LINEAR_ACCESS_TOKEN")`

## Auth & Security

- Authentication is managed by Polly + Nango from `metadata.polly.auth`
- Never ask users to paste tokens in chat
- Never print or log token values
- If auth fails, reconnect with:
  `manage_auth(action="connect", integration_id="linear", auth_env="LINEAR_ACCESS_TOKEN")`

## API Endpoint

`https://api.linear.app/graphql`

All requests are POST with:

`Authorization: $LINEAR_ACCESS_TOKEN`

## Quick Usage

List issues:

```bash
curl -sS -X POST \
  -H "Authorization: $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ issues(first: 10) { nodes { id title state { name } assignee { name } priority createdAt } } }"}' \
  "https://api.linear.app/graphql"
```

Get an issue by ID:

```bash
curl -sS -X POST \
  -H "Authorization: $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ issue(id: \"<issueId>\") { id title description state { name } assignee { name } priority labels { nodes { name } } } }"}' \
  "https://api.linear.app/graphql"
```

Create an issue:

```bash
curl -sS -X POST \
  -H "Authorization: $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { issueCreate(input: { title: \"New issue\", teamId: \"<teamId>\" }) { success issue { id title identifier url } } }"}' \
  "https://api.linear.app/graphql"
```

Update an issue:

```bash
curl -sS -X POST \
  -H "Authorization: $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { issueUpdate(id: \"<issueId>\", input: { stateId: \"<stateId>\" }) { success issue { id title state { name } } } }"}' \
  "https://api.linear.app/graphql"
```

Search issues (filter by title keyword):

```bash
curl -sS -X POST \
  -H "Authorization: $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ issues(filter: { title: { containsIgnoreCase: \"search term\" } }, first: 10) { nodes { id title state { name } assignee { name } } } }"}' \
  "https://api.linear.app/graphql"
```

> **Note:** `issueSearch` is deprecated. Use `issues(filter: { ... })` instead.
> Supported filter fields include `title`, `state`, `assignee`, `priority`, `label`, `team`, and more.
> See [Linear filtering docs](https://developers.linear.app/docs/graphql/working-with-the-graphql-api#filtering) for details.

List projects:

```bash
curl -sS -X POST \
  -H "Authorization: $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ projects(first: 20) { nodes { id name state startDate targetDate } } }"}' \
  "https://api.linear.app/graphql"
```

## Rules

- All Linear API calls use POST to the single GraphQL endpoint
- Use `first` / `after` parameters for pagination in queries
- To get team IDs, query `{ teams { nodes { id name } } }`
- To get workflow state IDs, query `{ workflowStates { nodes { id name type } } }`
- Do NOT use `issueSearch` — it is deprecated. Use `issues(filter: {...})` instead.
- On API errors, surface status + response body clearly
- On 401/403, reconnect with `manage_auth(action="connect", integration_id="linear", auth_env="LINEAR_ACCESS_TOKEN")`
- Never log, echo, or expose credential values in any output