Mode: Cognitive/Prompt-Driven - No standalone utility script; use via agent context.

Linear PM Skill

Overview

This skill provides comprehensive Linear project management capabilities with progressive disclosure for optimal context usage.

Context Savings: ~92% reduction

• Direct API Mode: ~15,000 tokens for full API documentation

• Skill Mode: ~300 tokens metadata + on-demand loading

Requirements

• LINEAR_API_KEY environment variable set

• Internet connectivity for Linear API access

Toolsets

Toolset Description

issues Issue creation, updates, comments, state changes

projects Project management and issue association

cycles Sprint/cycle management and planning

teams Team structure and member management

labels Label and workflow state management

Tools by Category

Issue Operations (Confirmation Required for Mutations)

Tool Description Confirmation

list-issues List issues with filters (state, assignee, label) No

get-issue Get detailed issue information No

create-issue Create new issue with title, description, team Yes

update-issue Update issue fields (state, assignee, priority) Yes

add-comment Add comment to an issue Yes

search-issues Search issues by text query No

assign-issue Assign issue to team member Yes

set-priority Set issue priority (urgent, high, medium, low) Yes

add-label Add label to issue Yes

Project Operations

Tool Description Confirmation

list-projects List all projects for a team No

get-project Get project details and metadata No

project-issues Get all issues in a project No

create-project Create new project Yes

update-project Update project details Yes

Cycle Operations (Sprints)

Tool Description Confirmation

list-cycles List cycles for a team No

current-cycle Get current active cycle No

cycle-issues Get issues in a specific cycle No

cycle-progress Get cycle completion metrics No

Team Operations

Tool Description Confirmation

list-teams List all teams in workspace No

get-team Get team details No

team-members List team members No

Label & State Operations

Tool Description Confirmation

list-labels List all labels for a team No

list-states List workflow states (backlog, to-do, in-progress, done) No

create-label Create new label Yes

Security

• Never expose LINEAR_API_KEY in logs or output

• API key should have minimal required permissions

• All tools that modify data require confirmation

Error Handling

• Verify API Key: Check LINEAR_API_KEY is set correctly

• Check API Rate Limits: GraphQL 1500 requests/hour; REST 500 requests/hour

• Validate Query Syntax: Ensure GraphQL queries are well-formed

• Check Team/Issue IDs: Verify IDs exist and are accessible

Agent Integration

• planner: Project management and backlog prioritization

• developer: Issue tracking during development

Common Workflows

Sprint Planning

• current-cycle - Get current sprint

• list-issues --state Backlog - Get backlog items

• update-issue --cycle-id ... - Assign issues to sprint

Issue Triage

• list-issues --state Backlog - Get unplanned issues

• set-priority --issue-id ... --priority 2 - Set priority

• add-label --issue-id ... --label bug - Categorize

Project Tracking

• list-projects --team-id ... - Get all projects

• project-issues --project-id ... - Get project issues

• cycle-progress --cycle-id ... - Check sprint progress

Related

• Official Linear API Documentation: https://developers.linear.app/docs/graphql/working-with-the-graphql-api

• Linear GraphQL Explorer: https://studio.apollographql.com/public/Linear-API/home

• Linear Webhook Documentation: https://developers.linear.app/docs/graphql/webhooks

Iron Laws

• ALWAYS verify LINEAR_API_KEY is set before any API call — Linear's API returns a 401 with a generic error message when the key is missing or expired; early validation produces a clear, actionable error.

• NEVER create duplicate issues without first searching by title — Linear doesn't deduplicate issues automatically; running the skill twice without a search creates duplicate work items that confuse team tracking.

• ALWAYS use issue state IDs (not state names) when transitioning issues — state names are case-sensitive, locale-dependent, and change when teams rename states; IDs are stable.

• NEVER fetch all team issues without a filter — unbounded team queries return thousands of issues, exhaust the API rate limit, and produce unusable context dumps.

• ALWAYS cache team and project metadata within a session — team IDs and project keys don't change during a session; re-fetching on every operation wastes API quota and slows workflows.

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Creating issues without deduplication check Duplicate issues split tracking; team velocity metrics skewed Search with a title filter (issues query with filter.title.eq field) before creating

Using state names in transitions Case-sensitive; breaks when team renames state; locale issues Use workflowState { id } query to get stable IDs; transition by ID

Fetching all team issues without filter Thousands of results; rate limit hit; unusable output Filter by state , assignee , cycle , or label in GraphQL query

Re-fetching team/project metadata per operation Multiple identical API calls; rate limit waste; slow execution Fetch team and project IDs once at session start; reuse for all subsequent calls

Ignoring pagination cursors Only first page returned; missed issues cause incomplete reports Use pageInfo { hasNextPage, endCursor } and paginate until hasNextPage: false

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md

• Issue found -> .claude/context/memory/issues.md

• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it is not in memory, it did not happen.