前言¶

很多团队已经把 Linear 当作日常项目管理的主战场：Bug 在这里流转，Sprint 在这里排期，Release 里程碑也在这里对齐。但当你把同样的问题交给 AI 编程助手——「帮我把这个 Bug 标成 In Progress 并加一条进展评论」——它往往只能写好代码片段，却无法真正动你的工单系统。

OpenAI 在官方技能库 openai/skills 里维护了一个名为 linear 的精选 Skill。它把「读 Issue、建项目、更新状态、写评论」这类操作，整理成 Agent 可遵循的标准工作流，底层对接 Linear 官方 MCP 服务器。对工程师团队来说，这意味着 AI 不再只是代码编辑器里的助手，也可以成为项目管理链路里的一环。

这是什么¶

linear 是一个基于通用 SKILL.md 格式的 Agent Skill，由 OpenAI 维护，源码位于 openai/skills/skills/.curated/linear。

它的定位很直接：通过 Linear MCP 服务器，用自然语言管理 Linear 中的 Issue、项目、文档与团队协作流程。Skill 本身的 description 写明了触发场景——当用户需要读取、创建或更新 Linear 中的 ticket 时使用。

与「让模型凭记忆猜工单内容」不同，这个 Skill 要求 Agent 按固定步骤调用 MCP 工具：先读再写、批量操作时说明分组逻辑、完成后汇总结果并提示后续动作。前提条件是 Linear MCP 服务器已通过 OAuth 连接，且当前账号能访问对应 workspace、团队和项目。

核心功能与亮点¶

1. 覆盖 Issue 全生命周期¶

Skill 文档列出了 Issue 相关 MCP 工具，包括：

• 查询：list_issues、get_issue、list_my_issues、list_issue_statuses、list_issue_labels
• 写入：create_issue、update_issue、create_issue_label

Agent 可以先拉取上下文，再按需创建或更新，避免「还没看清现状就乱改」。

2. 项目与团队维度¶

除单条 Issue 外，还支持：

• 项目：list_projects、get_project、create_project、update_project
• 团队与用户：list_teams、get_team、list_users
• 周期：list_cycles

适合 Sprint 规划、Release 立项、按团队查看负载等场景。

3. 文档与协作¶

• 文档：list_documents、get_document、search_documentation
• 评论：list_comments、create_comment

Standup 纪要同步到 Issue、文档缺口排查后自动开 ticket，都可以走同一套流程。

4. 内置九种实用工作流模板¶

官方 Skill 预置了可直接套用的场景，例如：

• Sprint Planning：按优先级筛选待办，创建新 Cycle 并分配任务
• Bug Triage：列出高优先级 Bug，按影响排序并推进状态
• Documentation Audit：搜索文档、为缺失或过时的章节创建 Issue
• Team Workload Balance：按负责人聚合活跃 Issue，识别过载并建议重分配
• Release Planning：创建版本项目、里程碑，并批量生成带估时的 Issue
• Cross-Project Dependencies：查找 blocked Issue，补建关联关系
• Automated Status Updates：为长期未更新的 Issue 补充进展评论
• Smart Labeling：分析未打标签的 Issue 并建议/应用标签
• Sprint Retrospectives：汇总上一 Cycle 完成情况，生成复盘 Issue

这些不是空泛描述，而是 Skill 要求 Agent 逐步执行的 workflow 指引。

安装与启用¶

使用该 Skill 分两层：安装 Skill 本身，以及 配置 Linear MCP 连接。两层都就绪后，Agent 才能实际读写 Linear 数据。

1. 安装 linear Skill¶

在 Codex CLI 或 IDE 扩展中，OpenAI 提供了精选 Skill 安装器：

$skill-installer linear

也可以从 GitHub 仓库手动复制 skills/.curated/linear/ 目录到本地 Skill 路径。Codex 会从以下位置扫描 Skill（含 .agents/skills 等）；安装后若未立即生效，重启 Codex 即可。

在 Cursor 中，可将该目录放入项目的 .cursor/skills/ 或 .agents/skills/，通过 $linear 或 /skills 显式调用；任务描述匹配时也可能被隐式选中。

ChatGPT 桌面端可在侧边栏 Skills 中浏览已安装技能，输入 @ 选择 Skill 显式调用。

2. 配置 Linear MCP（Codex）¶

Skill 文档要求：若 MCP 调用失败，需先完成 Linear MCP 配置。Codex 侧官方步骤如下：

第一步：添加 MCP 服务器

codex mcp add linear --url https://mcp.linear.app/mcp

Linear 官方 MCP 使用 Streamable HTTP 协议，读写默认端点为 https://mcp.linear.app/mcp；只读场景可改用 https://mcp.linear.app/mcp/readonly。

第二步：启用远程 MCP 客户端

首次在 Codex 中使用 MCP 时，需在 ~/.codex/config.toml 中开启相关特性。Linear 官方文档示例为：

[features]
experimental_use_rmcp_client = true

Skill 文档中也提到需设置 rmcp_client 相关配置，或通过 codex --enable rmcp_client 启用。以你当前 Codex 版本文档为准；修改配置后需重启 Codex。

第三步：OAuth 登录

codex mcp login linear

登录成功后重启 Codex，再进入 Skill 工作流的 Step 1。

3. 配置 Linear MCP（Cursor）¶

Cursor 用户可在 MCP 工具目录 搜索 Linear 一键安装，或使用 Linear 官方提供的 deeplink 完成配置。连接方式同样是 OAuth 2.1，服务端点 https://mcp.linear.app/mcp。

4. Windows / WSL 注意事项¶

Skill 文档提到：若在 Windows 上遇到连接错误，可尝试通过 WSL 运行 MCP Remote，并使用 SSE 备用端点：

{
  "mcpServers": {
    "linear": {
      "command": "wsl",
      "args": ["npx", "-y", "mcp-remote", "https://mcp.linear.app/sse", "--transport", "sse-only"]
    }
  }
}

Linear 官方文档说明 /sse 为旧版客户端的兼容路径，新环境优先使用 /mcp。

典型用法示例¶

Skill 规定了四步主流程：澄清目标 → 选择 workflow → 分批调用 MCP 工具 → 汇总结果。下面两个例子来自官方资料，可直接改编使用。

示例一：Bug 分诊¶

在 Codex 或 Cursor 中显式调用 Skill 后，可以这样描述任务：

$linear

列出我们团队所有 Critical / High 优先级的 open Bug，
按用户影响排序，把前 3 条推进到 In Progress，
并为每条 Issue 写一条说明当前处理方向的评论。

Agent 应先用 list_issues 等读接口构建上下文，确认 Issue ID 与团队 key，再调用 update_issue 和 create_comment。

示例二：Standup 纪要同步到 Issue¶

Linear 官方 MCP 文档提供了类似 prompt，Skill 的「Automated Status Updates」workflow 与之对应：

$linear

以下是今天的 Standup 纪要：
[paste notes here]

请匹配提到的 Linear Issue（按 ID、标题或负责人），
为每条高置信度匹配的 Issue 添加简洁进展评论；
无法确定的条目单独列出，不要猜测创建新 Issue。

示例三：Release 规划¶

$linear

为 v2.0 版本创建一个 Linear 项目，
里程碑包括：feature freeze、beta、docs、launch。
根据以下需求列表生成带估时的 Issue，并分配到对应里程碑：
[paste requirements]

Agent 会依次调用 create_project、create_issue，必要时 update_project 补充里程碑信息。

适用场景与注意事项¶

适合谁用¶

• 已用 Linear 管理研发流程的工程团队
• 希望 AI 参与工单分诊、Sprint 规划、Standup 同步的 Tech Lead / EM
• 在 Codex CLI、Cursor 或 ChatGPT 桌面端使用 Agent Skill 的开发者

使用限制¶

1. 必须先连上 Linear MCP。Skill 只是工作流说明书，真正读写数据靠 MCP；未 OAuth 时会停在 Step 0。
2. 写操作有权限边界。Agent 只能操作当前 OAuth 账号有权访问的 workspace；多 workspace 需分别认证。
3. 注意 API 速率限制。Skill 建议批量操作时拆分批次、复用过滤条件，避免短时间大量 list/update。
4. 复杂请求要拆步。工具调用需补全必填字段；一次塞太多变更，模型可能漏字段或触发错误。
5. 认证异常时。可清除本地 MCP 认证缓存（如 rm -rf ~/.mcp-auth）后重新登录；Windows/WSL 环境优先检查 transport 配置。

与其他工具的关系¶

• Linear MCP：提供底层 API 能力（find / create / update Issue、Project、Comment 等）
• linear Skill：规定 Agent 何时读、何时写、如何分批、如何汇报，减少「乱调工具」
• 二者缺一不可：只装 Skill 不连 MCP，Agent 有流程却无数据通道；只连 MCP 不用 Skill，则缺少场景化 playbook

小结¶

对已经把 Linear 当作项目中枢的团队来说，linear Skill 的价值在于：把「查工单、改状态、写评论、排 Sprint」从人工切换上下文，变成 Agent 可重复执行的标准流程。它不改变 Linear 本身，而是让 AI 编程工具真正接入现有项目管理栈。

官方 Skill 仓库：github.com/openai/skills/tree/main/skills/.curated/linear

Codex Skills 文档：developers.openai.com/codex/skills

Linear MCP 文档：linear.app/docs/mcp