linear

What this skill does

# Linear

Structured workflow for managing issues, projects, and team workflows in Linear via the Linear MCP server (OAuth-based, remote).

## Prerequisites

- Linear MCP server connected via your MCP integration (OAuth)
- If any Linear MCP tool call fails, the user may need to reconnect their Linear integration.

## Workflow

**Follow these steps in order.**

### Step 1: Clarify Scope

Confirm the user's goal: issue creation, triage, sprint planning, status update, documentation, workload review, etc. Identify team, project, priority, labels, cycle, and due dates as needed.

### Step 2: Read First

Always query before mutating. Build context with read operations:

| Goal | Tool |
|------|------|
| Find issues | `list_issues` (filter by team, assignee, state, label, project, priority) |
| My open work | `list_issues` with `assignee: "me"` |
| Issue details | `get_issue` with issue identifier (e.g., `CON-435`) |
| Team lookup | `list_teams` |
| Project lookup | `list_projects`, `get_project` |
| Available states | `list_issue_statuses` (requires `team`) |
| Available labels | `list_issue_labels` (optional `team` filter) |
| Cycles | `list_cycles` |
| Documents | `list_documents`, `get_document`, `search_documentation` |
| Comments | `list_comments` (requires `issueId`) |
| Users | `list_users`, `get_user` |
| Initiatives | `list_initiatives`, `get_initiative` |
| Milestones | `list_milestones` (requires `project`) |
| Status updates | `get_status_updates` |

### Step 3: Create or Update

Use `save_issue` for both creating and updating:

**Creating:** `title` and `team` are required. Omit `id`.
```
save_issue(title: "...", team: "Content", description: "...", priority: 3, labels: ["Bug"])
```

**Updating:** Pass `id` with the issue identifier.
```
save_issue(id: "CON-435", state: "In Progress", assignee: "me")
```

Other mutation tools:
- `save_comment` - add comments to issues
- `save_project`, `save_initiative`, `save_milestone` - project management
- `save_status_update` - post status updates
- `create_issue_label` - create new labels
- `create_document`, `update_document` - Linear docs
- `create_attachment` - attach files to issues

### Step 4: Summarize

After mutations, report what changed. Call out remaining gaps, blockers, or suggested next actions.

## Priority Values

| Value | Meaning |
|-------|---------|
| 0 | None |
| 1 | Urgent |
| 2 | High |
| 3 | Normal |
| 4 | Low |

## Practical Workflows

- **Sprint planning:** List open issues for a team, pick top items by priority, assign to a cycle
- **Bug triage:** List critical/high-priority bugs, rank by impact, move top items to In Progress
- **Team workload:** Group active issues by assignee, flag overloaded members, suggest redistributions
- **Release planning:** Create a project with milestones, generate issues with estimates
- **Status updates:** Find issues with stale updates, add status comments based on current state
- **Smart labeling:** Analyze unlabeled issues, suggest/apply labels, create missing categories
- **Cross-project dependencies:** Find blocked issues, identify blockers, create linked issues if missing

## Tips

- Use `assignee: "me"` for personal issue queries
- Batch related operations logically; don't create 20 issues one at a time without confirmation
- Use `query` parameter for text search across issue titles and descriptions
- `list_issues` with `state: "In Progress"` finds active work
- Duration filters use ISO-8601: `createdAt: "-P7D"` for last 7 days
- Link attachments to issues with the `links` field on `save_issue`: `[{url, title}]`
- Relations (`blocks`, `blockedBy`, `relatedTo`) are append-only on `save_issue`