Preface

Many teams have adopted Linear as their central hub for daily project management: Bugs flow through it, Sprints are scheduled here, and Release milestones are aligned here. But when you ask the same of an AI coding assistant—“Help me mark this Bug as In Progress and add a progress comment”—it can often only write code snippets, but cannot actually interact with your ticketing system.

OpenAI maintains a curated Skill named linear in its official skill library openai/skills. It organizes operations like “reading Issues, creating projects, updating statuses, and writing comments” into a standard workflow that Agents can follow, with the underlying layer connecting to the Linear official MCP server. For engineering teams, this means AI is no longer just an assistant in code editors, but can also become a part of the project management chain.

What This Is

linear is an Agent Skill based on the generic SKILL.md format, maintained by OpenAI, with its source code located at openai/skills/skills/.curated/linear.

Its positioning is straightforward: use natural language to manage Issues, projects, documents, and team collaboration workflows in Linear via the Linear MCP server. The Skill’s own description specifies the trigger scenario—use it when a user needs to read, create, or update tickets in Linear.

Unlike “letting the model guess ticket content from memory”, this Skill requires Agents to call MCP tools in fixed steps: read first before writing, explain grouping logic when performing batch operations, summarize results after completion, and prompt for follow-up actions. The prerequisite is that the Linear MCP server has been connected via OAuth, and the current account has access to the corresponding workspace, team, and project.

Core Features and Highlights

1. Covers the full lifecycle of Issues

The Skill documentation lists MCP tools related to Issues, including:
- Query: list_issues, get_issue, list_my_issues, list_issue_statuses, list_issue_labels
- Write: create_issue, update_issue, create_issue_label

Agents can pull context first before creating or updating as needed, avoiding “making changes without understanding the current state”.

2. Project and team dimensions

In addition to single Issues, it supports:
- Projects: list_projects, get_project, create_project, update_project
- Teams and users: list_teams, get_team, list_users
- Cycles: list_cycles

It is suitable for scenarios such as Sprint planning, Release project initiation, and viewing workloads by team.

3. Documents and collaboration

  • Documents: list_documents, get_document, search_documentation
  • Comments: list_comments, create_comment

Syncing Standup notes to Issues, automatically creating tickets after identifying documentation gaps, and more can all follow the same workflow.

4. Nine built-in practical workflow templates

The official Skill pre-configures ready-to-use scenarios, for example:
- Sprint Planning: Filter backlogs by priority, create new Cycles and assign tasks
- Bug Triage: List high-priority Bugs, sort them by impact, and advance their status
- Documentation Audit: Search documentation, create Issues for missing or outdated sections
- Team Workload Balance: Aggregate active Issues by assignee, identify overloaded members, and suggest reassignments
- Release Planning: Create version projects and milestones, and batch generate Issues with estimated time
- Cross-Project Dependencies: Find blocked Issues and establish associated relationships
- Automated Status Updates: Add progress comments to Issues that have not been updated for a long time
- Smart Labeling: Analyze unlabeled Issues and suggest/apply tags
- Sprint Retrospectives: Summarize the completion status of the last Cycle and generate retrospective Issues

These are not vague descriptions, but workflow guidelines that require Agents to execute step by step as specified in the Skill.

Installation and Enablement

Using this Skill has two layers: install the Skill itself, and configure the Linear MCP connection. Only after both are ready can the Agent actually read and write Linear data.

1. Install the linear Skill

In Codex CLI or IDE extensions, OpenAI provides a curated Skill installer:

$skill-installer linear

You can also manually copy the skills/.curated/linear/ directory from the GitHub repository to your local Skill path. Codex will scan for Skills from locations including .agents/skills; if it does not take effect immediately after installation, restart Codex.

In Cursor, you can place this directory in the project’s .cursor/skills/ or .agents/skills/, and call it explicitly via $linear or /skills; it may also be implicitly selected when the task description matches.

For the ChatGPT desktop app, you can browse installed skills in the Skills sidebar, and select the Skill explicitly by typing @.

2. Configure Linear MCP (Codex)

The Skill documentation states that if MCP calls fail, you need to complete the Linear MCP configuration first. The official steps for Codex are as follows:

Step 1: Add the MCP server

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

The official Linear MCP uses the Streamable HTTP protocol, with the default read-write endpoint at https://mcp.linear.app/mcp; for read-only scenarios, you can use https://mcp.linear.app/mcp/readonly instead.

