A lightweight Claude Code skill for fetching Linear issue details without the context overhead of 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)

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

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

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

python scripts/get_issue.py ENG-123

You should see the issue details printed out.

Option A: Copy to Claude Code skills directory

mkdir -p ~/.claude/skills
cp -r .claude/skills/linear-skills ~/.claude/skills/

Option B: Use directory directly (if Claude Code recognizes the path)

# 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.

# 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

# 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'

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.

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

{
  "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"
}

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)

Check that:

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

Run:

pip install -r requirements.txt

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.

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.

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

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

## 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

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

MIT