Agent-Skills.md

Agent Skills: Linear PM Skill

Linear project management - issues, projects, cycles, and roadmaps. Use for Linear-related tasks like managing issues, tracking sprints, and organizing projects.

UncategorizedID: oimiragieo/agent-studio/linear-pm

Repository

oimiragieo/agent-studio
oimiragieo
19

Install this agent skill to your local

pnpm dlx add-skill https://github.com/oimiragieo/agent-studio/tree/HEAD/.claude/skills/linear-pm

Skill Files

Browse the full folder contents for linear-pm.

Download Skill

Loading file tree…

.claude/skills/linear-pm/SKILL.md

Skill Metadata

Name
linear-pm
Description
Linear project management - issues, projects, cycles, and roadmaps. Use for Linear-related tasks like managing issues, tracking sprints, and organizing projects.

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

  1. Verify API Key: Check LINEAR_API_KEY is set correctly
  2. Check API Rate Limits: GraphQL 1500 requests/hour; REST 500 requests/hour
  3. Validate Query Syntax: Ensure GraphQL queries are well-formed
  4. 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

  1. current-cycle - Get current sprint
  2. list-issues --state Backlog - Get backlog items
  3. update-issue --cycle-id ... - Assign issues to sprint

Issue Triage

  1. list-issues --state Backlog - Get unplanned issues
  2. set-priority --issue-id ... --priority 2 - Set priority
  3. add-label --issue-id ... --label bug - Categorize

Project Tracking

  1. list-projects --team-id ... - Get all projects
  2. project-issues --project-id ... - Get project issues
  3. cycle-progress --cycle-id ... - Check sprint progress

Related

Iron Laws

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.