linear

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linear Project & Ticket Management

Linear项目与工单管理

This skill manages Linear through the GraphQL endpoint only. Do not use

linearis

or any other CLI wrapper. The project scripts in

${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/

share a single GraphQL client and hit

https://api.linear.app/graphql

directly.

本技能仅通过GraphQL端点管理Linear。请勿使用

linearis

或任何其他CLI包装器。

${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/

中的项目脚本共享一个GraphQL客户端，直接访问

https://api.linear.app/graphql

。

Prerequisites

前提条件

Required: API Token

必填项：API令牌

bash

export LINEAR_API_TOKEN='lin_api_xxxxx'

Get the token from Linear → Settings → Security & Access → Personal API keys.

bash

export LINEAR_API_TOKEN='lin_api_xxxxx'

从Linear → 设置 → 安全与访问 → 个人API密钥获取令牌。

Verify Setup

验证设置

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-ticket.py ICE-2041

If this returns ticket JSON, auth and GraphQL access are working.

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-ticket.py ICE-2041

如果返回工单JSON，则认证和GraphQL访问正常。

IMPORTANT: Use Scripts First

重要提示：优先使用脚本

Prefer the scripts in

${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/

over ad hoc

curl

calls. They resolve names to IDs, normalize errors, and keep output JSON-shaped for agent workflows. If you need raw queries for debugging or unsupported operations, use

references/graphql-reference.md

优先使用

${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/

中的脚本，而非临时的

curl

调用。这些脚本会将名称解析为ID，标准化错误，并保持输出为JSON格式以适配Agent工作流。如果需要原始查询进行调试或处理不支持的操作，请使用

references/graphql-reference.md

。

When to Use This Skill

何时使用本技能

Create or update tickets for feature work, bugs, or remediation
Create projects and milestones to organize work
Add comments with progress or review notes
Create, list, or read project documents
Move issues into projects or milestones

创建或更新功能开发、Bug修复或问题修复的工单
创建项目和里程碑以组织工作
添加包含进度或评审说明的评论
创建、列出或读取项目文档
将问题移入项目或里程碑

Scripts Overview

脚本概览

Script	Purpose
`list-issues.py`	List issues with optional team, status, and project filters
`search-issues.py`	Full-text search issues
`create-ticket.py`	Create a ticket
`read-ticket.py`	Read ticket details by identifier or UUID
`update-ticket.py`	Update ticket fields
`add-comment.py`	Add a comment to a ticket
`create-project.py`	Create a project
`add-issues-to-project.py`	Add tickets to a project
`create-milestone.py`	Create a project milestone
`add-issues-to-milestone.py`	Add tickets to a milestone
`create-document.py`	Create a project document
`list-documents.py`	List documents, optionally by project
`read-document.py`	Read a document by UUID

脚本	用途
`list-issues.py`	列出工单，可按团队、状态和项目筛选
`search-issues.py`	全文搜索工单
`create-ticket.py`	创建工单
`read-ticket.py`	通过标识符或UUID读取工单详情
`update-ticket.py`	更新工单字段
`add-comment.py`	给工单添加评论
`create-project.py`	创建项目
`add-issues-to-project.py`	将工单添加到项目
`create-milestone.py`	创建项目里程碑
`add-issues-to-milestone.py`	将工单添加到里程碑
`create-document.py`	创建项目文档
`list-documents.py`	列出文档，可按项目筛选
`read-document.py`	通过UUID读取文档

Ticket Operations

工单操作

List Issues

列出工单

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T --limit 100
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T --status "Todo,In Progress"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T --project "Orca Security Remediation"

Options:

```
--team
```
filter by team key or name
```
--limit
```
,
```
-l
```
max issues to fetch, default
```
50
```
```
--status
```
,
```
-s
```
comma-separated workflow states
```
--project
```
project name or UUID

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T --limit 100
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T --status "Todo,In Progress"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-issues.py --team ICE-T --project "Orca Security Remediation"

选项：

```
--team
```
按团队密钥或名称筛选
```
--limit
```
,
```
-l
```
最大获取工单数量，默认
```
50
```
```
--status
```
,
```
-s
```
逗号分隔的工作流状态
```
--project
```
项目名称或UUID

Search Issues

搜索工单

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "Orca Security"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "CVE" --team ICE-T
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "Privileged Role" --status "Todo,Triage"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "Docker" --team ICE-T --limit 20

Options:

```
query
```
required search text
```
--team
```
filter by team key or name
```
--status
```
,
```
-s
```
comma-separated workflow states
```
--project
```
project name or UUID
```
--assignee
```
,
```
-a
```
assignee user ID
```
--limit
```
,
```
-l
```
max results, default
```
25
```

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "Orca Security"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "CVE" --team ICE-T
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "Privileged Role" --status "Todo,Triage"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/search-issues.py "Docker" --team ICE-T --limit 20

选项：

```
query
```
必填搜索文本
```
--team
```
按团队密钥或名称筛选
```
--status
```
,
```
-s
```
逗号分隔的工作流状态
```
--project
```
项目名称或UUID
```
--assignee
```
,
```
-a
```
经办人用户ID
```
--limit
```
,
```
-l
```
最大结果数量，默认
```
25
```

Create Ticket

创建工单

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-ticket.py "Fix CVE-2024-1234" \
  --team ICE-T \
  --description "Critical vulnerability in production" \
  --priority 1 \
  --labels "security" \
  --json

Options:

```
title
```
required ticket title
```
--team
```
required team key or name
```
--description
```
,
```
-d
```
description
```
--priority
```
,
```
-p
```
```
1=urgent
```
,
```
2=high
```
,
```
3=normal
```
,
```
4=low
```
```
--labels
```
comma-separated label names or UUIDs
```
--json
```
print structured JSON instead of just the identifier

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-ticket.py "Fix CVE-2024-1234" \
  --team ICE-T \
  --description "Critical vulnerability in production" \
  --priority 1 \
  --labels "security" \
  --json

选项：

```
title
```
必填工单标题
```
--team
```
必填团队密钥或名称
```
--description
```
,
```
-d
```
描述内容
```
--priority
```
,
```
-p
```
```
1=紧急
```
,
```
2=高
```
,
```
3=正常
```
,
```
4=低
```
```
--labels
```
逗号分隔的标签名称或UUID
```
--json
```
输出结构化JSON而非仅标识符

Read Ticket

读取工单

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-ticket.py ICE-2021
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-ticket.py 9e05263f-ed01-4b85-9c74-569fd1a0ce13

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-ticket.py ICE-2021
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-ticket.py 9e05263f-ed01-4b85-9c74-569fd1a0ce13

Update Ticket

更新工单

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/update-ticket.py ICE-2021 --status "In Progress"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/update-ticket.py ICE-2021 --status "Done" --priority 2
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/update-ticket.py ICE-2021 --labels "security,urgent"

Options, at least one required:

```
--status
```
new status name or UUID
```
--priority
```
```
1=urgent
```
,
```
2=high
```
,
```
3=normal
```
,
```
4=low
```
```
--assignee
```
assignee user ID
```
--labels
```
comma-separated label names or UUIDs; labels are added to the existing set
```
--project
```
project name or UUID
```
--project-milestone
```
milestone name or UUID
```
--title
```
new title
```
--description
```
new description

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/update-ticket.py ICE-2021 --status "In Progress"
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/update-ticket.py ICE-2021 --status "Done" --priority 2
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/update-ticket.py ICE-2021 --labels "security,urgent"

选项（至少选一项）：

```
--status
```
新状态名称或UUID
```
--priority
```
```
1=紧急
```
,
```
2=高
```
,
```
3=正常
```
,
```
4=低
```
```
--assignee
```
经办人用户ID
```
--labels
```
逗号分隔的标签名称或UUID；标签会添加到现有集合中
```
--project
```
项目名称或UUID
```
--project-milestone
```
里程碑名称或UUID
```
--title
```
新标题
```
--description
```
新描述

Add Comment

添加评论

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-comment.py ICE-2021 "Fixed in PR #123"

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-comment.py ICE-2021 "Fixed in PR #123"

Project Operations

项目操作

Create Project

创建项目

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-project.py "Security Remediation Q1" \
  --team ICE-T \
  --description "Eliminate all High severity alerts" \
  --priority 1 \
  --json

Options:

```
name
```
required project name
```
--team
```
required team key or name
```
--description
```
short summary, max 255 chars
```
--content
```
full markdown content for the project page

--priority

0=none

1=urgent

2=high

3=normal

4=low

```
--target-date
```
```
YYYY-MM-DD
```
```
--json
```
print full project JSON

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-project.py "Security Remediation Q1" \
  --team ICE-T \
  --description "Eliminate all High severity alerts" \
  --priority 1 \
  --json

选项：

```
name
```
必填项目名称
```
--team
```
必填团队密钥或名称
```
--description
```
简短摘要，最多255字符
```
--content
```
项目页面的完整Markdown内容

--priority

0=无

1=紧急

2=高

3=正常

4=低

```
--target-date
```
```
YYYY-MM-DD
```
格式
```
--json
```
输出完整项目JSON

Add Issues to Project

将工单添加到项目

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID ICE-2027
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID ICE-2027 ICE-2028 ICE-2029
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID --issues ICE-2027,ICE-2028

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID ICE-2027
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID ICE-2027 ICE-2028 ICE-2029
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID --issues ICE-2027,ICE-2028

Milestone Operations

里程碑操作

Create Milestone

创建里程碑

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-milestone.py "P1: Critical Fixes" \
  --project PROJECT_UUID \
  --description "RCE and exposed secrets" \
  --target-date 2026-02-09 \
  --json

Options:

```
name
```
required milestone name
```
--project
```
required project UUID
```
--description
```
milestone description
```
--target-date
```
due date in
```
YYYY-MM-DD
```
```
--json
```
print full milestone JSON

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-milestone.py "P1: Critical Fixes" \
  --project PROJECT_UUID \
  --description "RCE and exposed secrets" \
  --target-date 2026-02-09 \
  --json

选项：

```
name
```
必填里程碑名称
```
--project
```
必填项目UUID
```
--description
```
里程碑描述
```
--target-date
```
截止日期，格式为
```
YYYY-MM-DD
```
```
--json
```
输出完整里程碑JSON

Add Issues to Milestone

将工单添加到里程碑

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-milestone.py MILESTONE_UUID ICE-2027 ICE-2028

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-milestone.py MILESTONE_UUID ICE-2027 ICE-2028

Document Operations

文档操作

Create Document

创建文档

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-document.py \
  --title "Security Findings Report" \
  --project PROJECT_UUID \
  --content-file ./report.md \
  --json

Options:

```
--title
```
required document title
```
--project
```
required project name or UUID
```
--content
```
markdown content
```
--content-file
```
read content from file
```
--json
```
print structured JSON

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-document.py \
  --title "Security Findings Report" \
  --project PROJECT_UUID \
  --content-file ./report.md \
  --json

选项：

```
--title
```
必填文档标题
```
--project
```
必填项目名称或UUID
```
--content
```
Markdown内容
```
--content-file
```
从文件读取内容
```
--json
```
输出结构化JSON

List Documents

列出文档

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-documents.py --project PROJECT_UUID
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-documents.py --project "Security Remediation" --limit 100

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-documents.py --project PROJECT_UUID
uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/list-documents.py --project "Security Remediation" --limit 100

Read Document

读取文档

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-document.py DOCUMENT_UUID

bash

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/read-document.py DOCUMENT_UUID

Common Workflow

常见工作流

bash

undefined

bash

undefined

1. Create project

1. 创建项目

PROJECT_ID=$(uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-project.py
"Security Remediation"
--team ICE-T
--description "Eliminate all security vulnerabilities")

2. Create milestone

2. 创建里程碑

MILESTONE_ID=$(uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-milestone.py
"P1: Critical"
--project "$PROJECT_ID"
--target-date 2026-02-09)

3. Create ticket

3. 创建工单

TICKET_ID=$(uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-ticket.py
"Patch CVE-2024-1234"
--team ICE-T
--priority 1)

4. Link ticket into the plan

4. 将工单关联到计划

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-project.py "$PROJECT_ID" "$TICKET_ID" uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/add-issues-to-milestone.py "$MILESTONE_ID" "$TICKET_ID"

5. Attach supporting documentation

5. 附加支持文档

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-document.py
--title "Findings Report"
--project "$PROJECT_ID"
--content-file ./report.md

---

uv run ${CLAUDE_PLUGIN_ROOT}/skills/linear/scripts/create-document.py
--title "Findings Report"
--project "$PROJECT_ID"
--content-file ./report.md

---

Direct GraphQL Usage

直接使用GraphQL

If a needed operation does not have a wrapper yet, call the GraphQL endpoint directly rather than introducing a CLI dependency.

bash

curl -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_TOKEN" \
  -d '{"query":"{ viewer { id name } }"}'

Do not use a

Bearer

prefix. Linear expects the raw token.

For reusable queries and resolver examples, see

references/graphql-reference.md

如果所需操作尚未有包装器，请直接调用GraphQL端点，而非引入CLI依赖。

bash

curl -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_TOKEN" \
  -d '{"query":"{ viewer { id name } }"}'

请勿添加

Bearer

前缀。Linear期望使用原始令牌。

如需可复用查询和解析器示例，请查看

references/graphql-reference.md

。

Known Limitations

已知限制

Due dates are not handled by the current project wrappers; use the UI if you need fields not exposed here
Labels must already exist in the workspace
Project
```
description
```
is capped at 255 characters; use
```
content
```
for long-form project docs

当前项目包装器不处理截止日期；如果需要此处未暴露的字段，请使用UI
标签必须已存在于工作区中
项目
```
description
```
最多255字符；如需长格式项目文档，请使用
```
content
```
字段

Error Handling

错误处理

All scripts exit with code

on errors.

Common failures:

Error: LINEAR_API_TOKEN not set and ~/.linear_api_token not found

```
Error: Ticket ICE-9999 not found
```
```
Error: Team 'INVALID' not found
```

Error: Milestone 'Release 1' matched multiple projects (...)

所有脚本在出错时会以代码

退出。

常见失败情况：

Error: LINEAR_API_TOKEN not set and ~/.linear_api_token not found

```
Error: Ticket ICE-9999 not found
```
```
Error: Team 'INVALID' not found
```

Error: Milestone 'Release 1' matched multiple projects (...)

Version

版本

Skill version:
```
3.0
```
Transport:
```
Linear GraphQL endpoint only
```

技能版本：
```
3.0
```
传输方式：
```
仅Linear GraphQL端点
```