Linear Skill

Conventions and patterns for using the Linear MCP server effectively.

When to Use This Skill

• Creating or updating Linear issues
• Managing project tasks and priorities
• Adding comments or context to issues
• Querying issues by status, assignee, or project

MCP Tools

Use the Linear MCP server tools:

Field Conventions

Title

Format: <type>: <brief description>

Types:

• feat - New feature or enhancement
• fix - Bug fix
• chore - Maintenance, refactoring, dependencies
• docs - Documentation
• perf - Performance improvement

Examples:

feat: Add user authentication flow
fix: Resolve null pointer in checkout
chore: Upgrade React to v19
docs: Update API documentation

Description

Structure descriptions consistently:

## Context
[Why this issue exists - background and motivation]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Technical Notes
[Optional: implementation hints, constraints, dependencies]

Estimate (Sizing)

Use fibonacci-style story points:

Default to smaller estimates. If unsure between 3 and 5, pick 3.

Priority

Status Workflow

Standard workflow states:

Backlog → Todo → In Progress → In Review → Done
                     ↓
                  Blocked

Status conventions:

• Backlog: Triaged but not scheduled
• Todo: Committed for current cycle
• In Progress: Actively being worked on (limit WIP)
• In Review: PR submitted, awaiting review
• Blocked: Waiting on external dependency
• Done: Shipped and verified

Labels

Use labels sparingly. Recommended categories:

Comments

When to Comment

Add comments for:

• Status updates when blocked
• Technical findings during implementation
• Links to relevant PRs or docs
• Decision rationale

Comment Format

**[Status Update]**
Blocked waiting on API credentials from vendor. ETA tomorrow.

---

**[Technical Note]**
Found that the existing auth middleware can be reused. See `src/middleware/auth.ts`.

---

**[Decision]**
Going with approach A because of X. Considered B but rejected due to Y.

Linking PRs

When a PR is created, add a comment:

**[PR Submitted]**
https://github.com/org/repo/pull/123

Ready for review.

Workflow Patterns

Creating an Issue

1. Use linear_get_teams to find team ID
2. Create issue with:
   - Descriptive title (type: description)
   - Structured description with acceptance criteria
   - Appropriate estimate (default to smaller)
   - Priority (default: Medium)
   - Status: Backlog or Todo

Starting Work

1. Move issue to "In Progress"
2. Begin implementation
3. Add comments for significant findings

Submitting for Review

1. Create PR (see Git conventions)
2. Add comment linking PR to issue
3. Move issue to "In Review"

Completing Work

1. Merge PR
2. Move issue to "Done"
3. Add final comment if needed (lessons learned, follow-up items)

Important: No Git Branches

Do NOT use Linear's git branch integration. We manage branches manually.

When working on an issue:

1. Create branches using standard git commands
2. Name branches using your team's convention (not Linear's auto-naming)
3. Link work to issues via PR descriptions or comments only

Query Examples

Find My Open Issues

Search: assignee:me is:open

Find Blocked Issues

Search: status:Blocked

Find High Priority Bugs

Search: priority:High label:bug

Find Unestimated Issues

Search: estimate:none project:"Current Sprint"

Anti-Patterns

Avoid

• Leaving issues in "In Progress" indefinitely
• Creating issues without acceptance criteria
• Using 13-point estimates (split the issue instead)
• Updating status without context (add a comment)
• Creating issues for work already done

Prefer

• Small, focused issues (< 8 points)
• Clear acceptance criteria
• Regular status updates via comments
• Closing issues when done (not leaving in review)

Quick Reference