Awesome-omni-skill linear

Manage Linear issues, projects, and cycles. Maintains session memory across conversations for context continuity.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/product/linear" ~/.claude/skills/diegosouzapw-awesome-omni-skill-linear-1fc1d0 && rm -rf "$T"

manifest: skills/product/linear/SKILL.md

source content

Linear Skill

Manage your Linear workspace from the command line with persistent session memory.

Project Configuration

Before using this skill, read

config.json

for project-specific values:

```
team
```
- The team key to use (e.g., "WIL")
```
defaultProject
```
- Default project ID for new issues
```
projects
```
- Named project shortcuts with IDs and descriptions
```
priorityContext
```
- What priority levels mean for this project's current phase
```
labels
```
- Label name to ID mappings
```
workflows
```
- Default states/priorities for different issue types

Use these values instead of the generic

TEAM

placeholders in examples below.

Project Conventions

This section documents agreed-upon conventions for using Linear. Customize these for your project.

Priority Definitions

Priority	Value	Meaning	Usage
Urgent	1	Hot fix to production	Blocking work on production, drop everything
High	2	Critical for current release	Required before next production deployment
Medium	3	Standard priority	Scheduled alongside feature work
Low	4	Nice-to-have, deferred	Revisit when ahead of schedule
None	0	Not yet prioritized	Needs review

Key behaviors:

Urgent: Developer patches immediately; stakeholders notified
High: Must be completed before production deployment
Medium: Scheduled alongside feature work
Low: Kept in backlog, won't delay deadlines

Status Workflow

┌─────────────────┐     ┌─────────────┐
│  CLIENT REVIEW  │     │   TRIAGE    │
│  (Client Inbox) │     │ (Dev Inbox) │
└────────┬────────┘     └──────┬──────┘
         │                     │
         └──────────┬──────────┘
                    ▼
              ┌───────────┐
              │   TO DO   │
              └─────┬─────┘
                    ▼
              ┌───────────┐
              │IN PROGRESS│
              └─────┬─────┘
                    ▼
              ┌───────────┐
              │  DEV DONE │
              └─────┬─────┘
                    ▼
            ┌─────────────┐
            │READY TO TEST│
            └──────┬──────┘
                   ▼
              ┌──────────┐
              │   DONE   │
              └──────────┘

Status	Owner	Meaning
Client Review	Client	Developer-created tickets awaiting client approval of priority/details
Triage	Developer	Client-reported bugs/issues awaiting developer review
To Do	Both	Approved, prioritized, ready to be worked on
In Progress	Developer	Actively being developed
Dev Done	Developer	Code complete (PR merged), not yet deployed to staging
Ready to Test	Client	Deployed to staging, awaiting client testing
Done	Both	Client tested and approved
Canceled	Both	Work determined to be unnecessary

Transition responsibilities:

```
→ Client Review
```
: Developer creates ticket from planning/meetings
```
Client Review → To Do
```
: Client approves after reviewing
```
→ Triage
```
: Client reports bug directly
```
Triage → To Do
```
: Developer reviews, sets priority
```
To Do → In Progress
```
: Developer picks up work
```
In Progress → Dev Done
```
: Code complete
```
Dev Done → Ready to Test
```
: Deployed to staging
```
Ready to Test → Done
```
: Client tests successfully

Inbox goal: Both

Client Review

and

Triage

should trend toward empty.

Projects

Organize work into projects based on your needs:

Project Type	Purpose
Support & Maintenance	Bug fixes, polish, production support
Feature Development	New feature work by phase or milestone
Infrastructure	Technical improvements, refactoring

Assignment rules:

Production bugs → Support project
New features → Appropriate feature project
Urgent hot fixes → May skip project assignment (priority is enough)

Labels

Label	Usage
`bug`	Something broken that needs fixing
`feature`	New functionality
`improvement`	Enhancement to existing functionality

Communication

Linear is the primary channel for project work
Use comments within tickets for discussion
@ mentions notify via inbox
Check inbox regularly for messages

Creating Issues from Transcripts

When generating issues from meeting transcripts:

Set status to
Client Review
(not Triage) - Client needs to approve
Include in description:
- Context from discussion
- Location in app (if applicable)
- Steps to reproduce (for bugs)
- Acceptance criteria (for features)
Set priority based on meeting discussion
Assign to project based on type
Add appropriate label (bug/feature/improvement)

Checking Your Inbox

Your Linear inbox contains notifications about issues you're assigned to, mentioned in, or have subscribed to. This is how client feedback and updates reach you.

Commands:

# View all notifications (most recent first)
npx linear-skill inbox

# View only unread notifications
npx linear-skill inbox --unread

# Limit to specific count
npx linear-skill inbox --unread --limit 10

