Master Linear

A comprehensive skill for managing projects and issues in Linear — covering issue creation, project workflows, cycle management, label systems, automation, and Linear CLI/API integration for efficient team project management.

When to Use This Skill

Choose Master Linear when you need to:

• Create and manage issues, projects, and cycles in Linear
• Set up team workflows with custom states and labels
• Automate issue triage and assignment
• Integrate Linear with GitHub, Slack, or other tools
• Query and update Linear data via CLI or API

Consider alternatives when:

• You need Jira administration (use a Jira skill)
• You need GitHub Projects management (use a GitHub skill)
• You need general project management (use a PM skill)

Quick Start

Copy
# Install Linear CLI (if available via MCP server)
# Or use the Linear API directly

# Create an issue
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { issueCreate(input: { title: \"Fix login timeout\", description: \"Users report 504 errors after 30s on login page\", teamId: \"TEAM_ID\", priority: 1 }) { success issue { id identifier url } } }"
  }'

Copy
// Linear SDK usage
import { LinearClient } from "@linear/sdk";

const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

// Create an issue
const issue = await linear.createIssue({
  title: "Fix login timeout",
  description: "Users report 504 errors after 30 seconds on login page.",
  teamId: "TEAM_ID",
  priority: 1, // Urgent
  labelIds: ["bug-label-id"],
});
console.log(`Created: ${issue.issue?.identifier}`);

// Query issues
const myIssues = await linear.issues({
  filter: {
    assignee: { id: { eq: "USER_ID" } },
    state: { type: { in: ["started", "unstarted"] } },
  },
});

for (const issue of myIssues.nodes) {
  console.log(`${issue.identifier}: ${issue.title} [${issue.state?.name}]`);
}

Core Concepts

Linear Data Model

Entity	Purpose	Hierarchy
Workspace	Top-level organization	Contains teams
Team	Group of people working together	Contains projects
Project	Larger initiative with milestones	Contains issues
Cycle	Time-boxed sprint/iteration	Contains issues
Issue	Single unit of work	Belongs to team
Label	Categorization tag	Applied to issues

Issue Workflow States

Copy
## Default Issue States

### Backlog States
- **Backlog** — Not yet prioritized
- **Triage** — Needs review and prioritization

### Active States
- **Todo** — Prioritized, ready to start
- **In Progress** — Actively being worked on
- **In Review** — Awaiting code review or QA

### Done States
- **Done** — Completed successfully
- **Canceled** — Won't be done (with reason)
- **Duplicate** — Merged with another issue

## Custom States (Example: Bug Workflow)
Reported → Triaged → Investigating → Fix in Progress →
Fix in Review → Testing → Verified → Done

Issue Prioritization

Copy
## Linear Priority Levels

| Priority | Label    | Response Time      | Use Case                |
|----------|----------|--------------------|-------------------------|
| 0        | No Priority | —              | Backlog items           |
| 1        | Urgent   | Immediate          | Production outages      |
| 2        | High     | This cycle         | Important bugs, blockers|
| 3        | Medium   | Next 1-2 cycles    | Features, improvements  |
| 4        | Low      | When possible      | Nice-to-haves, cleanup  |

Configuration

Parameter	Description	Example
api_key	Linear API key	process.env.LINEAR_API_KEY
team_id	Default team for issue creation	"TEAM_ID"
default_state	Default issue state	"Backlog"
cycle_length	Sprint/cycle duration in weeks	2
labels	Available issue labels	["bug", "feature", "chore"]
auto_assign	Auto-assign issues to creator	true

Best Practices

1. Use projects for initiatives, cycles for time-boxing — Projects group related issues toward a goal (e.g., "Auth Redesign"). Cycles are time-boxed sprints. An issue belongs to a project (what it serves) and a cycle (when it's done). Don't conflate the two.

2. Keep issue descriptions actionable, not just descriptive — "Login is broken" is a report. "Login returns 504 after 30 seconds. Expected: login completes in <3 seconds. Reproduction: submit form with valid credentials on /login." is actionable.

3. Limit WIP (Work in Progress) per person to 2-3 issues — If every team member has 8 issues "In Progress," nothing is actually progressing. Limit active work to force completion before starting new tasks.

4. Use labels for cross-cutting concerns, not for workflow — Labels like "bug," "performance," or "security" work well because they apply across workflow states. Don't use labels for workflow stages ("ready-for-review") — that's what custom states are for.

5. Archive completed projects and cycles regularly — Completed projects and old cycles clutter the interface and slow down queries. Archive them monthly. The data is preserved and searchable but doesn't pollute active views.

Common Issues

Issue counts grow faster than issue completion — The backlog becomes a graveyard of stale issues. Implement a monthly backlog review: if an issue has been in backlog for 3+ months without activity, either prioritize it or close it with a reason.

Teams use different workflow states inconsistently — One team's "In Review" means "code review," while another's means "QA testing." Standardize state definitions across teams and document what each state means explicitly.

Linear API rate limits slow down bulk operations — Linear's API has rate limits. For bulk imports or updates, batch operations and add delays between requests. Use the SDK's built-in pagination for large queries instead of fetching everything at once.