Imported from oimiragieo/agent-studio (.claude/skills/linear-pm/SKILL.md). Install upstream with npx skills add oimiragieo/agent-studio --skill linear-pm. Copyright stays with the author.

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

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.

linear-pm

About