Skip to content
Skills Library
Programming · Tool integration

Linear SDK Usage

/Linear SDK Usage

This skill should be used when implementing Linear integrations using the official @linear/sdk — creating issues programmatically, advanced fetch/modify patterns, error handling, and type safety. Activates on "linear sdk", "@linear/sdk", "linear client", "linear typescript".

Repository
claude ↗
Licence
MIT
Last repository change
22.10.2026

Assessment and security

90/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when implementing Linear integrations using the official @linear/sdk — creating issues programmatically, advanced fetch/modify patterns, error handling, and type safety. Activates on "linear sdk", "@linear/sdk", "linear client", "linear typescript".

Triggers from the description

linear sdk@linear/sdklinear clientlinear typescript
Original author description

This skill should be used when implementing Linear integrations using the official @linear/sdk — creating issues programmatically, advanced fetch/modify patterns, error handling, and type safety. Activates on "linear sdk", "@linear/sdk", "linear client", "linear typescript".

How it works

  1. Initialisation
  2. Fetching with lazy connections
  3. Mutations
  4. Errors
  5. Pagination helper
  6. Creating issues with linear.new
Original SKILL.md headings · 72 lines, 285 words
SKILL.md preview
---
name: Linear SDK Usage
description: This skill should be used when implementing Linear integrations using the official @linear/sdk — creating issues programmatically, advanced fetch/modify patterns, error handling, and type safety. Activates on "linear sdk", "@linear/sdk", "linear client", "linear typescript".
version: 1.0.0
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# Linear SDK (@linear/sdk)

References:
- SDK overview: https://linear.app/developers/sdk
- Advanced usage: https://linear.app/developers/advanced-usage
- Fetch / modify: https://linear.app/developers/sdk-fetching-and-modifying-data
- Errors: https://linear.app/developers/sdk-errors
- Create issues with `linearCreate`: https://linear.app/developers/create-issues-using-linear-new

## Initialisation
```ts
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });
```
For OAuth:
```ts
const client = new LinearClient({ accessToken: token });
```
For actor mode:
```ts
const client = new LinearClient({
  accessToken: token,
  // Attribution is set by `actor=app` at authorize time, not per call
});
```

## Fetching with lazy connections
The SDK returns `LinearFetch<T>` — promises that auto-resolve nested connections:
```ts
const team = await client.team("ENG");
const issues = await team.issues({ first: 50 });
for (const issue of issues.nodes) {
  const assignee = await issue.assignee;  // lazy fetch — second round-trip
}
```
**Pitfall:** lazy access fires N+1 queries. Use `client.issues({ filter, includeArchived: false })` with a GraphQL query that selects nested fields up front (drop into raw GraphQL via `client.client.rawRequest()`).

## Mutations
```ts
const result = await client.createIssue({
  teamId, title, description, priority: 1
});
if (!result.success) throw new Error("Create failed");
const issue = await result.issue;
```

## Errors
The SDK throws typed errors:
- `AuthenticationError` — token bad
- `UserError` — your input invalid (validation)
- `RatelimitedError` — back off; check `headers.get("X-RateLimit-Reset")`
- `NetworkError` — retry with exponential backoff
- `GraphqlError` — server-side; capture `errors[].extensions.code`
- See: https://linear.app/developers/sdk-errors

## Pagination helper
```ts
async function* paginate(query, vars) {
  let cursor;
  do {
    const page = await query({ ...vars, after: cursor });
    yield* page.nodes;
    cursor = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
  } while (cursor);
}
```
Used by `lib/pagination.ts`.

## Creating issues with linear.new
For UI-mediated creation (deep-link), see https://linear.app/developers/create-issues-using-linear-new — useful for triage flows that need user input.

Versions

The database has no other skills named Linear SDK Usage.

Database snapshot: 13.11.2026 · package version 1bc6d8781797 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100linear-sdk-patterns
    TypeScript/JavaScript SDK patterns and best practices for Linear. Use when learning SDK idioms, implementing common patterns, or optimizing Linear API usage. Trigger with phrases like "linear SDK patterns", "linear best practices", "linear typescript", "linear API patterns", "linear SDK idioms".
  • 100linear-sdk-patterns
    Implement current Linear TypeScript SDK query, mutation, pagination, raw GraphQL, and error-handling patterns. Use when building or refactoring a typed Linear adapter. Trigger with "use Linear SDK", "refactor Linear client", or "write typed Linear GraphQL".
  • 100linear-install-auth
    Install and configure Linear SDK/CLI authentication. Use when setting up a new Linear integration, configuring API keys, or initializing Linear in your project. Trigger with phrases like "install linear", "setup linear", "linear auth", "configure linear API key", "linear SDK setup".
  • 100linear-sdk-scripting
    Perform actions in Linear (read, create, update, search issues, projects, comments, teams, cycles, labels, etc.) by writing and running small Node scripts against the official @linear/sdk TypeScript SDK with a personal API key. Use this when the user wants to do Linear work from…
  • 100linear-core-workflow-a
    Implement a controlled Linear issue lifecycle from discovery through create, update, relation, comment, and archive actions. Use when automating issue operations with the GraphQL API or TypeScript SDK. Trigger with "automate Linear issues", "build an issue workflow", or "update Linear issue states".
  • 100claude-agent-sdk
    This skill should be used when developing applications with the Claude Agent SDK, answering questions about SDK features and APIs, implementing SDK patterns, or troubleshooting SDK integration. Covers Python and TypeScript APIs, core features, advanced features, and integrations.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.