mcpField
L
linear

linear

github.com/nodnarbnitram生产力1641 次安装27 周前更新
代码仓库

关于 linear

linear 是一项通过 Linear GraphQL API 管理项目、工单、里程碑和文档的技能。它提供脚本来执行常见操作，并规定仅使用 GraphQL 端点。

主要功能

  1. 01列出、搜索和读取工单
  2. 02创建及更新工单和项目
  3. 03管理里程碑及工单归属
  4. 04创建、列出和读取项目文档
  5. 05通过 GraphQL 端点操作

适用场景

  1. 01按团队或状态筛选工单
  2. 02将工单归入项目或里程碑
  3. 03整理项目里程碑和目标日期
  4. 04为项目创建或查看文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill linear

安装后在 Claude Code 中输入/linear确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
graphql-reference.md
scripts/
add-comment.py
add-issues-to-milestone.py
add-issues-to-project.py
create-document.py
create-milestone.py
create-project.py
create-ticket.py
linear_graphql.py
list-documents.py
list-issues.py
read-document.py
read-ticket.py
search-issues.py
update-ticket.py

详细介绍

Linear 项目与工单管理

此技能仅通过 GraphQL 端点管理 Linear。不要使用 linearis 或任何其他 CLI 封装工具。.claude/skills/linear/scripts/ 中的项目脚本共用一个 GraphQL 客户端，并直接访问 https://api.linear.app/graphql。

前置条件

必需：API 令牌
export LINEAR_API_TOKEN='lin_api_xxxxx'

从 Linear → Settings → Security & Access → Personal API keys 获取令牌。

验证设置
uv run .claude/skills/linear/scripts/read-ticket.py ICE-2041

如果返回工单 JSON，说明身份验证和 GraphQL 访问正常。

重要：优先使用脚本

优先使用 .claude/skills/linear/scripts/ 中的脚本，而不是临时编写 curl 调用。这些脚本会将名称解析为 ID、规范化错误，并保持输出为适合 Agent 工作流的 JSON 格式。如果需要原始查询来调试或执行不受支持的操作，请使用 references/graphql-reference.md。

何时使用此技能

  • 为功能开发、缺陷或修复工作创建或更新工单
  • 创建项目和里程碑以组织工作
  • 添加进度或审核备注
  • 创建、列出或读取项目文档
  • 将问题移入项目或里程碑

脚本概览

脚本用途
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 读取文档

工单操作

列出问题
uv run .claude/skills/linear/scripts/list-issues.py --team ICE-T
uv run .claude/skills/linear/scripts/list-issues.py --team ICE-T --limit 100
uv run .claude/skills/linear/scripts/list-issues.py --team ICE-T --status "Todo,In Progress"
uv run .claude/skills/linear/scripts/list-issues.py --team ICE-T --project "Orca Security Remediation"

选项：

  • --team 按团队键或名称筛选
  • --limit、-l 要获取的问题数量上限，默认为 50
  • --status、-s 以逗号分隔的工作流状态
  • --project 项目名称或 UUID
搜索问题
uv run .claude/skills/linear/scripts/search-issues.py "Orca Security"
uv run .claude/skills/linear/scripts/search-issues.py "CVE" --team ICE-T
uv run .claude/skills/linear/scripts/search-issues.py "Privileged Role" --status "Todo,Triage"
uv run .claude/skills/linear/scripts/search-issues.py "Docker" --team ICE-T --limit 20

选项：

  • query 必填的搜索文本
  • --team 按团队键或名称筛选
  • --status、-s 以逗号分隔的工作流状态
  • --project 项目名称或 UUID
  • --assignee、-a 受分配人用户 ID
  • --limit、-l 结果数量上限，默认为 25
创建工单
uv run .claude/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，而不只是标识符
读取工单
uv run .claude/skills/linear/scripts/read-ticket.py ICE-2021
uv run .claude/skills/linear/scripts/read-ticket.py 9e05263f-ed01-4b85-9c74-569fd1a0ce13
更新工单
uv run .claude/skills/linear/scripts/update-ticket.py ICE-2021 --status "In Progress"
uv run .claude/skills/linear/scripts/update-ticket.py ICE-2021 --status "Done" --priority 2
uv run .claude/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 新描述
添加评论
uv run .claude/skills/linear/scripts/add-comment.py ICE-2021 "Fixed in PR #123"

项目操作

创建项目
uv run .claude/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
将问题添加到项目
uv run .claude/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID ICE-2027
uv run .claude/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID ICE-2027 ICE-2028 ICE-2029
uv run .claude/skills/linear/scripts/add-issues-to-project.py PROJECT_UUID --issues ICE-2027,ICE-2028

里程碑操作

创建里程碑
uv run .claude/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
将问题添加到里程碑
uv run .claude/skills/linear/scripts/add-issues-to-milestone.py MILESTONE_UUID ICE-2027 ICE-2028

文档操作

创建文档
uv run .claude/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
列出文档
uv run .claude/skills/linear/scripts/list-documents.py --project PROJECT_UUID
uv run .claude/skills/linear/scripts/list-documents.py --project "Security Remediation" --limit 100
阅读文档
uv run .claude/skills/linear/scripts/read-document.py DOCUMENT_UUID

常见工作流

# 1. Create project
PROJECT_ID=$(uv run .claude/skills/linear/scripts/create-project.py \
  "Security Remediation" \
  --team ICE-T \
  --description "Eliminate all security vulnerabilities")

# 2. Create milestone
MILESTONE_ID=$(uv run .claude/skills/linear/scripts/create-milestone.py \
  "P1: Critical" \
  --project "$PROJECT_ID" \
  --target-date 2026-02-09)

# 3. Create ticket
TICKET_ID=$(uv run .claude/skills/linear/scripts/create-ticket.py \
  "Patch CVE-2024-1234" \
  --team ICE-T \
  --priority 1)

# 4. Link ticket into the plan
uv run .claude/skills/linear/scripts/add-issues-to-project.py "$PROJECT_ID" "$TICKET_ID"
uv run .claude/skills/linear/scripts/add-issues-to-milestone.py "$MILESTONE_ID" "$TICKET_ID"

# 5. Attach supporting documentation
uv run .claude/skills/linear/scripts/create-document.py \
  --title "Findings Report" \
  --project "$PROJECT_ID" \
  --content-file ./report.md

直接使用 GraphQL

如果所需操作尚无封装，请直接调用 GraphQL 端点，而不是引入 CLI 依赖。

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。

已知限制

  • 当前项目封装不处理截止日期；如果需要此处未提供的字段，请使用 UI
  • 标签必须已存在于工作区中
  • 项目 description 上限为 255 个字符；长篇项目文档请使用 content

错误处理

所有脚本在出错时均以代码 1 退出。

常见错误：

  • 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 (...)

版本

  • 技能版本：3.0
  • 传输方式：Linear GraphQL endpoint only

评论

支持 Markdown