Codex Skill 实战：用 Linear MCP 在 Codex 中管理 Issue、项目与团队工作流-酒店常州论坛

Codex Skill 实战：用 Linear MCP 在 Codex 中管理 Issue、项目与团队工作流

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本篇技术指南围绕 Skills Catalog 中 curated 级别的 linear Skill 展开，讲解如何在 Codex 中通过 Linear MCP 服务器以自然语言完成 Issue 的读取、创建与更新，以及项目（Project）、周期（Cycle）、评论、文档和团队协作等完整工作流。读完本文，你将掌握 Linear MCP 的安装与 OAuth 登录方法、Codex 中必须遵守的四步执行流程、工具清单的职责划分，以及冲刺规划、缺陷分流、文档审计、负载均衡、发布规划等九个开箱即用的实战场景，并学会批量操作与限流规避等最佳实践。

一、Skill 是什么：从仓库结构看 linear Skill 的定位

在 skills 目录中，每个 Skill 都是一个自包含的文件夹，内含指令文档SKILL.md、Agent 元数据agents/openai.yaml、资源文件（assets）与许可证（LICENSE.txt）。Agent Skills 的理念是"写一次，处处可用"（Write once, use everywhere）：将指令、脚本和资源打包成文件夹，供 AI Agent 发现并复用来完成特定任务。

linear Skill 位于 skills/.curated/linear（curated 即"精选"层级），其核心指令文件是 SKILL.md。该文件的 front-matter 声明了 Skill 的名称与用途：

name: linear description: Manage issues, projects & team workflows in Linear. Use when the user wants to read, create or updates tickets in Linear. metadata: short-description: Manage Linear issues in Codex

即：当用户想要读取、创建或更新 Linear 工单（tickets）时，Codex 会自动匹配并加载该 Skill。

配套的 agents/openai.yaml 则声明了该 Skill 对外暴露的 Agent 界面与依赖：

interface: display_name: "Linear" short_description: "Manage Linear issues in Codex" icon_small: "./assets/linear-small.svg" icon_large: "./assets/linear.png" default_prompt: "Use Linear context to triage or update relevant issues for this task, with clear next actions." dependencies: tools: - type: "mcp" value: "linear" description: "Linear MCP server" transport: "streamable_http" url: "https://mcp.linear.app/mcp"

从该文件可以看到 Skill 的核心依赖是一个名为linear的 MCP 工具，采用streamable_http传输方式，服务地址为https://mcp.linear.app/mcp。这正是 SKILL.md 中所有工作流得以执行的基础。

二、前置条件

在使用本 Skill 之前，需要满足以下两个条件：

Linear MCP 服务器必须已连接且可通过 OAuth 访问：即 Codex 环境中已注册并登录了 Linear 的 MCP 服务器；
确认对相关 Linear 工作区（workspace）、团队（teams）和项目（projects）具有访问权限：MCP 连接成功只代表通道打通，具体能否读写取决于账号在 Linear 工作区中的权限范围。

从 agents/openai.yaml 的依赖声明可以确认，该 Skill 不携带任何本地脚本，所有能力全部经由 MCP 工具透传，因此"MCP 是否连上"是全部前置条件的核心。

三、Required Workflow：必须按序执行的四步流程

SKILL.md 强调这是一套必须按顺序执行的流程，不得跳步（"Follow these steps in order. Do not skip steps."）。在实际使用中，Codex 会按以下 Step 0 到 Step 4 逐步推进。

Step 0：初始化 Linear MCP（如尚未配置）

如果任何 MCP 调用因为 Linear MCP 未连接而失败，应先暂停并完成以下三步初始化：

添加 Linear MCP：

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

启用远程 MCP 客户端（rmcp_client），二选一：
- 在config.toml中设置[features] rmcp_client = true；
- 或运行codex --enable rmcp_client。
使用 OAuth 登录：
```
codex mcp login linear
```

登录成功后，用户必须重启 Codex。此时 Agent 应当结束回答并明确告知用户：重启后再次发起请求即可从 Step 1 继续，而不是让用户误以为会话已经中断。

Windows / WSL 特殊说明

如果在 Windows 上遇到连接错误，可以尝试让 Linear MCP 通过 WSL 运行，使用如下 JSON 配置：

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

注意这里使用的是 SSE 传输端点https://mcp.linear.app/sse，并通过--transport sse-only强制走 SSE 协议，与默认的streamable_http（见 agents/openai.yaml）不同，二者按运行环境选用。

Step 1：澄清目标与范围

先明确用户的诉求与边界，例如：Issue 分流（issue triage）、冲刺规划（sprint planning）、文档审计（documentation audit）、负载均衡（workload balance）等。必要时确认团队/项目、优先级（priority）、标签（labels）、周期（cycle）和截止日期（due dates）。

Step 2：选择工作流并确认工具与标识符

根据目标从后文"Practical Workflows"中选择合适的工作流，并确定将要调用的 Linear MCP 工具。在调用工具前必须确认所需的标识符，例如：

Issue ID（工单编号）
Project ID（项目编号）
Team key（团队键，Linear 中用于标识团队，如ENG）

标识符缺失是 MCP 调用失败的常见原因，这一步是为了避免无效调用。

Step 3：按逻辑批次执行 MCP 调用

执行顺序遵循"先读后写、批量操作先解释"的原则：

先读（list/get/search）：先建立上下文，再动手修改；
再创建或更新（issues、projects、labels、comments）：确保带上所有必填字段；
批量操作前先说明分组逻辑：让用户理解即将发生的变更再应用。

