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
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.
1---2name: linear-pm3description: Linear project management - issues, projects, cycles, and roadmaps. Use for Linear-related tasks like managing issues, tracking sprints, and organizing projects.4---56**Mode: Cognitive/Prompt-Driven** - No standalone utility script; use via agent context.78# Linear PM Skill910## Overview1112This skill provides comprehensive Linear project management capabilities with progressive disclosure for optimal context usage.1314Context Savings: ~92% reduction1516- Direct API Mode: ~15,000 tokens for full API documentation17- Skill Mode: ~300 tokens metadata + on-demand loading1819## Requirements2021- LINEAR_API_KEY environment variable set22- Internet connectivity for Linear API access2324## Toolsets2526| Toolset | Description |27| -------- | ------------------------------------------------ |28| issues | Issue creation, updates, comments, state changes |29| projects | Project management and issue association |30| cycles | Sprint/cycle management and planning |31| teams | Team structure and member management |32| labels | Label and workflow state management |3334## Tools by Category3536### Issue Operations (Confirmation Required for Mutations)3738| Tool | Description | Confirmation |39| ------------- | ------------------------------------------------- | ------------ |40| list-issues | List issues with filters (state, assignee, label) | No |41| get-issue | Get detailed issue information | No |42| create-issue | Create new issue with title, description, team | Yes |43| update-issue | Update issue fields (state, assignee, priority) | Yes |44| add-comment | Add comment to an issue | Yes |45| search-issues | Search issues by text query | No |46| assign-issue | Assign issue to team member | Yes |47| set-priority | Set issue priority (urgent, high, medium, low) | Yes |48| add-label | Add label to issue | Yes |4950### Project Operations5152| Tool | Description | Confirmation |53| -------------- | -------------------------------- | ------------ |54| list-projects | List all projects for a team | No |55| get-project | Get project details and metadata | No |56| project-issues | Get all issues in a project | No |57| create-project | Create new project | Yes |58| update-project | Update project details | Yes |5960### Cycle Operations (Sprints)6162| Tool | Description | Confirmation |63| -------------- | ------------------------------ | ------------ |64| list-cycles | List cycles for a team | No |65| current-cycle | Get current active cycle | No |66| cycle-issues | Get issues in a specific cycle | No |67| cycle-progress | Get cycle completion metrics | No |6869### Team Operations7071| Tool | Description | Confirmation |72| ------------ | --------------------------- | ------------ |73| list-teams | List all teams in workspace | No |74| get-team | Get team details | No |75| team-members | List team members | No |7677### Label & State Operations7879| Tool | Description | Confirmation |80| ------------ | -------------------------------------------------------- | ------------ |81| list-labels | List all labels for a team | No |82| list-states | List workflow states (backlog, to-do, in-progress, done) | No |83| create-label | Create new label | Yes |8485## Security8687- Never expose LINEAR_API_KEY in logs or output88- API key should have minimal required permissions89- All tools that modify data require confirmation9091## Error Handling92931. Verify API Key: Check LINEAR_API_KEY is set correctly942. Check API Rate Limits: GraphQL 1500 requests/hour; REST 500 requests/hour953. Validate Query Syntax: Ensure GraphQL queries are well-formed964. Check Team/Issue IDs: Verify IDs exist and are accessible9798## Agent Integration99100- planner: Project management and backlog prioritization101- developer: Issue tracking during development102103## Common Workflows104105### Sprint Planning1061071. current-cycle - Get current sprint1082. list-issues --state Backlog - Get backlog items1093. update-issue --cycle-id ... - Assign issues to sprint110111### Issue Triage1121131. list-issues --state Backlog - Get unplanned issues1142. set-priority --issue-id ... --priority 2 - Set priority1153. add-label --issue-id ... --label bug - Categorize116117### Project Tracking1181191. list-projects --team-id ... - Get all projects1202. project-issues --project-id ... - Get project issues1213. cycle-progress --cycle-id ... - Check sprint progress122123## Related124125- Official Linear API Documentation: <https://developers.linear.app/docs/graphql/working-with-the-graphql-api>126- Linear GraphQL Explorer: <https://studio.apollographql.com/public/Linear-API/home>127- Linear Webhook Documentation: <https://developers.linear.app/docs/graphql/webhooks>128129## Iron Laws1301311. **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.1322. **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.1333. **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.1344. **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.1355. **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.136137## Anti-Patterns138139| Anti-Pattern | Why It Fails | Correct Approach |140| ----------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |141| 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 |142| 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 |143| Fetching all team issues without filter | Thousands of results; rate limit hit; unusable output | Filter by `state`, `assignee`, `cycle`, or `label` in GraphQL query |144| 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 |145| Ignoring pagination cursors | Only first page returned; missed issues cause incomplete reports | Use `pageInfo { hasNextPage, endCursor }` and paginate until `hasNextPage: false` |146147## Memory Protocol (MANDATORY)148149**Before starting:**150Read .claude/context/memory/learnings.md151152**After completing:**153154- New pattern -> .claude/context/memory/learnings.md155- Issue found -> .claude/context/memory/issues.md156- Decision made -> .claude/context/memory/decisions.md157158> ASSUME INTERRUPTION: If it is not in memory, it did not happen.
oimiragieo