---
slug: "linear-skills"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/conorluddy/linear-skills@main/README.md"
repo: "https://github.com/conorluddy/linear-skills"
source_file: "README.md"
branch: "main"
---
# Linear Get Issue Skill

A lightweight Claude Code skill for fetching Linear issue details without the context overhead of the full Linear MCP.

## Why This Over the Full Linear MCP?

**This skill:** Read-only issue lookup (search + get details)
- ✅ Minimal context usage
- ✅ Fast issue retrieval
- ✅ Perfect for "what's the status of X?" queries
- ✅ Zero external dependencies

**Official Linear MCP:** Full read/write operations
- For creating issues, updating status, adding comments
- For complex workflows that modify issues
- When you need your agent to take hands-on action

**The smart workflow:**
1. Use this skill to **read/search** issues (lightweight)
2. Use Linear MCP when you need to **create/modify** issues (when needed)

## Quick Start

### 1. No Dependencies to Install!

This skill uses only Python's built-in stdlib (urllib, json, argparse). Nothing to install.

### 2. Set Up Your Linear API Key

Copy the example `.env` file from the skill directory and add your API key:

```bash
cp .claude/skills/linear-skills/.env.example .claude/skills/linear-skills/.env
```

Then edit `.claude/skills/linear-skills/.env` and add your Linear API key:
```
LINEAR_API_KEY=your_api_key_here
```

**Note:** The script checks for `.env` in this order:
1. `.claude/skills/linear-skills/.env` (preferred - skill-specific)
2. Project root `.env` (for shared config)
3. Current working directory (fallback)

**Getting your API key:**
1. Go to your Linear workspace
2. Settings > API
3. Create a Personal API Key
4. Copy and paste into `.env`

### 3. Test It Works

```bash
python scripts/get_issue.py ENG-123
```

You should see the issue details printed out.

### 4. Install as Claude Code Skill

Option A: Copy to Claude Code skills directory
```bash
mkdir -p ~/.claude/skills
cp -r .claude/skills/linear-skills ~/.claude/skills/
```

Option B: Use directory directly (if Claude Code recognizes the path)
```bash
# Point Claude Code settings to this project's .claude/skills folder
```

Once installed, you can ask Claude Code: "Get issue ENG-123" and it will automatically fetch the details.

## Usage

### Search for Issues

```bash
# Find issues by keyword
python scripts/search_issues.py "filtering"
python scripts/search_issues.py "bug"

# Limit results
python scripts/search_issues.py "exercise" --limit 5

# Get JSON output
python scripts/search_issues.py "filtering" --json
```

### Get Full Issue Details

```bash
# Fetch issue (pretty output)
python scripts/get_issue.py LUDDY-320

# Get JSON output
python scripts/get_issue.py LUDDY-320 --json

# Parse specific field
python scripts/get_issue.py LUDDY-320 --json | jq '.description'
```

### With Claude Code

Claude Code can invoke both scripts automatically. Examples:

**Search first:**
- "Find all filtering-related issues"
- "Search for exercise bugs"

**Then get details:**
- "Get issue LUDDY-320"
- "Show me full details of LUDDY-321"
- "What's in LUDDY-323?"

Claude Code will invoke the appropriate script automatically.

## Output

### Pretty (Default)

```
ENG-123: Fix login bug
Status: In Progress
Priority: High
Assignee: John Doe (john@example.com)
Team: Engineering
Labels: bug, p1

Description:
Users unable to login with SSO on mobile Safari. Started after
the recent auth middleware update.

URL: https://linear.app/workspace/issue/ENG-123/...
Created: 2024-12-15T10:30:00
Updated: 2024-12-16T14:22:00
```

### JSON

```json
{
  "id": "issue_uuid",
  "identifier": "ENG-123",
  "title": "Fix login bug",
  "description": "Users unable to login...",
  "state": {
    "name": "In Progress",
    "type": "started"
  },
  "priority": "High",
  "assignee": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "team": {
    "name": "Engineering",
    "key": "ENG"
  },
  "labels": [
    {"name": "bug", "color": "#ff0000"}
  ],
  "url": "https://linear.app/...",
  "created_at": "2024-12-15T10:30:00",
  "updated_at": "2024-12-16T14:22:00"
}
```

## Troubleshooting

### "LINEAR_API_KEY environment variable not set"

Make sure you:
1. Created a `.env` file in the project root
2. Added your API key to it
3. The file is named `.env` (not `.env.example`)

### "Issue 'ENG-123' not found"

Check that:
1. The issue ID is correct
2. You have access to the Linear workspace
3. Your API key is valid

### "linear-sdk not installed"

Run:
```bash
pip install -r requirements.txt
```

## Why This Skill?

The full Linear MCP integration can be context-heavy when you only need simple issue lookups. This skill:

- **Zero Dependencies**: Pure Python stdlib - no npm installs, no package bloat
- **Lightweight**: Direct GraphQL queries vs SDK wrapper overhead
- **Focused**: Does one thing well - fetches issue details
- **Efficient Output**: Concise by default, verbose on demand
- **JSON Support**: Easy to parse and integrate with other tools
- **Context Optimized**: Minimal token usage for simple queries
- **Fast**: No SDK initialization, direct API calls

Perfect for when you just need: "What's the status of ENG-123?" without loading the entire Linear integration.

## Project Structure

```
linear-skills/
├── .claude/
│   └── skills/
│       └── linear-skills/
│           ├── SKILL.md              # Claude Code skill definition
│           ├── .env.example          # API key template
│           └── .env                  # ⭐ Your API key goes here
├── scripts/
│   └── get_issue.py                  # Main script
├── requirements.txt                  # Python dependencies
└── README.md                         # This file
```

**Note:** Each skill is self-contained in `.claude/skills/`. The `.env` file stays with the skill, not in the project root.

## Requirements

- Python 3.9+
- Linear API key (from workspace Settings > API)
- **Zero external dependencies** - uses only Python stdlib

## CLAUDE.md Configuration

Add this to your `CLAUDE.md` file so Claude Code knows about this skill:

```markdown
## Available Skills

### Linear Get Issue Skill

A lightweight read-only skill for searching and fetching Linear issues without the context overhead of the full Linear MCP.

**When to use this skill:**
- Searching for issues by keyword
- Getting current status/details of an issue
- Quick issue lookups and context gathering
- Reducing context usage compared to full Linear MCP

**When to use the official Linear MCP instead:**
- Creating new issues
- Updating issue status, assignees, or labels
- Adding comments or making changes
- Complex workflows that require write access

**Available tools:**
- `search_issues.py` - Find issues by keyword
- `get_issue.py` - Get full details of an issue

**Setup:**
- Located at: `.claude/skills/linear-skills/`
- Requires: Linear API key in `.env` file
- No other dependencies needed
```

## Future Enhancements

Potential improvements (not in initial build):
- Bulk fetch multiple issues
- Filter by status, assignee, team
- Cache responses locally
- Add relationship exploration (linked issues, dependencies)
- Project/workspace filtering

## License

MIT