Step 4：汇总结果并给出下一步

执行完成后，汇总结果、指出剩余的缺口（gaps）或阻塞项（blockers），并提议后续动作，例如：补充 Issue、调整标签、重新分配负责人或追加评论。

四、Available Tools：Linear MCP 工具清单

SKILL.md 将可用工具按职责划分为三组：

分组	工具
Issue 管理	`list_issues`、`get_issue`、`create_issue`、`update_issue`、`list_my_issues`、`list_issue_statuses`、`list_issue_labels`、`create_issue_label`
项目与团队	`list_projects`、`get_project`、`create_project`、`update_project`、`list_teams`、`get_team`、`list_users`
文档与协作	`list_documents`、`get_document`、`search_documentation`、`list_comments`、`create_comment`、`list_cycles`

从工具命名可以推断底层能力边界：Issue 组覆盖了工单的全生命周期（列表、详情、创建、更新、状态、标签）；项目与团队组面向项目管理维度；文档与协作组则打通了 Linear 的文档搜索、评论与周期数据。这些工具经 MCP 协议（streamable_http）暴露给 Codex，由 agents/openai.yaml 中的依赖声明保证加载。

五、Practical Workflows：九个可直接套用的实战工作流

这是 SKILL.md 的核心价值所在，覆盖了研发团队最常见的九类场景：

冲刺规划（Sprint Planning）：查看目标团队的未关闭 Issue，按优先级挑选重点事项，创建新周期（cycle，例如 "Q1 Performance Sprint"）并分配负责人。
缺陷分流（Bug Triage）：列出 critical/high 优先级缺陷，按用户影响面排序，将排在最前面的缺陷移动到 "In Progress" 状态。
文档审计（Documentation Audit）：在文档中搜索（例如 API auth 相关主题），针对缺失或过时的章节创建带 "documentation" 标签的 Issue，并附上详细的修复说明。
团队负载均衡（Team Workload Balance）：按负责人（assignee）分组统计活跃 Issue，标记负载过高的成员，建议或直接应用重新分配方案。
发布规划（Release Planning）：创建项目（例如 "v2.0 Release"），内置里程碑（feature freeze、beta、docs、launch），并生成带工时估算（estimates）的 Issue。
跨项目依赖（Cross-Project Dependencies）：找出所有 "blocked" 状态的 Issue，定位阻塞源（blockers），若缺少对应的关联工单则创建链接。
自动化状态更新（Automated Status Updates）：找出长期无更新的、属于你的 Issue，根据当前状态或阻塞情况追加状态评论。
智能打标（Smart Labeling）：分析未打标签的 Issue，建议或应用合适的标签，必要时新建缺失的标签类别（对应list_issue_labels、create_issue_label）。
冲刺复盘（Sprint Retrospectives）：为最近一个已完成的周期生成报告，记录"已完成 vs 顺延"（completed vs pushed）的工作，并为发现的模式创建讨论型 Issue。

这九个场景与 Step 1 中"明确目标"一一呼应：无论用户想要做什么，都能在这里找到一个标准化的执行模板。

六、Tips for Maximum Productivity：最大化生产力的技巧

SKILL.md 给出了四条关键技巧：

批量操作：将相关的变更合并成批次处理；对反复出现的 Issue 结构，考虑使用智能模板（smart templates）；
使用自然语言查询：能直接用自然语言表达需求，例如 "Show me what John is working on this week"；
善用上下文：在新请求中引用之前的 Issue，让 Linear MCP 基于既有上下文继续工作；
拆分批处理以规避限流：将大规模更新拆成较小的批次，避免触发速率限制；频繁使用的列表查询应缓存或复用过滤器。

其中"分批规避限流"与后文 Troubleshooting 中的 Performance 条目相互印证，说明 Linear API 的速率限制是真实存在的约束，批量与缓存是应对它的标准手段。

七、Troubleshooting：常见问题与排查

SKILL.md 将排障归纳为四类：

认证（Authentication）：清除浏览器 Cookie，重新执行 OAuth，核验工作区权限，确保 API 访问已启用；
工具调用错误（Tool Calling Errors）：确认当前模型支持多次工具调用（multiple tool calls），提供所有必填字段，将复杂请求拆分为多个简单请求；
数据缺失（Missing Data）：刷新 token，核验工作区访问权限，检查是否存在已归档的项目（archived projects），确认选择了正确的团队；
性能（Performance）：牢记 Linear API 有速率限制；批量操作使用分批处理，查询使用具体过滤器，高频查询做好缓存。

结合 Step 0 的内容，绝大多数连接类问题都可以归结为"MCP 未正确初始化"或"认证过期"两类根因，按序排查即可。

八、安装与本仓库关联说明

本仓库 README.md 说明：.system目录下的 Skill 会在最新版 Codex 中自动安装；而 curated 层级的 Skill（linear 即属于此类）需要在 Codex 中使用$skill-installer按名称安装，例如：

$skill-installer gh-address-comments

安装完成后重启 Codex 即可生效。linear Skill 自身的许可协议见其目录内的 LICENSE.txt（Apache License 2.0）。

需要说明的是，该 Skill 是"纯指令 + MCP 依赖"型：它不包含本地脚本，全部功能经由linear这个 MCP 工具透传。这意味着它的可用性完全取决于 Linear MCP 服务器的连接状态与用户工作区权限，这也解释了为什么 SKILL.md 会把"初始化 MCP"列为 Step 0，并强制要求按序执行全部步骤。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析