Linear Claude Skill
Manage Linear issues, projects, and teams directly from Claude Code — with MCP, SDK automation, and GraphQL fallbacks for creating issues, syncing status, and attaching files.
SKILL.md explicitly warns against exposing LINEAR_API_KEY, lists safe/unsafe commands, recommends varlock masked injection, MIT license, no malicious indicators; however allowed-tools grants full Bash, write operations (create/update/bulk sync) need no explicit user confirmation, and there is no rollback mechanism — deducted.
Docs are self-consistent with layered fallbacks (MCP→CLI→scripts→SDK→GraphQL), setup diagnostics, dry-run, --strict flags and clear failure feedback; but static review only, smoke tests merely declared without full key-path test evidence visible, capped at 10.
Trigger conditions (Linear issues, projects, team workflows) are clear in the description with rich scenarios and known-pitfall tables; boundaries/non-fit ranges are not declared, core function fully depends on Linear cloud plus npm/brew (overseas) reachability, questionable from mainland China, no Chinese support noted — deducted.
Well-layered docs (api/sdk/sync/projects/troubleshooting/labels), version 3.4.1 aligned with CHANGELOG and semantic-release, MIT license, recent maintenance activity; but publisher identity unverified and maintenance/update responsibility only implicit in a personal repo — deducted.
Claims full issue/project/team coverage with templates, validation, bulk import and dry-run, likely better than manual GraphQL; but output correctness unverifiable statically, and the changelog shows contradictory MCP reliability claims (previously ~50% failure, later high) — capped at 7, minus 1.
CHANGELOG links to commits/issues, package-lock pins dependencies, CI and smoke tests declared — auditable primary material; but no execution reproduction, unknown test coverage, no third-party corroboration, capped at 5.
- Core function depends entirely on Linear cloud and overseas channels (npm, brew); may be unreachable from mainland China networks.
- allowed-tools grants full Bash; bulk write operations default to no user confirmation — review sensitive changes manually.
- MCP reliability claims are contradictory across versions; verify against official docs before relying on them.
- Publisher unverified, personally maintained repo; long-term maintenance not guaranteed.
What does this skill do, and when should you use it?
This is a Claude Code skill that turns Linear project management into a reusable operating playbook: creating issues, updating status, managing projects and initiatives. It prefers the official Linear MCP server, falls back to the Linear CLI or @linear/sdk scripts when MCP is unavailable, and uses direct GraphQL only as a last resort. It enforces a required issue template with acceptance criteria, a domain-based label taxonomy, and a discovery-before-creation planning workflow. Advanced features include varlock secret masking, image extraction and upload, bulk import from manifests, and parallel subagent sync.
Reads Linear workspace data (issues, projects, teams, initiatives); creates and updates issues, sets parent-child relationships, bulk-updates status, changes project state, and links initiatives via MCP, npm run ops CLI commands, @linear/sdk, or GraphQL; enforces a six-section description template with pre-flight validation via validate-description; applies a 25-label, three-category taxonomy with validation and suggestions; extracts inline images from session JSONL and uploads them to Linear's S3 as issue attachments; bulk-imports issues with media from a manifest directory via bulk-create.ts; runs npm run setup for environment self-checks.
- A developer managing a Linear workspace in Claude Code who wants to create issues and change status without leaving the conversation
- A team lead planning a new phase who wants to create the project and all its issues in one session for traceability
- A team importing customer feedback or retro action items in bulk with screenshots or recordings attached
- Teams already using MCP tools who want CLI/SDK fallback paths for reliability
- Engineering orgs that want every issue to carry acceptance criteria and consistent labels for agent routing and auditing
What are this skill's strengths and limitations?
- Multi-backend resilience: MCP, CLI, SDK, GraphQL degrade gracefully, so missing MCP never blocks work
- Enforced six-section issue template with acceptance-criteria validation raises ticket quality
- Thoughtful security: varlock masks the API key, with explicit never-run leak commands
- Covers long-tail needs: bulk import, image extraction/upload, parallel subagent sync, post-edit hook
- esbuild pre-compilation gives ~18x faster CLI startup, backed by smoke tests
- Tightly coupled to the Claude Code ecosystem (allowed-tools, Linear-specialist subagent, hooks); porting to other clients requires rework
- Heavy dependency surface: Node.js, @linear/sdk, MCP server, plus optional lin CLI and varlock
- MCP-path template enforcement is instruction-only with no server-side gate; relies on retrospective lint-issues audits
- Documentation reflects one author's real-world workflow; lacks independent cross-platform testing evidence
How do you install this skill?
Requires Node.js >= 20.11.0 and a Linear personal API key (Settings → Security & access → Personal API keys, starts with lin_api_). Install: git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear && cd ~/.claude/skills/linear && npm install. Recommended MCP config for the official server: {"mcpServers":{"linear":{"command":"npx","args":["mcp-remote","https://mcp.linear.app/sse"],"env":{"LINEAR_API_KEY":"your_api_key"}}}}. Optionally run npm run build for esbuild pre-compilation (~18x faster cold start). Optional: install the lin CLI (brew install aaronkwhite/tap/lin or cargo install lincli) to speed up read operations.
How do you use this skill?
Run npm run setup first, then verify with npm run query -- "query { viewer { name } }". In Claude Code, simply prompt e.g. "Create a high priority issue titled 'Fix auth bug' in the ENG team", or use the CLI: npm run ops -- create-issue "Project" "Title" "Description"; npm run ops -- status Done ENG-123; npm run ops -- project-status "Phase 1" completed; npm run ops -- help lists all commands. Issue creation via CLI hard-rejects descriptions missing the Acceptance Criteria template.
How does this skill compare with similar options?
The source explicitly compares Linear's official MCP server (mcp.linear.app) against deprecated community servers (e.g. linear-mcp-server on npm, jerhadf/linear-mcp-server on GitHub) and strongly recommends the official server for reliability. It also positions the optional lin Rust CLI as a fast-path for reads, silently falling back to the SDK when unavailable.