linear

What this skill does

# linear

## Purpose
This skill enables the AI to interact with Linear's API for issue tracking, cycle management, project roadmaps, Git integrations, SLA monitoring, and API-driven workflows, specifically for engineering teams.

## When to Use
Use this skill when automating engineering workflows, such as creating issues from code changes, updating project roadmaps, tracking SLAs for tickets, or syncing Git commits with Linear issues. Apply it in scenarios involving team collaboration, like querying issues during sprint planning or integrating with CI/CD pipelines.

## Key Capabilities
- **Issue Management**: Create, update, and query issues using Linear's GraphQL API at https://api.linear.app/graphql.
- **Cycle and Project Handling**: Manage cycles via mutations like `cycleCreate` and projects with queries for roadmaps.
- **Git Integration**: Link Git commits to issues using webhooks or API; for example, associate a commit SHA with an issue ID.
- **SLA Tracking**: Monitor service level agreements by querying issue states and timestamps.
- **API Access**: Authenticate with a personal API key and perform operations like fetching issues with filters (e.g., state: "todo").
- **Config Formats**: Store API keys in environment variables like `$LINEAR_API_KEY`; use JSON for payload structures in requests.

## Usage Patterns
To accomplish tasks, always authenticate first by setting `$LINEAR_API_KEY` in your environment. For querying data, use GraphQL queries; for mutations, provide input objects. Pattern for issue creation: Authenticate → Prepare mutation payload → Send request → Handle response. For integrations, combine with Git tools by parsing commit messages and mapping to Linear issues. Always validate inputs, like ensuring issue titles are under 255 characters, before sending requests.

## Common Commands/API
- **Query Issues**: Use this GraphQL query to fetch open issues:
  ```
  query { issues(filter: { state: { name: { eq: "todo" } } }) { nodes { id title } } }
  ```
  Send via curl: `curl -H "Authorization: Bearer $LINEAR_API_KEY" -X POST https://api.linear.app/graphql -d '{"query": "above query"}'`
- **Create an Issue**: Execute this mutation to add a new issue:
  ```
  mutation { issueCreate(input: { title: "Fix bug in login", description: "Details here" }) { issue { id } } }
  ```
  Command: `curl -H "Authorization: Bearer $LINEAR_API_KEY" -X POST https://api.linear.app/graphql -d '{"query": "above mutation"}'`
- **Update Project Roadmap**: Query projects first, then mutate: `mutation { projectUpdate(id: "proj_123", name: "Updated Roadmap") { project { id } } }`
- **Git Integration Command**: To link a Git commit, use: `git log --format="%H %s" | awk '{print $1}' | xargs -I {} curl -H "Authorization: Bearer $LINEAR_API_KEY" -X POST https://api.linear.app/graphql -d '{"query": "mutation { issueUpdate(id: \"iss_456\", branch: \"{}\") { issue { id } } }"}'`
- **SLA Check**: Query: `query { issues(filter: { createdAt: { gt: "2023-01-01" } }) { nodes { id slaViolated } } }`

## Integration Notes
Set up authentication by exporting `$LINEAR_API_KEY` from your Linear account settings. For Git integration, configure webhooks in Linear to trigger on issue updates and parse payloads in scripts (e.g., using Python's requests library). Config format: Use a .env file with `LINEAR_API_KEY=your_key_here`, then load it in scripts via `os.environ.get('LINEAR_API_KEY')`. To integrate with other tools, chain API calls; for example, after a Git push, run a script that queries Linear issues and updates them. Ensure rate limits (e.g., 100 requests/min) are respected by adding delays in loops.

## Error Handling
Check for authentication errors (e.g., 401 status) by verifying `$LINEAR_API_KEY` before requests; if failed, prompt user to set the env var. For GraphQL errors, parse the "errors" field in responses (e.g., if "message" contains "Invalid input", validate payloads like ensuring required fields are present). Handle network issues with retries: Use a loop with exponential backoff, like `for i in 1..3; do curl ...; if [ $? -ne 0 ]; then sleep $((2**i)); fi; done`. For SLA violations, catch query errors by checking if issues return null values and log them. Always wrap API calls in try-catch blocks in code, e.g.:
  ```
  try { response = requests.post('https://api.linear.app/graphql', headers={'Authorization': f'Bearer {os.environ["LINEAR_API_KEY"]}'}, json={'query': '...'}) } catch e { print(f'Error: {e}') }
  ```

## Concrete Usage Examples
1. **Automate Issue Creation from Code Review**: When a pull request is opened in GitHub, use this script to create a Linear issue: Set `$LINEAR_API_KEY`, then run `curl -H "Authorization: Bearer $LINEAR_API_KEY" -X POST https://api.linear.app/graphql -d '{"query": "mutation { issueCreate(input: { title: \"Review PR #123\", description: \"Fixes in branch main\" }) { issue { id } } }"}'`. This links the PR to a new issue for tracking.
2. **Track SLA for Overdue Issues**: Query and notify on SLA breaches: First, export `$LINEAR_API_KEY`, then execute `curl -H "Authorization: Bearer $LINEAR_API_KEY" -X POST https://api.linear.app/graphql -d '{"query": "query { issues(filter: { slaViolated: true }) { nodes { id title } } }"}' | jq '.data.issues.nodes' > overdue_issues.json`. Process the JSON to send alerts, ensuring issues older than 48 hours are flagged.

## Graph Relationships
- Related to: "git" (for commit integrations), "issues" (for tracking workflows), "engineering" (for team management), "project" (for roadmap syncing).
- Connections: This skill can chain with "git" skills via API calls for automated linking; integrates with "engineering" for broader tool ecosystems.