Manage Linear Projects and Issues

Provides tools and workflows for managing issues, projects, and teams in Linear, supporting multiple tool backends - the official MCP server, the Linear CLI, or helper/SDK scripts - and falling back gracefully between them rather than treating a missing backend as a blocker.

Use this skill when managing Linear issues, projects, and teams - creating/updating issues, tracking project state, linking projects to initiatives, or bulk-syncing code changes to Linear. If MCP tools aren't available, the Linear CLI via Bash is always usable instead (linear issues view, create, update, comment add, list) - this should never be reported as a blocker.

Security is handled via Varlock integration: never expose LINEAR_API_KEY in terminal output or Claude's context - use varlock load (masked output) to validate the key is set and varlock run -- to inject secrets into commands, never linear config show, echo $LINEAR_API_KEY, printenv, or cat .env directly. New projects define the key in .env.schema with an @sensitive annotation and configure the MCP server to reference it via ${LINEAR_API_KEY}.

First-time setup runs npx tsx ~/.claude/skills/linear/scripts/setup.ts to check the API key, SDK installation, CLI availability, and MCP configuration, obtaining a lin_api_-prefixed key from Linear's Settings > Security & access > Personal API keys if missing, then verifying connectivity with a test GraphQL query.

The project planning workflow is opinionated: create the project first, set its state to planned, create issues directly inside it (never in a catch-all project moved later), then update state to in-progress when work begins - this preserves traceability, accurate progress metrics, and correctly working Linear views/filters. Project state commands (project-status) accept human-friendly terms mapped to Linear's API states: backlog, planned, in-progress (maps to started), paused, completed, canceled - with partial project-name matching supported. Initiative linking/unlinking (link-initiative, unlink-initiative) connects projects to initiatives, returning errors if the link or entities don't exist.

Tool selection guidance: prefer the official MCP server (mcp.linear.app, never deprecated community servers) for most operations; use helper/SDK scripts (@linear/sdk in TypeScript) for bulk operations, loops, or conditionals MCP doesn't support well; fall back to the raw GraphQL API only for operations neither MCP nor SDK covers. For 3+ issue bulk operations, project status changes, or multi-issue creation, delegate to a Linear-specialist subagent for parallel execution rather than sequential direct calls.

A hard structural requirement: every issue must be attached to a project, and every project must be linked to an initiative, or it won't appear in the project board/roadmap respectively. Labeling follows a domain-based taxonomy: exactly one Type label (feature, bug, refactor, chore, spike), 1-2 Domain labels (security, backend, frontend), and scope labels where applicable (blocked, breaking-change, tech-debt), validated via labels validate and suggested via labels suggest.

Built on the official Linear MCP server, the Linear CLI, the @linear/sdk TypeScript package, and Linear's GraphQL API as a fallback - with companion reference docs (api.md, sdk.md, sync.md, projects.md, troubleshooting.md, docs/labels.md) covering each layer in depth.

Teams managing Linear issues, projects, and initiatives through Claude Code who need secure API key handling, a consistent issue-to-project-to-initiative structure, and the right tool (MCP, CLI, SDK, or GraphQL) chosen per operation rather than defaulting to one backend regardless of fit.