Skip to content
Back to search

Linear

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wrsmith108--linear-claude-skill/badge.svg)](/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

i

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)

  1. ---
  2. name: Linear
  3. description: Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.
  4. version: 3.4.1
  5. author: Ryan Smith <ryan@smithhorn.ca>
  6. tags:
  7. - linear
  8. - issue-tracking
  9. - project-management
  10. - mcp
  11. - graphql
  12. - workflow
  13. allowed-tools:
  14. - mcp__linear
  15. - WebFetch(domain:linear.app)
  16. - Bash
  17. ---
  18. # Linear
  19. Tools and workflows for managing issues, projects, and teams in Linear.
  20. ---
  21. ## ⚠️ Tool Availability (READ FIRST)
  22. **This skill supports multiple tool backends. Use whichever is available:**
  23. 1. **MCP Tools (mcp__linear)** - Use if available in your tool set
  24. 2. **Linear CLI (`linear` command)** - Always available via Bash
  25. 3. **Helper Scripts** - For complex operations
  26. **If MCP tools are NOT available**, use the Linear CLI via Bash:
  27. ```bash
  28. # View an issue
  29. linear issues view ENG-123
  30. # Create an issue
  31. linear issues create --title "Issue title" --description "Description"
  32. # Update issue status (get state IDs first)
  33. linear issues update ENG-123 -s "STATE_ID"
  34. # Add a comment
  35. linear issues comment add ENG-123 -m "Comment text"
  36. # List issues
  37. linear issues list
  38. ```
  39. **Do NOT report "MCP tools not available" as a blocker** - use CLI instead.
  40. ---
  41. ## 🔐 Security: Varlock Integration
  42. **CRITICAL**: Never expose API keys in terminal output or Claude's context.
  43. ### Safe Commands (Always Use)
  44. ```bash
  45. # Validate LINEAR_API_KEY is set (masked output)
  46. varlock load 2>&1 | grep LINEAR
  47. # Run commands with secrets injected
  48. varlock run -- npm run query -- "query { viewer { name } }"
  49. # Check schema (safe - no values)
  50. cat .env.schema | grep LINEAR
  51. ```
  52. ### Unsafe Commands (NEVER Use)
  53. ```bash
  54. # ❌ NEVER - exposes key to Claude's context
  55. linear config show
  56. echo $LINEAR_API_KEY
  57. printenv | grep LINEAR
  58. cat .env
  59. ```
  60. ### Setup for New Projects
  61. 1. Create `.env.schema` with `@sensitive` annotation:
  62. ```bash
  63. # @type=string(startsWith=lin_api_) @required @sensitive
  64. LINEAR_API_KEY=
  65. ```
  66. 2. Add `LINEAR_API_KEY` to `.env` (never commit this file)
  67. 3. Configure MCP to use environment variable:
  68. ```json
  69. {
  70. "mcpServers": {
  71. "linear": {
  72. "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
  73. }
  74. }
  75. }
  76. ```
  77. 4. Use `varlock load` to validate before operations
  78. ---
  79. ## Quick Start (First-Time Users)
  80. ### 1. Check Your Setup
  81. Run the setup check to verify your configuration:
  82. ```bash
  83. npm run setup
  84. ```
  85. This will check:
  86. - LINEAR_API_KEY is set and valid
  87. - @linear/sdk is installed
  88. - Linear CLI availability (optional)
  89. - MCP configuration (optional)
  90. ### 2. Get API Key (If Needed)
  91. If setup reports a missing API key:
  92. 1. Open [Linear](https://linear.app) in your browser
  93. 2. Go to **Settings** (gear icon) -> **Security & access** -> **Personal API keys**
  94. 3. Click **Create key** and copy the key (starts with `lin_api_`)
  95. 4. Add to your environment:
  96. ```bash
  97. # Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
  98. export LINEAR_API_KEY="lin_api_your_key_here"
  99. # Option B: Add to Claude Code environment
  100. echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env
  101. # Then reload your shell or restart Claude Code
  102. ```
  103. ### 3. Test Connection
  104. Verify everything works:
  105. ```bash
  106. npm run query -- "query { viewer { name } }"
  107. ```
  108. You should see your name from Linear.
  109. ### 4. Common Operations
  110. ```bash
  111. # Create issue in a project
  112. 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."
  113. # Update issue status
  114. npm run ops -- status Done ENG-123 ENG-124
  115. # Edit issue title or description (fix typos, expand bodies)
  116. npm run ops -- update-issue ENG-123 description --file /tmp/description.md --force
  117. npm run ops -- update-issue ENG-123 title "Corrected title" --force
  118. echo "New body from pipeline" | npm run ops -- update-issue ENG-123 description --stdin --force
  119. npm run ops -- update-issue ENG-123 description "Short inline update" --strict=false
  120. # Create sub-issue
  121. npm run ops -- create-sub-issue ENG-100 "Sub-task" "Details"
  122. # Update project status
  123. npm run ops -- project-status "Phase 1" completed
  124. # Show all commands
  125. npm run ops -- help
  126. ```
  127. See [Project Management Commands](#project-management-commands) for full reference.
  128. ---
  129. ## Issue Creation Checklist (Required)
  130. **When creating a Linear issue, always complete these three steps — even if the user doesn't mention them.**
  131. 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.
  132. **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.
  133. ```markdown
  134. ## Context
  135. **Title:** <title>
  136. <What is changing and why. 2-4 sentences. Link prior issues, docs, or incidents that motivate this.>
  137. ## Problem
  138. <What specifically is broken, missing, or insufficient today. Name the file, flow, or behavior.>
  139. ## Proposal
  140. <What you intend to do about it. High-level approach, not implementation line-by-line.>
  141. ## Acceptance Criteria
  142. - [ ] <Concrete, testable outcome>
  143. - [ ] <Concrete, testable outcome>
  144. ## Verification
  145. <How the AC will actually be checked. Manual steps, test command, or review instruction.>
  146. ## Out of Scope
  147. - <What this issue does NOT cover — redirect to the follow-up or explain why it's deferred>
  148. ```
  149. 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.
  150. 2. **Labels.** Apply from the [label taxonomy](docs/labels.md):
  151. - Exactly ONE type label (`feature`, `bug`, `refactor`, `chore`, `spike`)
  152. - 1-2 domain labels (`backend`, `frontend`, `security`, `infrastructure`, etc.)
  153. - Scope labels if relevant (`blocked`, `breaking-change`, `tech-debt`)
  154. 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.
  155. **When updating** an existing issue, preserve existing labels and project — only add missing labels or correct misassigned ones.
  156. > **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:
  157. >
  158. > ```bash
  159. > echo "$DRAFT_BODY" | npm run ops -- validate-description --stdin
  160. > # exit 0 → safe to call save_issue
  161. > # exit 5 → fix the description; re-pipe; try again
  162. > ```
  163. >
  164. > 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`.
  165. >
  166. > **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.
  167. >
  168. > **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.
  169. ---
  170. ## Project Planning Workflow
  171. > See [Issue Creation Checklist](#issue-creation-checklist-required) — descriptions, labels, and project assignment are required for every issue.
  172. ### Create Issues in the Correct Project from the Start
  173. **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.
  174. #### Recommended Workflow
  175. 1. **Create the project first**:
  176. ```bash
  177. npm run ops -- create-project "Phase X: Feature Name" "My Initiative"
  178. ```
  179. 2. **Set project state to Planned**:
  180. ```bash
  181. npm run ops -- project-status "Phase X: Feature Name" planned
  182. ```
  183. 3. **Create issues directly in the project** (use `--template` to print the canonical template first, or pass a multi-line description via heredoc):
  184. ```bash
  185. # Print the template to seed your description
  186. npm run ops -- create-issue --template
  187. # Create the issue with a template-shaped description
  188. npm run ops -- create-issue "Phase X: Feature Name" "Parent task" "$(cat <<'EOF'
  189. ## Context
  190. Implement the core feature with integration tests and documentation.
  191. ## Acceptance Criteria
  192. - [ ] All API endpoints return correct responses
  193. - [ ] Test coverage >80% on new modules
  194. EOF
  195. )" --labels feature,backend
  196. npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "$(cat <<'EOF'
  197. ## Context
  198. Set up database schema and migrations for the new feature tables.
  199. ## Acceptance Criteria
  200. - [ ] Migration runs cleanly on a fresh database
  201. - [ ] Rollback migration restores prior schema
  202. EOF
  203. )"
  204. ```
  205. 4. **Update project state when work begins**:
  206. ```bash
  207. npm run ops -- project-status "Phase X: Feature Name" in-progress
  208. ```
  209. #### Why This Matters
  210. - **Traceability**: Issues are linked to their project from creation
  211. - **Metrics**: Project progress tracking is accurate from day one
  212. - **Workflow**: No time wasted moving issues between projects
  213. - **Organization**: Linear views and filters work correctly
  214. #### Anti-Pattern to Avoid
  215. ❌ Creating issues in a "holding" project and moving them later:
  216. ```bash
  217. # Don't do this
  218. create-issue "Phase 6A" "New feature" # Wrong project
  219. # Later: manually move to Phase X # Extra work
  220. ```
  221. ---
  222. ## Project Management Commands
  223. ### project-status
  224. Update a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.
  225. ```bash
  226. npm run ops -- project-status <project-name> <state>
  227. ```
  228. **Valid States:**
  229. | Input | Description | API Value |
  230. |-------|-------------|-----------|
  231. | `backlog` | Not yet started | backlog |
  232. | `planned` | Scheduled for future | planned |
  233. | `in-progress` | Currently active | started |
  234. | `paused` | Temporarily on hold | paused |
  235. | `completed` | Successfully finished | completed |
  236. | `canceled` | Will not be done | canceled |
  237. **Examples:**
  238. ```bash
  239. # Start working on a project
  240. npm run ops -- project-status "Phase 8: MCP Decision Engine" in-progress
  241. # Mark project complete
  242. npm run ops -- project-status "Phase 8" completed
  243. # Partial name matching works
  244. npm run ops -- project-status "Phase 8" paused
  245. ```
  246. ### link-initiative
  247. Link an existing project to an initiative.
  248. ```bash
  249. npm run ops -- link-initiative <project-name> <initiative-name>
  250. ```
  251. **Examples:**
  252. ```bash
  253. # Link a project to an initiative
  254. npm run ops -- link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"
  255. # Partial matching works
  256. npm run ops -- link-initiative "Phase 8" "Q1 Goals"
  257. ```
  258. ### unlink-initiative
  259. Remove a project from an initiative.
  260. ```bash
  261. npm run ops -- unlink-initiative <project-name> <initiative-name>
  262. ```
  263. **Examples:**
  264. ```bash
  265. # Remove incorrect link
  266. npm run ops -- unlink-initiative "Phase 8" "Linear Skill"
  267. # Clean up test links
  268. npm run ops -- unlink-initiative "Test Project" "Q1 Goals"
  269. ```
  270. **Error Handling:**
  271. - Returns error if project is not linked to the specified initiative
  272. - Returns error if project or initiative not found
  273. ### Complete Project Lifecycle Example
  274. ```bash
  275. # 1. Create project linked to initiative
  276. npm run ops -- create-project "Phase 11: New Feature" "Q1 Goals"
  277. # 2. Set state to planned
  278. npm run ops -- project-status "Phase 11" planned
  279. # 3. Create issues in the project
  280. npm run ops -- create-issue "Phase 11" "Parent task" "Description"
  281. npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "Details"
  282. # 4. Start work - update to in-progress
  283. npm run ops -- project-status "Phase 11" in-progress
  284. # 5. Mark issues done
  285. npm run ops -- status Done ENG-XXX ENG-YYY
  286. # 6. Complete project
  287. npm run ops -- project-status "Phase 11" completed
  288. # 7. (Optional) Link to additional initiative
  289. npm run ops -- link-initiative "Phase 11" "Q2 Goals"
  290. ```
  291. ---
  292. ## Tool Selection
  293. Choose the right tool for the task:
  294. | Priority | Tool | When to Use |
  295. |----------|------|-------------|
  296. | 1 | **MCP (Official Server)** | Most operations - PREFERRED |
  297. | 2 | **`lin` CLI** | Fast-path for reads/status updates when installed (optional) |
  298. | 3 | **Helper Scripts** | Bulk operations, label taxonomy, project workflows |
  299. | 4 | **SDK scripts** | Complex operations (loops, conditionals) |
  300. | 5 | **GraphQL API** | Operations not supported by above |
  301. ### `lin` CLI (Optional Fast-Path)
  302. If the [`lin`](https://github.com/aaronkwhite/linear-cli) Rust binary is installed, the skill uses it automatically for:
  303. - Issue status updates (`status`, `done`, `wip`)
  304. - Listing initiatives
  305. - Searching issues (`search <query>`)
  306. - Listing issues (`list-issues [--team X] [--state Y]`)
  307. - User info (`whoami`)
  308. All operations fall back silently to the SDK when `lin` is unavailable.
  309. **Install** (optional):
  310. ```bash
  311. brew install aaronkwhite/tap/lin # macOS (Homebrew)
  312. cargo install lincli # Any platform with Rust
  313. ```
  314. **Disable**: Set `LINEAR_USE_LIN=0` to skip `lin` even when installed.
  315. ### MCP Server Configuration
  316. **Use the official Linear MCP server** at `mcp.linear.app`:
  317. ```json
  318. {
  319. "mcpServers": {
  320. "linear": {
  321. "command": "npx",
  322. "args": ["mcp-remote", "https://mcp.linear.app/sse"],
  323. "env": { "LINEAR_API_KEY": "your_api_key" }
  324. }
  325. }
  326. }
  327. ```
  328. > **WARNING**: Do NOT use deprecated community servers. See [troubleshooting.md](troubleshooting.md) for details.
  329. ### MCP Reliability (Official Server)
  330. | Operation | Reliability | Notes |
  331. |-----------|-------------|-------|
  332. | Create issue | ✅ High | Full support |
  333. | Update status | ✅ High | Use `state: "Done"` directly |
  334. | List/Search issues | ✅ High | Supports filters, queries |
  335. | Add comment | ✅ High | Works with issue IDs |
  336. ### Quick Status Update
  337. ```bash
  338. # Via MCP - use human-readable state names
  339. update_issue with id="issue-uuid", state="Done"
  340. # Via helper script (bulk operations)
  341. node scripts/linear-helpers.mjs update-status Done 123 124 125
  342. ```
  343. ### Helper Script Reference
  344. For detailed helper script usage, see **[troubleshooting.md](troubleshooting.md)**.
  345. ### Parallel Agent Execution
  346. For bulk operations or background execution, use the `Linear-specialist` subagent:
  347. ```javascript
  348. Task({
  349. description: "Update Linear issues",
  350. prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
  351. subagent_type: "Linear-specialist"
  352. })
  353. ```
  354. **When to use `Linear-specialist` (parallel):**
  355. - Bulk status updates (3+ issues)
  356. - Project status changes
  357. - Creating multiple issues
  358. - Sync operations after code changes
  359. **When to use direct execution:**
  360. - Single issue queries
  361. - Viewing issue details
  362. - Quick status checks
  363. - Operations needing immediate results
  364. See **[sync.md](sync.md)** for parallel execution patterns.
  365. ## Image Uploads
  366. ### Step 1: Extract the image from conversation context
  367. Images shared inline in Claude Code are **not** saved to disk automatically — they live as base64 in the session JSONL. Use the extraction script:
  368. ```bash
  369. # Find the current session JSONL
  370. ls -t ~/.claude/projects/<project-path>/*.jsonl | head -1
  371. # Extract all inline images (saves to /tmp by default)
  372. npm run extract-image -- <path-to-session.jsonl>
  373. # Or specify a custom output directory
  374. npm run extract-image -- <path-to-session.jsonl> ~/Desktop
  375. ```
  376. This saves images to `/tmp/shared-image-0.png`, `/tmp/shared-image-1.png`, etc.
  377. > **Always verify** the extracted image with the Read tool before uploading.
  378. ### Step 2: Create the issue
  379. ```bash
  380. # Standard approach
  381. npm run ops -- create-issue "Project Name" "Issue title" "Description"
  382. ```
  383. > **Note**: If you need to target a specific team and `create-issue` picks the wrong one, use GraphQL with explicit `teamId`:
  384. >
  385. > ```bash
  386. > # Get the project's team
  387. > npm run query -- 'query { projects(filter: { name: { containsIgnoreCase: "PROJECT NAME" } }) { nodes { id name teams { nodes { id name key } } } } }'
  388. >
  389. > # Create with explicit teamId
  390. > npm run query -- 'mutation { issueCreate(input: { teamId: "TEAM_UUID", projectId: "PROJECT_UUID", title: "Issue title", description: "Description" }) { success issue { id identifier url } } }'
  391. > ```
  392. ### Step 3: Upload the image and attach to the issue
  393. ```bash
  394. npm run upload-image -- /tmp/shared-image-0.png ENG-123 "Optional comment text"
  395. ```
  396. The script will:
  397. 1. Upload the file to Linear's S3 storage
  398. 2. Post a comment on the issue with the image embedded as markdown
  399. **Supported formats**: PNG, JPG/JPEG, GIF, WebP, SVG, PDF
  400. ### Known pitfalls
  401. | Problem | Cause | Fix |
  402. |---------|-------|-----|
  403. | `create-issue` picks wrong team | Multiple teams in workspace | Use GraphQL with explicit teamId (see Step 2) |
  404. | `upload-image.ts` "Issue not found" | Issue was deleted before attaching | Ensure issue exists first |
  405. | Image not found on disk | Shared inline, not as file | Extract from session JSONL (Step 1) |
  406. ---
  407. ## Critical Requirements
  408. ### Issues → Projects → Initiatives
  409. **Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**
  410. | Entity | Must Link To | If Missing |
  411. |--------|--------------|------------|
  412. | Issue | Project | Not visible in project board |
  413. | Project | Initiative | Not visible in roadmap |
  414. See **[projects.md](projects.md)** for complete project creation checklist.
  415. ---
  416. ## Conventions
  417. ### Issue Status
  418. - **Assigned to me**: Set `state: "Todo"`
  419. - **Unassigned**: Set `state: "Backlog"`
  420. ### Labels
  421. 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.
  422. ```bash
  423. # Validate labels
  424. npm run ops -- labels validate "feature,security"
  425. # Suggest labels for issue
  426. npm run ops -- labels suggest "Fix XSS vulnerability"
  427. ```
  428. ## SDK Automation Scripts
  429. **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:
  430. - Complete script patterns and templates
  431. - Common automation examples (bulk updates, filtering, reporting)
  432. - Tool selection criteria
  433. Scripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.
  434. ## GraphQL API
  435. **Fallback only.** Use when operations aren't supported by MCP or SDK.
  436. See **[api.md](api.md)** for complete documentation including:
  437. - Authentication and setup
  438. - Example queries and mutations
  439. - Timeout handling patterns
  440. - MCP timeout workarounds
  441. - Shell script compatibility
  442. **Quick ad-hoc query:**
  443. ```bash
  444. npm run query -- "query { viewer { name } }"
  445. ```
  446. ## Projects & Initiatives
  447. For advanced project and initiative management patterns, see **[projects.md](projects.md)**.
  448. **Quick reference** - common project commands:
  449. ```bash
  450. # Create project linked to initiative
  451. npm run ops -- create-project "Phase X: Name" "My Initiative"
  452. # Update project status
  453. npm run ops -- project-status "Phase X" in-progress
  454. npm run ops -- project-status "Phase X" completed
  455. # Link/unlink projects to initiatives
  456. npm run ops -- link-initiative "Phase X" "My Initiative"
  457. npm run ops -- unlink-initiative "Phase X" "Old Initiative"
  458. ```
  459. **Key topics in projects.md:**
  460. - Project creation checklist (mandatory steps)
  461. - Content vs Description fields
  462. - Discovery before creation
  463. - Codebase verification before work
  464. - Sub-issue management
  465. - Project status updates
  466. - Project updates (status reports)
  467. ---
  468. ## Sync Patterns (Bulk Operations)
  469. For bulk synchronization of code changes to Linear, see **[sync.md](sync.md)**.
  470. **Quick sync commands:**
  471. ```bash
  472. # Bulk update issues to Done
  473. npm run ops -- status Done ENG-101 ENG-102 ENG-103
  474. # Update project status
  475. npm run ops -- project-status "My Project" completed
  476. ```
  477. ### Bulk Issue Import (`bulk-create.ts`)
  478. Create many issues in one team from a manifest directory, each with its own
  479. markdown description and optional media files. Media is uploaded via Linear's
  480. `fileUpload` API and embedded in the description (images inline, other files
  481. as links).
  482. Use case: importing customer feedback, retrospective action items, or custdev
  483. tickets where each issue needs screenshots or recordings attached.
  484. ```bash
  485. LINEAR_API_KEY=xxx npx tsx scripts/bulk-create.ts \
  486. --manifest ./feedback-2026-04 \
  487. --config ./feedback-2026-04/config.json
  488. ```
  489. Preview the manifest first without creating issues or uploading files:
  490. ```bash
  491. npx tsx scripts/bulk-create.ts \
  492. --manifest ./feedback-2026-04 \
  493. --config ./feedback-2026-04/config.json \
  494. --dry-run
  495. ```
  496. **Manifest directory:**
  497. ```
  498. feedback-2026-04/
  499. tickets.json # [{ key, title, priority?, labels?, files? }, ...]
  500. config.json # { team_key, state_name?, default_priority? }
  501. desc-<key>.md # description markdown per ticket (optional)
  502. <media files> # referenced by each ticket's files[]
  503. ```
  504. **Config resolves by name, not UUID:**
  505. - `team_key` → looked up via `findTeamByKey` (e.g. `"ENG"`)
  506. - `state_name` → optional workflow state (e.g. `"Triage"`)
  507. - Ticket `labels` → label names resolved per team case-insensitively; unknown
  508. names warn by default, or fail with `--strict`
  509. ---
  510. ## Reference
  511. | Document | Purpose |
  512. |----------|---------|
  513. | [api.md](api.md) | GraphQL API reference, timeout handling |
  514. | [sdk.md](sdk.md) | SDK automation patterns |
  515. | [sync.md](sync.md) | Bulk sync patterns |
  516. | [projects.md](projects.md) | Project & initiative management |
  517. | [troubleshooting.md](troubleshooting.md) | Common issues, MCP debugging |
  518. | [docs/labels.md](docs/labels.md) | Label taxonomy |
  519. **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)

  1. # Linear Skill for Claude Code
  2. 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.
  3. ## Features
  4. - **esbuild Pre-compilation** — 18x faster CLI startup (~50ms vs ~1s) with transparent tsx fallback via shared `scripts/run.sh`
  5. - **Label Taxonomy System** — Domain-based labels for consistent categorization and agent routing
  6. - **First-Time Setup Check** — Automatic configuration validation with actionable guidance
  7. - **High-Level Operations** — Simple commands for initiatives, projects, and status updates
  8. - **Sub-Issue Management** — Create and manage parent-child issue relationships
  9. - **Discovery Before Creation** — Mandatory checks to prevent duplicate projects/issues
  10. - **MCP Tool Integration** — Simple operations via Linear MCP server
  11. - **SDK Automation** — Complex operations with TypeScript scripts
  12. - **GraphQL API** — Direct API access for advanced queries
  13. - **Project Management** — Content, descriptions, milestones, resource links
  14. - **Bulk Sync** — Synchronize code changes with Linear via CLI, agents, or hooks
  15. - **Image Uploads** — Upload images to Linear's S3 storage and attach to issues
  16. - **Smoke Tests** — Automated verification of build output and CLI behavior
  17. - **`lin` CLI Integration** — Optional fast-path via [aaronkwhite/linear-cli](https://github.com/aaronkwhite/linear-cli) Rust binary with silent SDK fallback
  18. ## Quick Start (New Users)
  19. ### 1. Install the Skill
  20. ```bash
  21. git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
  22. cd ~/.claude/skills/linear && npm install
  23. ```
  24. ### 2. Run Setup Check
  25. ```bash
  26. npm run setup
  27. ```
  28. This checks your configuration and tells you exactly what's missing.
  29. ### 3. Get Your API Key (If Needed)
  30. 1. Open [Linear](https://linear.app) in your browser
  31. 2. Go to **Settings** → **Security & access** → **Personal API keys**
  32. 3. Click **Create key** and copy it (starts with `lin_api_`)
  33. 4. Add to your environment:
  34. ```bash
  35. # Add to shell profile
  36. echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc
  37. source ~/.zshrc
  38. ```
  39. ### 4. Verify It Works
  40. ```bash
  41. npm run ops -- whoami
  42. ```
  43. You should see your name and organization.
  44. ### 5. Build for Faster Startup (Optional)
  45. ```bash
  46. npm run build
  47. ```
  48. Pre-compiles TypeScript to JavaScript for ~18x faster CLI cold starts. Without building, commands still work via tsx (slower but functional).
  49. ### 6. Start Using It
  50. ```bash
  51. # Create an initiative
  52. npm run ops -- create-initiative "My Project"
  53. # Create a project
  54. npm run ops -- create-project "Phase 1" "My Project"
  55. # Create a sub-issue under a parent
  56. npm run ops -- create-sub-issue ENG-100 "Add tests" "Unit tests for feature"
  57. # Set parent-child relationships for existing issues
  58. npm run ops -- set-parent ENG-100 ENG-101 ENG-102
  59. # Update issue status
  60. npm run ops -- status Done ENG-123 ENG-124
  61. # See all commands
  62. npm run ops -- help
  63. ```
  64. ---
  65. ## Installation
  66. ```bash
  67. # Clone directly to your skills directory
  68. git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
  69. cd ~/.claude/skills/linear && npm install
  70. ```
  71. ## Prerequisites
  72. - **Linear API Key** — Generate at Linear → Settings → Security & access → Personal API keys
  73. - **`lin` CLI** (Optional) — Faster execution for status updates, search, and listings:
  74. ```bash
  75. brew install aaronkwhite/tap/lin # macOS (Homebrew)
  76. cargo install lincli # Any platform with Rust
  77. ```
  78. Set `LINEAR_USE_LIN=0` to disable even when installed.
  79. - **Linear MCP Server** (Recommended) — Use the **official Linear MCP server** for best reliability:
  80. ```json
  81. {
  82. "mcpServers": {
  83. "linear": {
  84. "command": "npx",
  85. "args": ["mcp-remote", "https://mcp.linear.app/sse"],
  86. "env": {
  87. "LINEAR_API_KEY": "your_api_key"
  88. }
  89. }
  90. }
  91. }
  92. ```
  93. > **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).
  94. ## Directory Structure
  95. ```
  96. linear-claude-skill/
  97. ├── SKILL.md # Main skill instructions (Claude Code discovers this)
  98. ├── api.md # GraphQL API reference
  99. ├── sdk.md # SDK automation patterns
  100. ├── sync.md # Bulk sync patterns
  101. ├── docs/
  102. │ └── labels.md # Label taxonomy documentation
  103. ├── scripts/
  104. │ ├── run.sh # Shared runner (dist/ with tsx fallback)
  105. │ ├── build.mjs # esbuild pre-compilation script
  106. │ ├── linear-ops.ts # High-level operations (issues, projects, labels)
  107. │ ├── query.ts # GraphQL query runner
  108. │ ├── setup.ts # Configuration checker
  109. │ ├── sync.ts # Bulk sync CLI tool
  110. │ ├── upload-image.ts # Upload images to Linear S3
  111. │ ├── extract-image.ts # Extract images from session JSONL
  112. │ ├── linear-api.mjs # Direct API wrapper
  113. │ ├── __tests__/ # Smoke tests (Node built-in test runner)
  114. │ └── lib/ # Shared utilities (taxonomy, labels, verification)
  115. ├── dist/ # Pre-compiled JS output (gitignored, in npm package)
  116. └── hooks/
  117. └── post-edit.sh # Auto-sync hook
  118. ```
  119. ## Key Patterns
  120. ### Discovery Before Creation (Critical!)
  121. **ALWAYS check Linear before creating projects or issues.** This prevents duplicates:
  122. ```bash
  123. # Check for existing projects
  124. linear projects list | grep -i "phase\|feature-name"
  125. # Check for existing issues
  126. linear issues list --filter "title:keyword"
  127. ```
  128. See `SKILL.md` → "Discovery Before Creation" for the full checklist.
  129. ### Codebase Verification Before Work (Critical!)
  130. **ALWAYS verify codebase state before accepting issue scope at face value.**
  131. Issue descriptions may be outdated or speculative. APIs or features may already be implemented!
  132. ```bash
  133. # Before starting "implement API" issues:
  134. ls src/pages/api/admin/members/ # Check if files exist
  135. grep -r "test.skip" tests/ # Check if tests are just skipped
  136. ```
  137. **Key Lesson**: Issues describing "missing" features may already be implemented. The real work is often un-skipping tests and fixing assertions, not reimplementing.
  138. See `SKILL.md` → "Codebase Verification Before Work" for the full checklist.
  139. ### Content vs Description (Critical!)
  140. Linear has TWO text fields — using the wrong one causes blank displays:
  141. | Field | Limit | Shows In |
  142. |-------|-------|----------|
  143. | `description` | 255 chars | List views, tooltips |
  144. | `content` | Unlimited | **Main detail panel** |
  145. Always set BOTH when creating projects.
  146. ### Project Status UUIDs
  147. Status UUIDs are **workspace-specific**. Query your workspace:
  148. ```graphql
  149. query { projectStatuses { nodes { id name } } }
  150. ```
  151. Common statuses: `Backlog`, `Planned`, `In Progress`, `Completed`, `Canceled`
  152. ### Sub-Issue Management
  153. Organize issues into parent-child hierarchies for better tracking:
  154. ```bash
  155. # Create a sub-issue under a parent issue
  156. # Inherits team and project from parent automatically
  157. npm run ops -- create-sub-issue <parent> <title> [description] [--priority 1-4] [--labels label1,label2]
  158. # Set existing issues as children of a parent
  159. npm run ops -- set-parent <parent> <child1> <child2> ...
  160. # List all sub-issues of a parent
  161. npm run ops -- list-sub-issues <parent>
  162. ```
  163. **When to use sub-issues:**
  164. - Breaking down features into trackable subtasks
  165. - Organizing TDD/E2E test issues under a feature issue
  166. - Sequential phases within a larger initiative
  167. ### Label Taxonomy
  168. A standardized label system for consistent issue categorization across projects:
  169. ```bash
  170. # Show full taxonomy (25 labels across 3 categories)
  171. npm run ops -- labels taxonomy
  172. # Validate label combinations
  173. npm run ops -- labels validate "feature,security,breaking-change"
  174. # Suggest labels based on issue title
  175. npm run ops -- labels suggest "Fix XSS vulnerability in login form"
  176. # Show agent recommendations for labels
  177. npm run ops -- labels agents "security,performance"
  178. ```
  179. **Label Categories:**
  180. - **Type** (exactly one required): `feature`, `bug`, `refactor`, `chore`, `spike`
  181. - **Domain** (1-2 recommended): `security`, `backend`, `frontend`, `testing`, `infrastructure`, `mcp`, `cli`, etc.
  182. - **Scope** (0-2 optional): `blocked`, `breaking-change`, `tech-debt`, `needs-split`, `good-first-issue`
  183. See `docs/labels.md` for the complete taxonomy guide.
  184. ### Resource Links
  185. Add clickable links to projects/initiatives:
  186. ```graphql
  187. mutation {
  188. entityExternalLinkCreate(input: {
  189. url: "https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/phase-1.md",
  190. label: "Implementation Doc",
  191. projectId: "<uuid>"
  192. }) { success }
  193. }
  194. ```
  195. ### Project Milestones
  196. Track Definition of Done:
  197. ```graphql
  198. mutation {
  199. projectMilestoneCreate(input: {
  200. projectId: "<uuid>",
  201. name: "DoD: Testing",
  202. description: "Unit tests, E2E tests, 100% coverage"
  203. }) { success }
  204. }
  205. ```
  206. ### Project Updates (Status Reports)
  207. Post status updates to a project's Updates tab:
  208. ```bash
  209. npm run ops -- create-project-update "Project Name" "## Update\n\nBody" --health onTrack
  210. ```
  211. Health options: `onTrack`, `atRisk`, `offTrack`
  212. See `SKILL.md` for full documentation and GraphQL examples.
  213. ## Usage Examples
  214. ### Create Issue (MCP)
  215. ```
  216. Create a high priority issue titled "Fix authentication bug" in the ENG team
  217. ```
  218. ### Update Project Status (GraphQL)
  219. ```graphql
  220. mutation {
  221. projectUpdate(id: "<project-uuid>", input: {
  222. statusId: "<status-uuid>" # Get from projectStatuses query
  223. }) { success }
  224. }
  225. ```
  226. ### Bulk Operations (SDK)
  227. See `sdk.md` for TypeScript patterns for loops, filtering, and batch updates.
  228. ### Bulk Sync (NEW)
  229. Synchronize code changes with Linear issues in bulk:
  230. ```bash
  231. # Update multiple issues to Done
  232. npm run sync -- --issues ENG-432,ENG-433,ENG-434 --state Done
  233. # Update project status after phase completion
  234. npm run sync -- --project "Phase 11" --state completed
  235. # Verify sync completed
  236. npm run sync -- --verify ENG-432,ENG-433 --expected-state Done
  237. ```
  238. #### Agent-Spawned Sync
  239. Spawn a parallel agent for autonomous sync via Task tool:
  240. ```javascript
  241. Task({
  242. description: "Sync Phase 11 to Linear",
  243. prompt: "Update ENG-432,433,434 to Done. Update project to completed.",
  244. subagent_type: "Linear-specialist"
  245. })
  246. ```
  247. #### Hook-Triggered Sync
  248. Auto-suggest sync after code edits. Add to `.claude/settings.json`:
  249. ```json
  250. {
  251. "hooks": {
  252. "PostToolUse": [{
  253. "matcher": "Write|Edit",
  254. "hooks": [{
  255. "type": "command",
  256. "command": "bash ~/.claude/skills/linear/hooks/post-edit.sh"
  257. }]
  258. }]
  259. }
  260. }
  261. ```
  262. See `sync.md` for complete patterns including AgentDB integration.
  263. ## Changelog
  264. ### 2.6.3 (2026-04-08)
  265. - Extracted shared `scripts/run.sh` — all 7 npm scripts now use a single runner instead of duplicated shell wrappers
  266. - Replaced `2>/dev/null` with `[ -f dist/X.js ]` file-existence checks so runtime errors surface properly
  267. - Added `f() { ...; }; f` argument forwarding to all npm scripts (community fix from PR #17 by @aphexcx)
  268. - Added smoke test for npm script argument forwarding
  269. - Consistent `[WARN]` fallback messages across all scripts including `sync`
  270. ### 2.5.0 (2026-03-17)
  271. - Consolidated `requireClient()` to delegate to `getLinearClient()` — single client singleton
  272. - Added smoke tests for build output, CLI behavior, and lazy client initialization
  273. - Documented `__BUNDLED__` build-time define pattern
  274. - Extended esbuild fallback pattern to `upload-image` and `extract-image` scripts
  275. - Bumped SKILL.md version to match package.json
  276. ### 2.4.0 (2026-03-04)
  277. - Added esbuild pre-compilation for **18x faster CLI startup** (~50ms vs ~1s)
  278. - Lazy `getLinearClient()` — SDK initialization deferred to first API call
  279. - Transparent fallback via shared `scripts/run.sh`
  280. - Removed `import.meta.url` CLI guards from lib files
  281. - `npm run` as canonical invocation form in all documentation
  282. - CI workflow with build verification and smoke tests
  283. ### 2.3.0 (2026-02-27)
  284. - Added `scripts/upload-image.ts` and `scripts/extract-image.ts` for image management
  285. See [CHANGELOG.md](CHANGELOG.md) for full version history.
  286. ## Development
  287. ### Prerequisites
  288. - Node.js >= 20.11.0 (see `.nvmrc`)
  289. - npm
  290. ### Quick Start
  291. ```bash
  292. git clone https://github.com/wrsmith108/linear-claude-skill.git
  293. cd linear-claude-skill
  294. npm ci
  295. npm test # builds and runs smoke tests (no API key needed)
  296. npm run build # compile TypeScript to dist/
  297. ```
  298. ## Contributing
  299. Contributions welcome! Please submit issues and PRs to improve the skill.
  300. ## License
  301. MIT License — See [LICENSE](LICENSE)
  302. ## Credits
  303. Created for the Claude Code community. Patterns developed through real-world project management workflows.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.