Notification types include:

```
issueAssignedToYou
```
- You were assigned to an issue
```
issueNewComment
```
- Someone commented on an issue you follow
```
issueMention
```
- You were @mentioned in a comment
```
issueStatusChanged
```
- Status changed on an issue you follow
And many more...

Workflow tip: Check your inbox at the start of each session to see client feedback and updates since your last session. This is especially useful for catching comments on recently completed work.

Reading Comments & Client Feedback

Comments contain important client feedback, clarifications, and discussion history. Use them strategically to stay context-efficient.

When to use

--comments

flag or
comments
command:

Planning implementation for specific tickets (1-5 tickets)
Reviewing client feedback before starting work
Checking for clarifications or scope changes
Preparing spec documents that need client context

When NOT to fetch comments:

Broad searches across many tickets (
```
issues --team TEAM
```
)
Filtering/triaging tickets by status or priority
Quick status checks or updates
Bulk operations

Commands:

# Lightweight - just comments for quick review
npx linear-skill comments TEAM-123

# Full context - issue details + comments for implementation planning
npx linear-skill issue TEAM-123 --comments

Workflow tip: When moving tickets from

To Do

In Progress

, fetch comments first to ensure you have the latest client context before writing implementation specs.

Viewing Screenshots & Attachments

Issues often include screenshots showing bugs, UI states, or expected behavior. The skill returns signed URLs that are publicly accessible for 1 hour.

Output fields when using

--comments

```
inlineImages
```
- Images embedded in description or comments (extracted from markdown
```
![alt](url)
```
)
```
attachments
```
- Files attached to the issue

Workflow to view screenshots:

Fetch the issue with comments to get signed URLs:

npx linear-skill issue TEAM-123 --comments

Download images to the skill's cache directory:

# Create cache directory if needed
mkdir -p ~/.linear-skill/images

# Download each image (use the signed URL from output)
curl -s -o ~/.linear-skill/images/screenshot-1.png "<signed-url>"

View the image using the Read tool:

# Claude can view the downloaded image
Read ~/.linear-skill/images/screenshot-1.png

Clean up after reviewing (images are not auto-deleted):

