Skip to content

alivirgo/Major-AI-Skills / plugins/mas-design-knowledge/skills/linear

linear

Verified

Manage Linear issues, projects, cycles, and labels through GraphQL and webhook-driven workflows.

Linear Product Issue Tracking AI Skill Guide (Claude)

Overview & Engine Architecture

Linear is a high-speed issue tracker for product/engineering teams with Issues, Projects, Cycles, Initiatives, and Workflow states. Automation uses the Linear GraphQL API, personal API keys / OAuth, and webhooks. Claude operates as a Principal Product Operations Engineer, specializing in issue triage mutations, project roadmap queries, label taxonomies, and idempotent webhook handlers.

Linear Domain & API Stack

┌─────────────────────────────────────────────────────────────┐
│                 Linear Architecture                         │
│                                                             │
│  Product Objects                                            │
│  ├── Teams / Members / Workflow States                      │
│  ├── Issues / Labels / Comments / Attachments               │
│  └── Projects / Cycles / Initiatives                        │
│                                                             │
│  API                                                        │
│  ├── GraphQL endpoint https://api.linear.app/graphql        │
│  ├── API Key (Authorization: <key>)                         │
│  └── Webhooks (issue create/update, comments, ...)          │
│                                                             │
│  Client Surfaces                                            │
│  ├── Desktop / Web / Mobile                                 │
│  ├── Slack / GitHub integrations                            │
│  └── @linear/sdk                                            │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

  1. Team-Scoped Writes: Always resolve teamId before issueCreate.
  2. State by Type: Prefer state IDs/types (started, completed) over hard-coded names when possible.
  3. Idempotent Imports: Key off external IDs in description/attachments or custom fields patterns.
  4. Rate Limits: Batch thoughtfully; prefer GraphQL selection sets that fetch only needed fields.
  5. Webhook Verification: Validate signatures when Linear provides signing secrets.

Production TypeScript: Create Issue + Query Cycle Load

// ==============================================================================
// Linear GraphQL: create issue and list active cycle issues
// npm i @linear/sdk
// ==============================================================================
import { LinearClient } from "@linear/sdk";

const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

async function createBug(title: string, description: string, teamKey: string) {
  const teams = await linear.teams({ filter: { key: { eq: teamKey } } });
  const team = teams.nodes[0];
  if (!team) throw new Error(`Team not found: ${teamKey}`);

  const payload = await linear.createIssue({
    teamId: team.id,
    title,
    description,
    priority: 2, // High
  });

  const issue = await payload.issue;
  if (!issue) throw new Error("Issue creation failed");
  return issue.identifier; // e.g. ENG-123
}

async function activeCycleSummary(teamKey: string) {
  const teams = await linear.teams({ filter: { key: { eq: teamKey } } });
  const team = teams.nodes[0];
  if (!team) throw new Error(`Team not found: ${teamKey}`);

  const cycles = await team.cycles({ filter: { isActive: { eq: true } } });
  const cycle = cycles.nodes[0];
  if (!cycle) return { cycle: null, issues: [] as string[] };

  const issues = await cycle.issues();
  return {
    cycle: cycle.name,
    issues: issues.nodes.map((i) => `${i.identifier} ${i.title}`),
  };
}

createBug("Checkout 500 on promo codes", "Repro steps...", "ENG").then(console.log);

Raw GraphQL alternative:

mutation IssueCreate($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { id identifier url }
  }
}

Technical Troubleshooting Matrix

Issue & Failure SignatureRoot Cause AnalysisDiagnostic & Resolution Pathway
UnauthorizedBad/revoked API key.Regenerate key; check header format.
Team not foundWrong key / private team.List teams via API; confirm membership.
State transition rejectedIllegal workflow move.Query team states; move via allowed edges.
Webhook duplicatesAt-least-once delivery.Dedupe on action + issue id + updatedAt.

Best Practices

  1. Encode triage rules as labels + templates, not tribal knowledge.
  2. Link PRs via Linear<>GitHub integration rather than pasting only URLs.
  3. Keep priority taxonomy small and consistent (Urgent/High/Medium/Low).

Essential References

  • GraphQL: https://api.linear.app/graphql
  • SDK: @linear/sdk
  • Auth header: Authorization: <LINEAR_API_KEY>

Agent Operational Directive

MANDATORY: Resolve team IDs before creating issues. Prefer SDK/GraphQL typed inputs over scraping the UI. Make webhook consumers idempotent.

planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall