Linear
Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/wrsmith108--linear-claude-skill)HTML
<a href="/listings/wrsmith108--linear-claude-skill"><img src="/api/listings/wrsmith108--linear-claude-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Install the Skill
git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear cd ~/.claude/skills/linear && npm install
2. Run Setup Check
npm run setup
This checks your configuration and tells you exactly what's missing.
3. Get Your API Key (If Needed)
1. Open [Linear](https://linear.app) in your browser 2. Go to **Settings** → **Security & access** → **Personal API keys** 3. Click **Create key** and copy it (starts with `lin_api_`) 4. Add to your environment:
# Add to shell profile echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc source ~/.zshrc
4. Verify It Works
npm run ops -- whoami
You should see your name and organization.
5. Build for Faster Startup (Optional)
npm run build
Pre-compiles TypeScript to JavaScript for ~18x faster CLI cold starts. Without building, commands still work via tsx (slower but functional).
6. Start Using It
# Create an initiative npm run ops -- create-initiative "My Project" # Create a project npm run ops -- create-project "Phase 1" "My Project" # Create a sub-issue under a parent npm run ops -- create-sub-issue ENG-100 "Add tests" "Unit tests for feature" # Set parent-child relationships for existing issues npm run ops -- set-parent ENG-100 ENG-101 ENG-102 # Update issue status npm run ops -- status Done ENG-123 ENG-124 # See all commands npm run ops -- help
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 726 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: Linear
- description: Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.
- version: 3.4.1
- author: Ryan Smith <ryan@smithhorn.ca>
- tags:
- - linear
- - issue-tracking
- - project-management
- - mcp
- - graphql
- - workflow
- allowed-tools:
- - mcp__linear
- - WebFetch(domain:linear.app)
- - Bash
- ---
- # Linear
- Tools and workflows for managing issues, projects, and teams in Linear.
- ---
- ## ⚠️ Tool Availability (READ FIRST)
- **This skill supports multiple tool backends. Use whichever is available:**
- 1. **MCP Tools (mcp__linear)** - Use if available in your tool set
- 2. **Linear CLI (`linear` command)** - Always available via Bash
- 3. **Helper Scripts** - For complex operations
- **If MCP tools are NOT available**, use the Linear CLI via Bash:
- ```bash
- # View an issue
- linear issues view ENG-123
- # Create an issue
- linear issues create --title "Issue title" --description "Description"
- # Update issue status (get state IDs first)
- linear issues update ENG-123 -s "STATE_ID"
- # Add a comment
- linear issues comment add ENG-123 -m "Comment text"
- # List issues
- linear issues list
- ```
- **Do NOT report "MCP tools not available" as a blocker** - use CLI instead.
- ---
- ## 🔐 Security: Varlock Integration
- **CRITICAL**: Never expose API keys in terminal output or Claude's context.
- ### Safe Commands (Always Use)
- ```bash
- # Validate LINEAR_API_KEY is set (masked output)
- varlock load 2>&1 | grep LINEAR
- # Run commands with secrets injected
- varlock run -- npm run query -- "query { viewer { name } }"
- # Check schema (safe - no values)
- cat .env.schema | grep LINEAR
- ```
- ### Unsafe Commands (NEVER Use)
- ```bash
- # ❌ NEVER - exposes key to Claude's context
- linear config show
- echo $LINEAR_API_KEY
- printenv | grep LINEAR
- cat .env
- ```
- ### Setup for New Projects
- 1. Create `.env.schema` with `@sensitive` annotation:
- ```bash
- # @type=string(startsWith=lin_api_) @required @sensitive
- LINEAR_API_KEY=
- ```
- 2. Add `LINEAR_API_KEY` to `.env` (never commit this file)
- 3. Configure MCP to use environment variable:
- ```json
- {
- "mcpServers": {
- "linear": {
- "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
- }
- }
- }
- ```
- 4. Use `varlock load` to validate before operations
- ---
- ## Quick Start (First-Time Users)
- ### 1. Check Your Setup
- Run the setup check to verify your configuration:
- ```bash
- npm run setup
- ```
- This will check:
- - LINEAR_API_KEY is set and valid
- - @linear/sdk is installed
- - Linear CLI availability (optional)
- - MCP configuration (optional)
- ### 2. Get API Key (If Needed)
- If setup reports a missing API key:
- 1. Open [Linear](https://linear.app) in your browser
- 2. Go to **Settings** (gear icon) -> **Security & access** -> **Personal API keys**
- 3. Click **Create key** and copy the key (starts with `lin_api_`)
- 4. Add to your environment:
- ```bash
- # Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
- export LINEAR_API_KEY="lin_api_your_key_here"
- # Option B: Add to Claude Code environment
- echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env
- # Then reload your shell or restart Claude Code
- ```
- ### 3. Test Connection
- Verify everything works:
- ```bash
- npm run query -- "query { viewer { name } }"
- ```
- You should see your name from Linear.
- ### 4. Common Operations
- ```bash
- # Create issue in a project
- npm run ops -- create-issue "Project" "Add rate limiting to auth endpoints" "Auth endpoints have no rate limiting, allowing brute-force attacks. Add configurable limits per endpoint with 429 responses when exceeded."
- # Update issue status
- npm run ops -- status Done ENG-123 ENG-124
- # Edit issue title or description (fix typos, expand bodies)
- npm run ops -- update-issue ENG-123 description --file /tmp/description.md --force
- npm run ops -- update-issue ENG-123 title "Corrected title" --force
- echo "New body from pipeline" | npm run ops -- update-issue ENG-123 description --stdin --force
- npm run ops -- update-issue ENG-123 description "Short inline update" --strict=false
- # Create sub-issue
- npm run ops -- create-sub-issue ENG-100 "Sub-task" "Details"
- # Update project status
- npm run ops -- project-status "Phase 1" completed
- # Show all commands
- npm run ops -- help
- ```
- See [Project Management Commands](#project-management-commands) for full reference.
- ---
- ## Issue Creation Checklist (Required)
- **When creating a Linear issue, always complete these three steps — even if the user doesn't mention them.**
- 1. **Detailed description with Acceptance Criteria.** Every issue description MUST include an `## Acceptance Criteria` section with at least 2 concrete, testable checklist items. See [docs/issue-template.md](docs/issue-template.md) for the canonical template plus a populated full example. The CLI `create-issue` / `create-sub-issue` will reject descriptions missing this structure; for MCP `save_issue` callers, validate the draft first with `npm run ops -- validate-description --stdin` (see below). If the user provides only a title, draft the description yourself using the template below.
- **Depth — default to the full six-section template.** Unless the user's phrasing clearly signals brevity (*"quick issue"*, *"one-liner"*, *"just the AC"*, *"brief"*, *"terse"*, *"minimum"*, *"short"*), structure the body as **Context → Problem → Proposal → Acceptance Criteria → Verification → Out of scope**. The 120-char / 2-item floor is what the validator *rejects*, not what reviewers *want*. If the user gives you only a title, draft a verbose body from the full template — ask follow-up questions rather than shipping the floor. For trivial changes (typo fix, one-line config tweak), collapsing `Problem` into `Context` and dropping `Verification` is fine when the AC is self-evidently testable — collapse deliberately, not by default.
- ```markdown
- ## Context
- **Title:** <title>
- <What is changing and why. 2-4 sentences. Link prior issues, docs, or incidents that motivate this.>
- ## Problem
- <What specifically is broken, missing, or insufficient today. Name the file, flow, or behavior.>
- ## Proposal
- <What you intend to do about it. High-level approach, not implementation line-by-line.>
- ## Acceptance Criteria
- - [ ] <Concrete, testable outcome>
- - [ ] <Concrete, testable outcome>
- ## Verification
- <How the AC will actually be checked. Manual steps, test command, or review instruction.>
- ## Out of Scope
- - <What this issue does NOT cover — redirect to the follow-up or explain why it's deferred>
- ```
- Print the template on demand with: `npm run ops -- create-issue --template`. See [docs/issue-template.md](docs/issue-template.md) for a fully populated example.
- 2. **Labels.** Apply from the [label taxonomy](docs/labels.md):
- - Exactly ONE type label (`feature`, `bug`, `refactor`, `chore`, `spike`)
- - 1-2 domain labels (`backend`, `frontend`, `security`, `infrastructure`, etc.)
- - Scope labels if relevant (`blocked`, `breaking-change`, `tech-debt`)
- 3. **Project assignment.** Assign to the appropriate project based on context (active sprint, feature area, or user instruction). If no project is obvious, ask the user. In batch/subagent context, use the project associated with the parent issue or the default initiative project.
- **When updating** an existing issue, preserve existing labels and project — only add missing labels or correct misassigned ones.
- > **MCP tools.** Before calling `mcp__linear__save_issue` (or any MCP issue-create tool), pipe the draft description through `validate-description --stdin` and only call `save_issue` if it exits 0:
- >
- > ```bash
- > echo "$DRAFT_BODY" | npm run ops -- validate-description --stdin
- > # exit 0 → safe to call save_issue
- > # exit 5 → fix the description; re-pipe; try again
- > ```
- >
- > The CLI already gates this for `create-issue` / `create-sub-issue`. MCP has no server-side gate — this pre-flight + the retroactive `npm run lint-issues` audit are the only enforcement for the MCP path. For longer drafts in a file, use `--file <path>` instead of `--stdin`.
- >
- > **Depth ≠ validation.** Validation passing (exit 0) only means the 120-char / 2-AC floor is met. Structure the body as the full six-section template (Context → Problem → Proposal → AC → Verification → Out of Scope) unless the user explicitly asked for brevity — see bullet #1 above.
- >
- > **Enforcement model.** CLI + SDK paths are hard-gated; the MCP path is instruction + audit. A PreToolUse hook that intercepts `save_issue` was considered and rejected: it only fires when Claude Code is the runtime, install is per-user, and the payload shape is harness-version-dependent. Run `npm run lint-issues -- --since 24h` locally or in CI to catch instruction-layer drift retroactively.
- ---
- ## Project Planning Workflow
- > See [Issue Creation Checklist](#issue-creation-checklist-required) — descriptions, labels, and project assignment are required for every issue.
- ### Create Issues in the Correct Project from the Start
- **Best Practice**: When planning a new phase or initiative, create the project and its issues together in a single planning session. Avoid creating issues in a catch-all project and moving them later.
- #### Recommended Workflow
- 1. **Create the project first**:
- ```bash
- npm run ops -- create-project "Phase X: Feature Name" "My Initiative"
- ```
- 2. **Set project state to Planned**:
- ```bash
- npm run ops -- project-status "Phase X: Feature Name" planned
- ```
- 3. **Create issues directly in the project** (use `--template` to print the canonical template first, or pass a multi-line description via heredoc):
- ```bash
- # Print the template to seed your description
- npm run ops -- create-issue --template
- # Create the issue with a template-shaped description
- npm run ops -- create-issue "Phase X: Feature Name" "Parent task" "$(cat <<'EOF'
- ## Context
- Implement the core feature with integration tests and documentation.
- ## Acceptance Criteria
- - [ ] All API endpoints return correct responses
- - [ ] Test coverage >80% on new modules
- EOF
- )" --labels feature,backend
- npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "$(cat <<'EOF'
- ## Context
- Set up database schema and migrations for the new feature tables.
- ## Acceptance Criteria
- - [ ] Migration runs cleanly on a fresh database
- - [ ] Rollback migration restores prior schema
- EOF
- )"
- ```
- 4. **Update project state when work begins**:
- ```bash
- npm run ops -- project-status "Phase X: Feature Name" in-progress
- ```
- #### Why This Matters
- - **Traceability**: Issues are linked to their project from creation
- - **Metrics**: Project progress tracking is accurate from day one
- - **Workflow**: No time wasted moving issues between projects
- - **Organization**: Linear views and filters work correctly
- #### Anti-Pattern to Avoid
- ❌ Creating issues in a "holding" project and moving them later:
- ```bash
- # Don't do this
- create-issue "Phase 6A" "New feature" # Wrong project
- # Later: manually move to Phase X # Extra work
- ```
- ---
- ## Project Management Commands
- ### project-status
- Update a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.
- ```bash
- npm run ops -- project-status <project-name> <state>
- ```
- **Valid States:**
- | Input | Description | API Value |
- |-------|-------------|-----------|
- | `backlog` | Not yet started | backlog |
- | `planned` | Scheduled for future | planned |
- | `in-progress` | Currently active | started |
- | `paused` | Temporarily on hold | paused |
- | `completed` | Successfully finished | completed |
- | `canceled` | Will not be done | canceled |
- **Examples:**
- ```bash
- # Start working on a project
- npm run ops -- project-status "Phase 8: MCP Decision Engine" in-progress
- # Mark project complete
- npm run ops -- project-status "Phase 8" completed
- # Partial name matching works
- npm run ops -- project-status "Phase 8" paused
- ```
- ### link-initiative
- Link an existing project to an initiative.
- ```bash
- npm run ops -- link-initiative <project-name> <initiative-name>
- ```
- **Examples:**
- ```bash
- # Link a project to an initiative
- npm run ops -- link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"
- # Partial matching works
- npm run ops -- link-initiative "Phase 8" "Q1 Goals"
- ```
- ### unlink-initiative
- Remove a project from an initiative.
- ```bash
- npm run ops -- unlink-initiative <project-name> <initiative-name>
- ```
- **Examples:**
- ```bash
- # Remove incorrect link
- npm run ops -- unlink-initiative "Phase 8" "Linear Skill"
- # Clean up test links
- npm run ops -- unlink-initiative "Test Project" "Q1 Goals"
- ```
- **Error Handling:**
- - Returns error if project is not linked to the specified initiative
- - Returns error if project or initiative not found
- ### Complete Project Lifecycle Example
- ```bash
- # 1. Create project linked to initiative
- npm run ops -- create-project "Phase 11: New Feature" "Q1 Goals"
- # 2. Set state to planned
- npm run ops -- project-status "Phase 11" planned
- # 3. Create issues in the project
- npm run ops -- create-issue "Phase 11" "Parent task" "Description"
- npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "Details"
- # 4. Start work - update to in-progress
- npm run ops -- project-status "Phase 11" in-progress
- # 5. Mark issues done
- npm run ops -- status Done ENG-XXX ENG-YYY
- # 6. Complete project
- npm run ops -- project-status "Phase 11" completed
- # 7. (Optional) Link to additional initiative
- npm run ops -- link-initiative "Phase 11" "Q2 Goals"
- ```
- ---
- ## Tool Selection
- Choose the right tool for the task:
- | Priority | Tool | When to Use |
- |----------|------|-------------|
- | 1 | **MCP (Official Server)** | Most operations - PREFERRED |
- | 2 | **`lin` CLI** | Fast-path for reads/status updates when installed (optional) |
- | 3 | **Helper Scripts** | Bulk operations, label taxonomy, project workflows |
- | 4 | **SDK scripts** | Complex operations (loops, conditionals) |
- | 5 | **GraphQL API** | Operations not supported by above |
- ### `lin` CLI (Optional Fast-Path)
- If the [`lin`](https://github.com/aaronkwhite/linear-cli) Rust binary is installed, the skill uses it automatically for:
- - Issue status updates (`status`, `done`, `wip`)
- - Listing initiatives
- - Searching issues (`search <query>`)
- - Listing issues (`list-issues [--team X] [--state Y]`)
- - User info (`whoami`)
- All operations fall back silently to the SDK when `lin` is unavailable.
- **Install** (optional):
- ```bash
- brew install aaronkwhite/tap/lin # macOS (Homebrew)
- cargo install lincli # Any platform with Rust
- ```
- **Disable**: Set `LINEAR_USE_LIN=0` to skip `lin` even when installed.
- ### MCP Server Configuration
- **Use the official Linear MCP server** at `mcp.linear.app`:
- ```json
- {
- "mcpServers": {
- "linear": {
- "command": "npx",
- "args": ["mcp-remote", "https://mcp.linear.app/sse"],
- "env": { "LINEAR_API_KEY": "your_api_key" }
- }
- }
- }
- ```
- > **WARNING**: Do NOT use deprecated community servers. See [troubleshooting.md](troubleshooting.md) for details.
- ### MCP Reliability (Official Server)
- | Operation | Reliability | Notes |
- |-----------|-------------|-------|
- | Create issue | ✅ High | Full support |
- | Update status | ✅ High | Use `state: "Done"` directly |
- | List/Search issues | ✅ High | Supports filters, queries |
- | Add comment | ✅ High | Works with issue IDs |
- ### Quick Status Update
- ```bash
- # Via MCP - use human-readable state names
- update_issue with id="issue-uuid", state="Done"
- # Via helper script (bulk operations)
- node scripts/linear-helpers.mjs update-status Done 123 124 125
- ```
- ### Helper Script Reference
- For detailed helper script usage, see **[troubleshooting.md](troubleshooting.md)**.
- ### Parallel Agent Execution
- For bulk operations or background execution, use the `Linear-specialist` subagent:
- ```javascript
- Task({
- description: "Update Linear issues",
- prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
- subagent_type: "Linear-specialist"
- })
- ```
- **When to use `Linear-specialist` (parallel):**
- - Bulk status updates (3+ issues)
- - Project status changes
- - Creating multiple issues
- - Sync operations after code changes
- **When to use direct execution:**
- - Single issue queries
- - Viewing issue details
- - Quick status checks
- - Operations needing immediate results
- See **[sync.md](sync.md)** for parallel execution patterns.
- ## Image Uploads
- ### Step 1: Extract the image from conversation context
- Images shared inline in Claude Code are **not** saved to disk automatically — they live as base64 in the session JSONL. Use the extraction script:
- ```bash
- # Find the current session JSONL
- ls -t ~/.claude/projects/<project-path>/*.jsonl | head -1
- # Extract all inline images (saves to /tmp by default)
- npm run extract-image -- <path-to-session.jsonl>
- # Or specify a custom output directory
- npm run extract-image -- <path-to-session.jsonl> ~/Desktop
- ```
- This saves images to `/tmp/shared-image-0.png`, `/tmp/shared-image-1.png`, etc.
- > **Always verify** the extracted image with the Read tool before uploading.
- ### Step 2: Create the issue
- ```bash
- # Standard approach
- npm run ops -- create-issue "Project Name" "Issue title" "Description"
- ```
- > **Note**: If you need to target a specific team and `create-issue` picks the wrong one, use GraphQL with explicit `teamId`:
- >
- > ```bash
- > # Get the project's team
- > npm run query -- 'query { projects(filter: { name: { containsIgnoreCase: "PROJECT NAME" } }) { nodes { id name teams { nodes { id name key } } } } }'
- >
- > # Create with explicit teamId
- > npm run query -- 'mutation { issueCreate(input: { teamId: "TEAM_UUID", projectId: "PROJECT_UUID", title: "Issue title", description: "Description" }) { success issue { id identifier url } } }'
- > ```
- ### Step 3: Upload the image and attach to the issue
- ```bash
- npm run upload-image -- /tmp/shared-image-0.png ENG-123 "Optional comment text"
- ```
- The script will:
- 1. Upload the file to Linear's S3 storage
- 2. Post a comment on the issue with the image embedded as markdown
- **Supported formats**: PNG, JPG/JPEG, GIF, WebP, SVG, PDF
- ### Known pitfalls
- | Problem | Cause | Fix |
- |---------|-------|-----|
- | `create-issue` picks wrong team | Multiple teams in workspace | Use GraphQL with explicit teamId (see Step 2) |
- | `upload-image.ts` "Issue not found" | Issue was deleted before attaching | Ensure issue exists first |
- | Image not found on disk | Shared inline, not as file | Extract from session JSONL (Step 1) |
- ---
- ## Critical Requirements
- ### Issues → Projects → Initiatives
- **Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**
- | Entity | Must Link To | If Missing |
- |--------|--------------|------------|
- | Issue | Project | Not visible in project board |
- | Project | Initiative | Not visible in roadmap |
- See **[projects.md](projects.md)** for complete project creation checklist.
- ---
- ## Conventions
- ### Issue Status
- - **Assigned to me**: Set `state: "Todo"`
- - **Unassigned**: Set `state: "Backlog"`
- ### Labels
- Uses **domain-based label taxonomy** — see [Issue Creation Checklist](#issue-creation-checklist-required) for required rules and [docs/labels.md](docs/labels.md) for the full taxonomy.
- ```bash
- # Validate labels
- npm run ops -- labels validate "feature,security"
- # Suggest labels for issue
- npm run ops -- labels suggest "Fix XSS vulnerability"
- ```
- ## SDK Automation Scripts
- **Use only when MCP tools are insufficient.** For complex operations involving loops, mapping, or bulk updates, write TypeScript scripts using `@linear/sdk`. See `sdk.md` for:
- - Complete script patterns and templates
- - Common automation examples (bulk updates, filtering, reporting)
- - Tool selection criteria
- Scripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.
- ## GraphQL API
- **Fallback only.** Use when operations aren't supported by MCP or SDK.
- See **[api.md](api.md)** for complete documentation including:
- - Authentication and setup
- - Example queries and mutations
- - Timeout handling patterns
- - MCP timeout workarounds
- - Shell script compatibility
- **Quick ad-hoc query:**
- ```bash
- npm run query -- "query { viewer { name } }"
- ```
- ## Projects & Initiatives
- For advanced project and initiative management patterns, see **[projects.md](projects.md)**.
- **Quick reference** - common project commands:
- ```bash
- # Create project linked to initiative
- npm run ops -- create-project "Phase X: Name" "My Initiative"
- # Update project status
- npm run ops -- project-status "Phase X" in-progress
- npm run ops -- project-status "Phase X" completed
- # Link/unlink projects to initiatives
- npm run ops -- link-initiative "Phase X" "My Initiative"
- npm run ops -- unlink-initiative "Phase X" "Old Initiative"
- ```
- **Key topics in projects.md:**
- - Project creation checklist (mandatory steps)
- - Content vs Description fields
- - Discovery before creation
- - Codebase verification before work
- - Sub-issue management
- - Project status updates
- - Project updates (status reports)
- ---
- ## Sync Patterns (Bulk Operations)
- For bulk synchronization of code changes to Linear, see **[sync.md](sync.md)**.
- **Quick sync commands:**
- ```bash
- # Bulk update issues to Done
- npm run ops -- status Done ENG-101 ENG-102 ENG-103
- # Update project status
- npm run ops -- project-status "My Project" completed
- ```
- ### Bulk Issue Import (`bulk-create.ts`)
- Create many issues in one team from a manifest directory, each with its own
- markdown description and optional media files. Media is uploaded via Linear's
- `fileUpload` API and embedded in the description (images inline, other files
- as links).
- Use case: importing customer feedback, retrospective action items, or custdev
- tickets where each issue needs screenshots or recordings attached.
- ```bash
- LINEAR_API_KEY=xxx npx tsx scripts/bulk-create.ts \
- --manifest ./feedback-2026-04 \
- --config ./feedback-2026-04/config.json
- ```
- Preview the manifest first without creating issues or uploading files:
- ```bash
- npx tsx scripts/bulk-create.ts \
- --manifest ./feedback-2026-04 \
- --config ./feedback-2026-04/config.json \
- --dry-run
- ```
- **Manifest directory:**
- ```
- feedback-2026-04/
- tickets.json # [{ key, title, priority?, labels?, files? }, ...]
- config.json # { team_key, state_name?, default_priority? }
- desc-<key>.md # description markdown per ticket (optional)
- <media files> # referenced by each ticket's files[]
- ```
- **Config resolves by name, not UUID:**
- - `team_key` → looked up via `findTeamByKey` (e.g. `"ENG"`)
- - `state_name` → optional workflow state (e.g. `"Triage"`)
- - Ticket `labels` → label names resolved per team case-insensitively; unknown
- names warn by default, or fail with `--strict`
- ---
- ## Reference
- | Document | Purpose |
- |----------|---------|
- | [api.md](api.md) | GraphQL API reference, timeout handling |
- | [sdk.md](sdk.md) | SDK automation patterns |
- | [sync.md](sync.md) | Bulk sync patterns |
- | [projects.md](projects.md) | Project & initiative management |
- | [troubleshooting.md](troubleshooting.md) | Common issues, MCP debugging |
- | [docs/labels.md](docs/labels.md) | Label taxonomy |
- **External:** [Linear MCP Documentation](https://linear.app/docs/mcp.md)
README.md · README · 419 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Linear Skill for Claude Code
- A comprehensive [Claude Code](https://claude.ai/code) skill for managing Linear issues, projects, and teams. Provides patterns for MCP tools, SDK automation, and GraphQL API access.
- ## Features
- - **esbuild Pre-compilation** — 18x faster CLI startup (~50ms vs ~1s) with transparent tsx fallback via shared `scripts/run.sh`
- - **Label Taxonomy System** — Domain-based labels for consistent categorization and agent routing
- - **First-Time Setup Check** — Automatic configuration validation with actionable guidance
- - **High-Level Operations** — Simple commands for initiatives, projects, and status updates
- - **Sub-Issue Management** — Create and manage parent-child issue relationships
- - **Discovery Before Creation** — Mandatory checks to prevent duplicate projects/issues
- - **MCP Tool Integration** — Simple operations via Linear MCP server
- - **SDK Automation** — Complex operations with TypeScript scripts
- - **GraphQL API** — Direct API access for advanced queries
- - **Project Management** — Content, descriptions, milestones, resource links
- - **Bulk Sync** — Synchronize code changes with Linear via CLI, agents, or hooks
- - **Image Uploads** — Upload images to Linear's S3 storage and attach to issues
- - **Smoke Tests** — Automated verification of build output and CLI behavior
- - **`lin` CLI Integration** — Optional fast-path via [aaronkwhite/linear-cli](https://github.com/aaronkwhite/linear-cli) Rust binary with silent SDK fallback
- ## Quick Start (New Users)
- ### 1. Install the Skill
- ```bash
- git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
- cd ~/.claude/skills/linear && npm install
- ```
- ### 2. Run Setup Check
- ```bash
- npm run setup
- ```
- This checks your configuration and tells you exactly what's missing.
- ### 3. Get Your API Key (If Needed)
- 1. Open [Linear](https://linear.app) in your browser
- 2. Go to **Settings** → **Security & access** → **Personal API keys**
- 3. Click **Create key** and copy it (starts with `lin_api_`)
- 4. Add to your environment:
- ```bash
- # Add to shell profile
- echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc
- source ~/.zshrc
- ```
- ### 4. Verify It Works
- ```bash
- npm run ops -- whoami
- ```
- You should see your name and organization.
- ### 5. Build for Faster Startup (Optional)
- ```bash
- npm run build
- ```
- Pre-compiles TypeScript to JavaScript for ~18x faster CLI cold starts. Without building, commands still work via tsx (slower but functional).
- ### 6. Start Using It
- ```bash
- # Create an initiative
- npm run ops -- create-initiative "My Project"
- # Create a project
- npm run ops -- create-project "Phase 1" "My Project"
- # Create a sub-issue under a parent
- npm run ops -- create-sub-issue ENG-100 "Add tests" "Unit tests for feature"
- # Set parent-child relationships for existing issues
- npm run ops -- set-parent ENG-100 ENG-101 ENG-102
- # Update issue status
- npm run ops -- status Done ENG-123 ENG-124
- # See all commands
- npm run ops -- help
- ```
- ---
- ## Installation
- ```bash
- # Clone directly to your skills directory
- git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
- cd ~/.claude/skills/linear && npm install
- ```
- ## Prerequisites
- - **Linear API Key** — Generate at Linear → Settings → Security & access → Personal API keys
- - **`lin` CLI** (Optional) — Faster execution for status updates, search, and listings:
- ```bash
- brew install aaronkwhite/tap/lin # macOS (Homebrew)
- cargo install lincli # Any platform with Rust
- ```
- Set `LINEAR_USE_LIN=0` to disable even when installed.
- - **Linear MCP Server** (Recommended) — Use the **official Linear MCP server** for best reliability:
- ```json
- {
- "mcpServers": {
- "linear": {
- "command": "npx",
- "args": ["mcp-remote", "https://mcp.linear.app/sse"],
- "env": {
- "LINEAR_API_KEY": "your_api_key"
- }
- }
- }
- }
- ```
- > **Important**: Always use Linear's official MCP server at `mcp.linear.app`. Do NOT use deprecated community servers like `linear-mcp-server` (npm) or `jerhadf/linear-mcp-server` (GitHub).
- ## Directory Structure
- ```
- linear-claude-skill/
- ├── SKILL.md # Main skill instructions (Claude Code discovers this)
- ├── api.md # GraphQL API reference
- ├── sdk.md # SDK automation patterns
- ├── sync.md # Bulk sync patterns
- ├── docs/
- │ └── labels.md # Label taxonomy documentation
- ├── scripts/
- │ ├── run.sh # Shared runner (dist/ with tsx fallback)
- │ ├── build.mjs # esbuild pre-compilation script
- │ ├── linear-ops.ts # High-level operations (issues, projects, labels)
- │ ├── query.ts # GraphQL query runner
- │ ├── setup.ts # Configuration checker
- │ ├── sync.ts # Bulk sync CLI tool
- │ ├── upload-image.ts # Upload images to Linear S3
- │ ├── extract-image.ts # Extract images from session JSONL
- │ ├── linear-api.mjs # Direct API wrapper
- │ ├── __tests__/ # Smoke tests (Node built-in test runner)
- │ └── lib/ # Shared utilities (taxonomy, labels, verification)
- ├── dist/ # Pre-compiled JS output (gitignored, in npm package)
- └── hooks/
- └── post-edit.sh # Auto-sync hook
- ```
- ## Key Patterns
- ### Discovery Before Creation (Critical!)
- **ALWAYS check Linear before creating projects or issues.** This prevents duplicates:
- ```bash
- # Check for existing projects
- linear projects list | grep -i "phase\|feature-name"
- # Check for existing issues
- linear issues list --filter "title:keyword"
- ```
- See `SKILL.md` → "Discovery Before Creation" for the full checklist.
- ### Codebase Verification Before Work (Critical!)
- **ALWAYS verify codebase state before accepting issue scope at face value.**
- Issue descriptions may be outdated or speculative. APIs or features may already be implemented!
- ```bash
- # Before starting "implement API" issues:
- ls src/pages/api/admin/members/ # Check if files exist
- grep -r "test.skip" tests/ # Check if tests are just skipped
- ```
- **Key Lesson**: Issues describing "missing" features may already be implemented. The real work is often un-skipping tests and fixing assertions, not reimplementing.
- See `SKILL.md` → "Codebase Verification Before Work" for the full checklist.
- ### Content vs Description (Critical!)
- Linear has TWO text fields — using the wrong one causes blank displays:
- | Field | Limit | Shows In |
- |-------|-------|----------|
- | `description` | 255 chars | List views, tooltips |
- | `content` | Unlimited | **Main detail panel** |
- Always set BOTH when creating projects.
- ### Project Status UUIDs
- Status UUIDs are **workspace-specific**. Query your workspace:
- ```graphql
- query { projectStatuses { nodes { id name } } }
- ```
- Common statuses: `Backlog`, `Planned`, `In Progress`, `Completed`, `Canceled`
- ### Sub-Issue Management
- Organize issues into parent-child hierarchies for better tracking:
- ```bash
- # Create a sub-issue under a parent issue
- # Inherits team and project from parent automatically
- npm run ops -- create-sub-issue <parent> <title> [description] [--priority 1-4] [--labels label1,label2]
- # Set existing issues as children of a parent
- npm run ops -- set-parent <parent> <child1> <child2> ...
- # List all sub-issues of a parent
- npm run ops -- list-sub-issues <parent>
- ```
- **When to use sub-issues:**
- - Breaking down features into trackable subtasks
- - Organizing TDD/E2E test issues under a feature issue
- - Sequential phases within a larger initiative
- ### Label Taxonomy
- A standardized label system for consistent issue categorization across projects:
- ```bash
- # Show full taxonomy (25 labels across 3 categories)
- npm run ops -- labels taxonomy
- # Validate label combinations
- npm run ops -- labels validate "feature,security,breaking-change"
- # Suggest labels based on issue title
- npm run ops -- labels suggest "Fix XSS vulnerability in login form"
- # Show agent recommendations for labels
- npm run ops -- labels agents "security,performance"
- ```
- **Label Categories:**
- - **Type** (exactly one required): `feature`, `bug`, `refactor`, `chore`, `spike`
- - **Domain** (1-2 recommended): `security`, `backend`, `frontend`, `testing`, `infrastructure`, `mcp`, `cli`, etc.
- - **Scope** (0-2 optional): `blocked`, `breaking-change`, `tech-debt`, `needs-split`, `good-first-issue`
- See `docs/labels.md` for the complete taxonomy guide.
- ### Resource Links
- Add clickable links to projects/initiatives:
- ```graphql
- mutation {
- entityExternalLinkCreate(input: {
- url: "https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/phase-1.md",
- label: "Implementation Doc",
- projectId: "<uuid>"
- }) { success }
- }
- ```
- ### Project Milestones
- Track Definition of Done:
- ```graphql
- mutation {
- projectMilestoneCreate(input: {
- projectId: "<uuid>",
- name: "DoD: Testing",
- description: "Unit tests, E2E tests, 100% coverage"
- }) { success }
- }
- ```
- ### Project Updates (Status Reports)
- Post status updates to a project's Updates tab:
- ```bash
- npm run ops -- create-project-update "Project Name" "## Update\n\nBody" --health onTrack
- ```
- Health options: `onTrack`, `atRisk`, `offTrack`
- See `SKILL.md` for full documentation and GraphQL examples.
- ## Usage Examples
- ### Create Issue (MCP)
- ```
- Create a high priority issue titled "Fix authentication bug" in the ENG team
- ```
- ### Update Project Status (GraphQL)
- ```graphql
- mutation {
- projectUpdate(id: "<project-uuid>", input: {
- statusId: "<status-uuid>" # Get from projectStatuses query
- }) { success }
- }
- ```
- ### Bulk Operations (SDK)
- See `sdk.md` for TypeScript patterns for loops, filtering, and batch updates.
- ### Bulk Sync (NEW)
- Synchronize code changes with Linear issues in bulk:
- ```bash
- # Update multiple issues to Done
- npm run sync -- --issues ENG-432,ENG-433,ENG-434 --state Done
- # Update project status after phase completion
- npm run sync -- --project "Phase 11" --state completed
- # Verify sync completed
- npm run sync -- --verify ENG-432,ENG-433 --expected-state Done
- ```
- #### Agent-Spawned Sync
- Spawn a parallel agent for autonomous sync via Task tool:
- ```javascript
- Task({
- description: "Sync Phase 11 to Linear",
- prompt: "Update ENG-432,433,434 to Done. Update project to completed.",
- subagent_type: "Linear-specialist"
- })
- ```
- #### Hook-Triggered Sync
- Auto-suggest sync after code edits. Add to `.claude/settings.json`:
- ```json
- {
- "hooks": {
- "PostToolUse": [{
- "matcher": "Write|Edit",
- "hooks": [{
- "type": "command",
- "command": "bash ~/.claude/skills/linear/hooks/post-edit.sh"
- }]
- }]
- }
- }
- ```
- See `sync.md` for complete patterns including AgentDB integration.
- ## Changelog
- ### 2.6.3 (2026-04-08)
- - Extracted shared `scripts/run.sh` — all 7 npm scripts now use a single runner instead of duplicated shell wrappers
- - Replaced `2>/dev/null` with `[ -f dist/X.js ]` file-existence checks so runtime errors surface properly
- - Added `f() { ...; }; f` argument forwarding to all npm scripts (community fix from PR #17 by @aphexcx)
- - Added smoke test for npm script argument forwarding
- - Consistent `[WARN]` fallback messages across all scripts including `sync`
- ### 2.5.0 (2026-03-17)
- - Consolidated `requireClient()` to delegate to `getLinearClient()` — single client singleton
- - Added smoke tests for build output, CLI behavior, and lazy client initialization
- - Documented `__BUNDLED__` build-time define pattern
- - Extended esbuild fallback pattern to `upload-image` and `extract-image` scripts
- - Bumped SKILL.md version to match package.json
- ### 2.4.0 (2026-03-04)
- - Added esbuild pre-compilation for **18x faster CLI startup** (~50ms vs ~1s)
- - Lazy `getLinearClient()` — SDK initialization deferred to first API call
- - Transparent fallback via shared `scripts/run.sh`
- - Removed `import.meta.url` CLI guards from lib files
- - `npm run` as canonical invocation form in all documentation
- - CI workflow with build verification and smoke tests
- ### 2.3.0 (2026-02-27)
- - Added `scripts/upload-image.ts` and `scripts/extract-image.ts` for image management
- See [CHANGELOG.md](CHANGELOG.md) for full version history.
- ## Development
- ### Prerequisites
- - Node.js >= 20.11.0 (see `.nvmrc`)
- - npm
- ### Quick Start
- ```bash
- git clone https://github.com/wrsmith108/linear-claude-skill.git
- cd linear-claude-skill
- npm ci
- npm test # builds and runs smoke tests (no API key needed)
- npm run build # compile TypeScript to dist/
- ```
- ## Contributing
- Contributions welcome! Please submit issues and PRs to improve the skill.
- ## License
- MIT License — See [LICENSE](LICENSE)
- ## Credits
- Created for the Claude Code community. Patterns developed through real-world project management workflows.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.