rm ~/.linear-skill/images/*.png

Important notes:

Signed URLs expire after 1 hour - re-fetch the issue if URLs have expired
macOS does NOT auto-clean
```
/tmp
```
, so use
```
~/.linear-skill/images/
```
for predictable cleanup
Always review screenshots before implementing bug fixes to understand the exact issue
Multiple screenshots may show different states (before/after, different views, etc.)

Release Workflow

For staging → production releases:

All
```
High
```
priority items must be
```
Done
```
```
Medium
```
items are optional for current release
```
Low
```
items are explicitly deferred
Once all required items are
```
Done
```
, deploy to production

Semantic versioning may be adopted for tracking releases.

Starting a Session

Always load context first to see what you were working on:

npx linear-skill context

This shows:

Recent session summaries
Focus tickets from last session
Recent actions taken
Any notes you left

Quick Start

# Setup (one time)
cp .env.example .env
cp config.example.json config.json
# Edit .env with your LINEAR_API_KEY
npm install && npm run build

# Load previous context
npx linear-skill context

# List your assigned issues
npx linear-skill issues --assignee me

# Create an issue (for transcript-generated tickets, use Client Review state)
npx linear-skill create "Fix login bug" --team TEAM --state "Client Review"

# Update an issue
npx linear-skill update TEAM-123 --state "In Progress"

# Quick actions
npx linear-skill start TEAM-123    # Move to "In Progress"
npx linear-skill done TEAM-123     # Move to "Done"

# Mark tickets as current focus
npx linear-skill focus TEAM-123 TEAM-456

# Save session before ending
npx linear-skill session-save "Completed auth work, PR ready for review"

Session Memory

The skill remembers your recent work across conversations:

Auto-tracking: All issue interactions are logged automatically
Focus tickets: Mark what you're actively working on
Session summaries: 2-3 recent session summaries are kept
Context command: Loads this into new conversations

Command Categories

Read Commands

```
teams
```
- List all teams
```
users
```
- List users (use
```
--me
```
for current user)
```
states --team TEAM
```
- List workflow states
```
projects
```
- List projects
```
cycles --team TEAM
```
- List cycles (
```
--active
```
for current)
```
issues
```
- List issues with filters
```
issue TEAM-123
```
- Get issue details
```
issue TEAM-123 --comments
```
- Get issue details with comments
```
comments TEAM-123
```
- Get comments for an issue
```
search "query"
```
- Search issues
```
inbox
```
- List notifications from your inbox
```
inbox --unread
```
- List only unread notifications

Write Commands

```
create "title" --team TEAM
```
- Create issue
```
update TEAM-123 --state "Done"
```
- Update issue
```
assign TEAM-123 me
```
- Assign issue
```
comment TEAM-123 "comment text"
```
- Add comment
```
start TEAM-123
```
- Move to "In Progress"
```
done TEAM-123
```
- Move to "Done"

Session Commands

```
context
```
- Load session context (use at start)
```
focus TEAM-123 TEAM-456
```
- Set focus tickets
```
notes "reminder text"
```
- Set session notes
```
session-save "summary"
```
- Save session summary
```
sessions
```
- View session history
```
session-clear --older-than 7
```
- Clear old data

Config Commands

```
init
```
- Initialize configuration
```
config
```
- Show current config
```
cache-refresh
```
- Refresh teams/users/states cache
```
cache-status
```
- Show cache status

Issue Filtering

The

issues

command supports flexible filtering with multiple values for most parameters.

Available Filter Options

Option	Alias	Description	Multiple Values
`--team`	`-t`	Filter by team key or ID	No
`--project`	`-p`	Filter by project ID(s)	Yes (comma-separated)
`--cycle`	`-c`	Filter by cycle ID	No
`--assignee`	`-a`	Filter by assignee (ID, email, or "me")	No
`--state`	`-s`	Filter by state name(s)	Yes (repeat flag or comma)
`--priority`	`-P`	Filter by priority (1-4 or names)	Yes (repeat flag or comma)
`--label`	`-L`	Filter by label name(s)	Yes (repeat flag)
`--limit`	`-l`	Maximum issues to return (default: 50)	No

Priority Values

Value	Name	Meaning
1	urgent	Hot fix to production
2	high	Critical for current release
3	medium	Standard priority
4	low	Nice-to-have
0	none	Not yet prioritized

Filtering Examples

# Basic filters
npx linear-skill issues --team TEAM
npx linear-skill issues --assignee me
npx linear-skill issues --state "To Do"

# Priority filtering (CRITICAL for hotfix workflow)
npx linear-skill issues --team TEAM --priority 1              # Urgent only
npx linear-skill issues --team TEAM --priority urgent         # Same as above
npx linear-skill issues --team TEAM --priority 1,2            # Urgent and High
npx linear-skill issues --team TEAM -P urgent -P high         # Same as above

# Multiple states
npx linear-skill issues --team TEAM -s "To Do" -s "In Progress"
npx linear-skill issues --state "Triage,Client Review"        # Comma syntax

# Label filtering (matches issues with ANY of the labels)
npx linear-skill issues --team TEAM --label "Bug"
npx linear-skill issues --team TEAM -L "Bug" -L "Feature"

# Combined filters
npx linear-skill issues --team TEAM --priority 1 --state "To Do"
npx linear-skill issues --team TEAM --assignee me --priority 1,2 --limit 20

# Find all inbox items (Triage + Client Review)
npx linear-skill issues --team TEAM -s "Triage" -s "Client Review"

# Production hotfix query
npx linear-skill issues --team TEAM --priority urgent --state "To Do"

Bulk Operations for Transcript Processing

When creating multiple issues from a meeting transcript:

# Create each ticket with Client Review status
npx linear-skill create "Ticket title" --team TEAM --state "Client Review" --priority 2 -d "Description here"

# After client reviews, they move approved tickets to To Do
npx linear-skill update TEAM-123 --state "To Do"

Setup

Copy
```
.env.example
```
to
```
.env
```
Add your Linear API key:
```
LINEAR_API_KEY=lin_api_xxxx
```
Copy
```
config.example.json
```
to
```
config.json
```
Set your default team in
```
config.json
```
Run
```
npm install && npm run build
```
Test:
```
npx linear-skill teams
```

Skill Initialization

If this skill has not been configured for the current project, help the user set it up:

Check if initialized

npx linear-skill config

team

is "YOUR_TEAM_KEY" or missing, initialization is needed.

Initialization steps

Verify
```
.env
```
has
```
LINEAR_API_KEY
```
set

Discover workspace:

npx linear-skill teams      # Get team key
npx linear-skill projects   # Get project IDs and names
npx linear-skill states --team TEAM_KEY  # Check workflow states

Ask the user:
- Which team to use as default?
- How to categorize their projects (support, feature phases)?
- What does "High priority" mean for their current work?
- What is their current project phase?
Update
```
config.json
```
with discovered values
Check for missing workflow states (Client Review, Dev Done, Ready to Test) and guide user to create them in Linear UI

Refresh cache:

npx linear-skill cache-refresh

Documentation

README.md - Developer setup guide
REFERENCE.md - Full command reference
CONFIG.md - Configuration guide
SESSION.md - Session memory details