Step 2: Enable the remote MCP client
When using MCP in Codex for the first time, you need to enable related features in ~/.codex/config.toml. The Linear official documentation example is:

[features]
experimental_use_rmcp_client = true

The Skill documentation also mentions setting up rmcp_client related configurations, or enabling it via codex --enable rmcp_client. Refer to the documentation for your current Codex version; you need to restart Codex after modifying the configuration.

Step 3: OAuth login

codex mcp login linear

After a successful login, restart Codex and proceed to Step 1 of the Skill workflow.

3. Configure Linear MCP (Cursor)

Cursor users can search for Linear in the MCP tool directory for one-click installation, or use the official Linear deeplink to complete the configuration. The connection method is also OAuth 2.1, with the service endpoint https://mcp.linear.app/mcp.

4. Notes for Windows / WSL

The Skill documentation states that if you encounter connection errors on Windows, you can try running the MCP Remote via WSL and use the SSE alternative endpoint:

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

The Linear official documentation notes that /sse is a compatible path for older clients, and /mcp should be prioritized in new environments.

Typical Usage Examples

The Skill specifies a four-step main workflow: Clarify the goal → Select a workflow → Call MCP tools in batches → Summarize results. The two examples below are from official materials and can be adapted directly for use.

Example 1: Bug Triage

After explicitly calling the Skill in Codex or Cursor, you can describe the task like this:

$linear

List all Critical / High priority open Bugs in our team,
sort them by user impact, advance the top 3 to In Progress,
and add a comment explaining the current processing direction for each Issue.

The Agent should first use read interfaces such as list_issues to build context, confirm the Issue ID and team key, then call update_issue and create_comment.

Example 2: Sync Standup Notes to Issues

The Linear official MCP documentation provides a similar prompt, which corresponds to the Skill’s “Automated Status Updates” workflow:

$linear

Here is today's Standup notes:
[paste notes here]

Please match the mentioned Linear Issues (by ID, title, or assignee),
add concise progress comments to each Issue with high-confidence matches;
list items that cannot be confirmed separately, do not guess and create new Issues.

Example 3: Release Planning

$linear

Create a Linear project for version v2.0,
with milestones including: feature freeze, beta, docs, launch.
Generate Issues with estimated time based on the following requirement list, and assign them to the corresponding milestones:
[paste requirements]

The Agent will sequentially call create_project, create_issue, and if necessary update_project to supplement milestone information.

Applicable Scenarios and Notes

Who This Is For

  • Engineering teams that already use Linear to manage their R&D workflows
  • Tech Leads / Engineering Managers who want AI to participate in ticket triage, Sprint planning, and Standup syncs
  • Developers using Agent Skills in Codex CLI, Cursor, or the ChatGPT desktop app

Usage Restrictions

  1. Must connect to Linear MCP first. The Skill is just a workflow manual, and the actual reading and writing of data relies on MCP; without OAuth authentication, it will stop at Step 0.
  2. Write operations have permission boundaries. Agents can only operate workspaces that the current OAuth account has access to; multiple workspaces require separate authentication.
  3. Pay attention to API rate limits. The Skill recommends splitting batches for bulk operations and reusing filter conditions to avoid a large number of list/update requests in a short period.
  4. Complex requests need to be broken down into steps. Tool calls need to complete mandatory fields; cramming too many changes at once may cause the model to miss fields or trigger errors.
  5. When authentication exceptions occur: You can clear the local MCP authentication cache (such as rm -rf ~/.mcp-auth) and log in again; for Windows/WSL environments, prioritize checking the transport configuration.

Relationship with Other Tools

  • Linear MCP: Provides underlying API capabilities (find / create / update Issues, Projects, Comments, etc.)
  • linear Skill: Specifies when the Agent should read, write, batch operations, and how to report results, reducing “random tool calls”
  • Both are indispensable: Installing only the Skill without connecting to MCP leaves the Agent with a workflow but no data channel; connecting only to MCP without using the Skill lacks scenario-specific playbooks.

Summary

For teams that already use Linear as their project hub, the value of the linear Skill lies in turning manual context switching for “checking tickets, changing statuses, writing comments, and scheduling Sprints” into a repeatable standard workflow that Agents can execute. It does not change Linear itself, but allows AI coding tools to truly integrate into the existing project management stack.

Official Skill repository: github.com/openai/skills/tree/main/skills/.curated/linear

Codex Skills documentation: developers.openai.com/codex/skills

Linear MCP documentation: linear.app/docs/mcp