linear
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill linearRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/linearInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/linear/ - All projects
~/.claude/skills/linear/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExpert Linear issue tracking assistance covering cycles, projects, triage, keyboard-first workflows, and GraphQL API integration. Use when managing fast software development workflows and bug tracking.
Linear
Linear is a streamlined, keyboard-first issue tracking and project management platform designed for high-velocity software engineering teams.
When to Use
- High-Velocity Issue Tracking for Engineering Teams: Fast, keyboard-first issue tracking and project management.
- Cycles & Project Roadmapping: Planning 2-week engineering cycles, tracking velocity, and milestones.
- GitHub & GitLab PR Synchronization: Automatically moving issues to In Progress on branch creation and Done on PR merge.
- Linear GraphQL API Automation: Automating issue creation, triage bots, and metrics collection via GraphQL.
Quick Start
# Query Linear GraphQL API for assigned issues
curl -X POST https://api.linear.app/graphql \
-H "Authorization: $LINEAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "{ viewer { assignedIssues(filter: { state: { type: { eq: \"started\" } } }) { nodes { id identifier title } } } }"}'
Core Concepts
Linear GraphQL API Integration with Python
Querying and creating issues programmatically:
import requests
import os
LINEAR_API_URL = "https://api.linear.app/graphql"
API_KEY = os.environ["LINEAR_API_KEY"]
headers = {
"Authorization": API_KEY,
"Content-Type": "application/json"
}
# GraphQL Mutation to create an engineering issue
create_issue_mutation = '''
mutation CreateIssue($teamId: String!, $title: String!, $description: String!) {
issueCreate(input: {
teamId: $teamId
title: $title
description: $description
priority: 1 # Urgent
}) {
success
issue {
id
identifier
url
}
}
}
'''
variables = {
"teamId": "TEAM_UUID_HERE",
"title": "Investigate elevated latency on payment webhook worker",
"description": "P99 latency spiked above 1200ms following deployment v2026.1.0."
}
res = requests.post(LINEAR_API_URL, json={"query": create_issue_mutation, "variables": variables}, headers=headers)
print("Created Issue:", res.json())
Git Branch & PR Automation Rules
Linking code to Linear issues automatically:
# Branch naming convention: <username>/<issue-identifier>-<description>
git checkout -b alice/eng-402-checkout-rate-limit
# Commit message linking
git commit -m "fix(checkout): enforce rate limiting on token endpoint (Fixes ENG-402)"
Linear automatically moves ENG-402 to:
- In Progress when the branch is pushed.
- In Review when a Pull Request is opened.
- Done when the Pull Request is merged into
main.
Essential Keyboard Shortcuts
Operating Linear with speed:
C: Create new issue.Cmd + K: Open Command Menu.S: Change issue state (Todo, In Progress, Done).P: Change priority (Urgent, High, Medium, Low).A: Assign issue to team member.
Common Patterns
Automated Issue Creation via GraphQL API
Problem: Creating Linear tickets automatically from CI/CD alert hooks.
Solution: Execute Linear GraphQL mutation via curl or script.
curl -X POST "https://api.linear.app/graphql" \
-H "Authorization: $LINEAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "mutation IssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id title url } } }",
"variables": {
"input": {
"teamId": "TEAM_UUID",
"title": "Bug: Production CPU Spike",
"description": "CPU exceeded 90% on api-gateway-pod-3."
}
}
}'
Best Practices
Do:
- Name Git branches using the Linear issue identifier (
eng-102-fix-auth) to enable automated status synchronization. - Use Linear's Triage inbox to review and accept incoming bugs and feature requests before backlog addition.
- Set issue estimates (points or t-shirt sizes) to track team velocity across cycles.
- Use the Linear GraphQL API for automated triage bots and Slack integrations.
Don't:
- Leave completed issues un-merged or open; link pull requests so status updates automatically.
- Create massive multi-month tickets; break large epics into distinct sub-issues.
- Commit
LINEAR_API_KEYto public repositories.
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
GraphQL error: 401 Unauthorized | Invalid LINEAR_API_KEY or missing scopes. | Generate API key in Linear Settings > API > Personal API Keys. |
GitHub integration not updating issues | Webhook disconnected or repository not linked in Linear integration settings. | Re-authenticate GitHub integration in Linear Settings > Integrations. |
Cycle burndown chart not updating | Issues added to cycle without estimate story points. | Assign points/estimates to issues in cycle backlog. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill