Skip to content
OpenAI linear

OpenAI linear Skill

by OpenAI openai/skills

OpenAI's skill for driving Linear through its MCP server: a read-first workflow for issue triage, sprint planning, documentation audits and workload balancing, with the MCP setup and OAuth steps written out.

GitHub
Development
Released

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from openai/skills.

$ npx skills add openai/skills --skill linear

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/linear/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/linear/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • Writes out the Linear MCP setup: remote server URL, remote MCP client flag, OAuth login and the required restart
  • WSL fallback config for Windows connection errors
  • Read-first execution order: list/get/search to build context before any create or update
  • Explains the grouping logic before applying a bulk change
  • Nine concrete plays, from sprint planning and bug triage to retrospectives and dependency discovery
  • Troubleshooting for OAuth, missing required fields and Linear API rate limits

Linear's MCP server gives an agent the tools; it does not tell the agent how to use them well. linear is OpenAI's curated skill that supplies the missing procedure — and, usefully, the setup steps people get stuck on.

It starts before the first tool call

Step 0 is the Linear MCP connection itself: add the remote server (https://mcp.linear.app/mcp), enable the remote MCP client, complete the OAuth login, and — the detail that saves an afternoon — restart the client afterwards, which the skill tells the user explicitly rather than looping on a failing call. There is a documented WSL fallback for Windows connection errors, routing through mcp-remote over SSE.

The workflow

After setup it enforces four ordered steps: clarify the goal and scope (team, project, priority, labels, cycle, due dates); choose the workflow and confirm the identifiers the tools will need; execute in logical batches — read first with list/get/search to build context, then create and update, explaining the grouping before any bulk change; and finally summarise results, remaining gaps and proposed next actions.

The read-before-write rule and the explain-before-bulk rule are the two that matter. Bulk operations on an issue tracker are hard to undo and easy to get subtly wrong, and narrating the grouping first gives you a chance to stop it.

What it covers

The skill maps the Linear MCP tool surface — issues (list_issues, get_issue, create_issue, update_issue, list_my_issues, statuses, labels), projects and teams (list_projects, create_project, update_project, list_teams, list_users), and documentation and collaboration (list_documents, search_documentation, list_comments, create_comment, list_cycles) — onto nine concrete plays: sprint planning, bug triage, documentation audit, workload balancing, release planning, cross-project dependency discovery, automated status updates, smart labelling and sprint retrospectives.

It closes with a troubleshooting section for the three things that actually go wrong: OAuth and workspace permissions, tool-calling errors from missing required fields, and Linear's API rate limits when a bulk operation runs too wide.

Who it is for

Engineering teams running Linear who want an agent to do the tracker housekeeping — triage, labelling, retro reports — without it quietly reorganising a board. From OpenAI's curated public skills collection.

Try it

Once installed, ask your agent something like:

Triage the open bugs on the Platform team in Linear: rank the critical and high ones by user impact, and move the top five to In Progress.

SKILL.md

The instructions your agent loads, as published by OpenAI.

SKILL.md
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

Overview

This skill provides a structured workflow for managing issues, projects & team workflows in Linear. It ensures consistent integration with the Linear MCP server, which offers natural-language project management for issues, projects, documentation, and team collaboration.

Prerequisites
  • Linear MCP server must be connected and accessible via OAuth
  • Confirm access to the relevant Linear workspace, teams, and projects
Required Workflow

Follow these steps in order. Do not skip steps.

Step 0: Set up Linear MCP (if not already configured)

If any MCP call fails because Linear MCP is not connected, pause and set it up:

  1. Add the Linear MCP:
  • codex mcp add linear --url https://mcp.linear.app/mcp
  1. Enable remote MCP client:
  • Set [features] rmcp_client = true in config.toml or run codex --enable rmcp_client
  1. Log in with OAuth:
  • codex mcp login linear

After successful login, the user will have to restart codex. You should finish your answer and tell them so when they try again they can continue with Step 1.

Windows/WSL note: If you see connection errors on Windows, try configuring the Linear MCP to run via WSL:

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

Clarify the user's goal and scope (e.g., issue triage, sprint planning, documentation audit, workload balance). Confirm team/project, priority, labels, cycle, and due dates as needed.

Step 2

Select the appropriate workflow (see Practical Workflows below) and identify the Linear MCP tools you will need. Confirm required identifiers (issue ID, project ID, team key) before calling tools.

Step 3

Execute Linear MCP tool calls in logical batches:

  • Read first (list/get/search) to build context.
  • Create or update next (issues, projects, labels, comments) with all required fields.
  • For bulk operations, explain the grouping logic before applying changes.
Step 4

Summarize results, call out remaining gaps or blockers, and propose next actions (additional issues, label changes, assignments, or follow-up comments).

Available Tools

Issue Management: list_issues, get_issue, create_issue, update_issue, list_my_issues, list_issue_statuses, list_issue_labels, create_issue_label

Project & Team: list_projects, get_project, create_project, update_project, list_teams, get_team, list_users

Documentation & Collaboration: list_documents, get_document, search_documentation, list_comments, create_comment, list_cycles

Practical Workflows
  • Sprint Planning: Review open issues for a target team, pick top items by priority, and create a new cycle (e.g., "Q1 Performance Sprint") with assignments.
  • Bug Triage: List critical/high-priority bugs, rank by user impact, and move the top items to "In Progress."
  • Documentation Audit: Search documentation (e.g., API auth), then open labeled "documentation" issues for gaps or outdated sections with detailed fixes.
  • Team Workload Balance: Group active issues by assignee, flag anyone with high load, and suggest or apply redistributions.
  • Release Planning: Create a project (e.g., "v2.0 Release") with milestones (feature freeze, beta, docs, launch) and generate issues with estimates.
  • Cross-Project Dependencies: Find all "blocked" issues, identify blockers, and create linked issues if missing.
  • Automated Status Updates: Find your issues with stale updates and add status comments based on current state/blockers.
  • Smart Labeling: Analyze unlabeled issues, suggest/apply labels, and create missing label categories.
  • Sprint Retrospectives: Generate a report for the last completed cycle, note completed vs. pushed work, and open discussion issues for patterns.
Tips for Maximum Productivity
  • Batch operations for related changes; consider smart templates for recurring issue structures.
  • Use natural queries when possible ("Show me what John is working on this week").
  • Leverage context: reference prior issues in new requests.
  • Break large updates into smaller batches to avoid rate limits; cache or reuse filters when listing frequently.
Troubleshooting
  • Authentication: Clear browser cookies, re-run OAuth, verify workspace permissions, ensure API access is enabled.
  • Tool Calling Errors: Confirm the model supports multiple tool calls, provide all required fields, and split complex requests.
  • Missing Data: Refresh token, verify workspace access, check for archived projects, and confirm correct team selection.
  • Performance: Remember Linear API rate limits; batch bulk operations, use specific filters, or cache frequent queries.
Install

Alternatives

See all OpenAI linear alternatives
Browse all skills →