Linear Claude Skill

https://github.com/wrsmith108/linear-claude-skill
Admin
A comprehensive Claude Code skill for managing Linear issues, projects, and teams with features...
Tokens:29,526
Snippets:367
Trust Score:7.5
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Run Setup Check

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Execute the setup script to validate your configuration and identify any missing requirements.

```bash
npm run setup
```

--------------------------------

### Clone and Install Project Dependencies

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Clone the repository and install the necessary npm packages to get started with development.

```bash
git clone https://github.com/wrsmith108/linear-claude-skill.git
cd linear-claude-skill
npm ci
```

--------------------------------

### Install lin CLI for any platform with Rust

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Install the 'lin' CLI tool using Cargo on any platform with Rust installed.

```bash
cargo install lincli
```

--------------------------------

### Install lin CLI

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Optional installation commands for the `lin` Rust binary on macOS via Homebrew or any platform with Rust.

```bash
brew install aaronkwhite/tap/lin    # macOS (Homebrew)

```

```bash
cargo install lincli                # Any platform with Rust
```

--------------------------------

### Basic Linear SDK Setup

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sdk.md

Initializes the Linear client with an API key. Ensure the LINEAR_API_KEY environment variable is set or pass the key directly.

```typescript
import { LinearClient } from '@linear/sdk'

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

async function main() {
  // Your automation logic here
}

main().catch(console.error)
```

--------------------------------

### Complete Project Lifecycle Example

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Demonstrates a full project lifecycle from creation to completion, including status updates, issue management, and initiative linking.

```bash
# 1. Create project linked to initiative
npm run ops -- create-project "Phase 11: New Feature" "Q1 Goals"
```

```bash
# 2. Set state to planned
npm run ops -- project-status "Phase 11" planned
```

```bash
# 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"
```

```bash
# 4. Start work - update to in-progress
npm run ops -- project-status "Phase 11" in-progress
```

```bash
# 5. Mark issues done
npm run ops -- status Done ENG-XXX ENG-YYY
```

```bash
# 6. Complete project
npm run ops -- project-status "Phase 11" completed
```

```bash
# 7. (Optional) Link to additional initiative
npm run ops -- link-initiative "Phase 11" "Q2 Goals"
```

--------------------------------

### Build for Faster Startup

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Pre-compile TypeScript to JavaScript using npm run build. This significantly speeds up CLI cold starts.

```bash
npm run build
```

--------------------------------

### Install the Linear Claude Skill

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Clone the skill repository and install its dependencies using npm.

```bash
git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
cd ~/.claude/skills/linear && npm install
```

--------------------------------

### Install lin CLI for macOS

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Install the 'lin' CLI tool using Homebrew on macOS for faster execution of Linear operations.

```bash
brew install aaronkwhite/tap/lin
```

--------------------------------

### Create an Initiative

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Use the 'create-initiative' command to start a new initiative in Linear.

```bash
npm run ops -- create-initiative "My Project"
```

--------------------------------

### Get Help for Linear API Wrapper

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Display help information for the linear-api.mjs script.

```bash
node scripts/linear-api.mjs help
```

--------------------------------

### Full Example Issue Body

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/issue-template.md

This is a complete example of a well-formed issue description, demonstrating the expected depth and detail for each section.

```markdown
## Context
`labels validate` is invoked from `create-issue` (`scripts/linear-ops.ts:135`) on every issue creation. It re-fetches the full label list from Linear on each call — ~400ms round-trip. For batch scripts creating 10+ issues in a loop, that's 4+ seconds of avoidable latency, and it's the dominant cost now that the `lin` CLI fast-path handles the cheap cases.

## Problem
`scripts/lib/labels.ts:fetchAllLabels()` has no caching. Each caller gets a fresh network fetch even when the label set hasn't changed within the process lifetime. No in-memory map, no module-level singleton, no short-lived cache.

## Proposal
Add an in-memory cache to `fetchAllLabels()` keyed by workspace ID (derived from the SDK client). Cache TTL is the process lifetime — no invalidation needed, because new labels appearing mid-batch isn't a realistic case for CLI scripts. Fall through to the network on cache miss; populate the cache on success only (do not cache failures).

## Acceptance Criteria
- [ ] `fetchAllLabels()` makes at most one network call per process for a given workspace
- [ ] A new test in `scripts/__tests__/labels.test.ts` spies on the fetcher and asserts call count ≤ 1 across 3 consecutive `validate` invocations
- [ ] No change to `fetchAllLabels()` signature — all call sites remain identical
- [ ] `LINEAR_DISABLE_LABEL_CACHE=1` env var escape hatch restores fetch-every-call behavior

## Verification
```bash
npm run build && npm test
# then, with a valid LINEAR_API_KEY:
time npm run ops -- labels validate "feature,backend"   # run 3 times back-to-back
# First run: ~400ms (network). Runs 2-3: <50ms each (cached).
LINEAR_DISABLE_LABEL_CACHE=1 npm run ops -- labels validate "feature,backend"
# Should re-fetch, ~400ms again.
```

## Out of Scope
- Persisting the cache across process invocations (filesystem or Redis) — follow-up if batch latency is still problematic
- Invalidation on label CRUD mutations within the same process — assumed rare; if it bites someone, add a clear-on-mutate hook then
- Caching the project or team lists — same pattern applies but track separately
```

--------------------------------

### Run Smoke Tests

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Execute the built-in smoke tests to verify the project setup. No API key is required for this step.

```bash
npm test
```

--------------------------------

### Setup: Define Sensitive API Key in .env.schema

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Define the LINEAR_API_KEY in the .env.schema file with sensitive and required annotations. This ensures the key is treated securely.

```bash
# @type=string(startsWith=lin_api_) @required @sensitive
LINEAR_API_KEY=
```

--------------------------------

### Running TypeScript Scripts with tsx

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sdk.md

Examples of how to execute TypeScript scripts using tsx. Includes direct execution, execution with environment variables, and making scripts executable.

```bash
# Direct execution
npx tsx automation.ts
```

```bash
# With environment variable
LINEAR_API_KEY=lin_api_xxx npx tsx automation.ts
```

```bash
# Make executable (requires shebang)
chmod +x automation.ts
./automation.ts
```

--------------------------------

### Agent-Spawned Sync with Task Tool

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sync.md

Spawn a parallel agent using the Task tool for autonomous synchronization. This example specifies issues to update and a project status to change, recommending GraphQL mutations for bulk operations.

```javascript
Task({
  description: "Sync Current Phase to Linear",
  prompt: `
    Update these Linear issues to Done status:
    ENG-432, ENG-433, ENG-434, ENG-435, ENG-436, ENG-437

    Then update project "Current Phase" status to "completed".

    Use GraphQL mutations (MCP times out on bulk ops).
    Report success/failure counts.
  `,
  subagent_type: "Linear-specialist"
})
```

--------------------------------

### Anti-Pattern: Creating Issue in Wrong Project

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

This example demonstrates an anti-pattern where an issue is created in an incorrect project, necessitating manual relocation later. Avoid this workflow.

```bash
# Don't do this
create-issue "Phase 6A" "New feature"  # Wrong project
# Later: manually move to Phase X      # Extra work
```

--------------------------------

### Post Progress Update (JavaScript)

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

This JavaScript example demonstrates how to post a detailed progress update to a project using the Linear API. It constructs a GraphQL mutation with a Markdown body and sends it via a fetch request.

```javascript
node -e "
const projectId = '<project-uuid>';

const updateBody = 
`## Status: In Progress 🚀

**Swarm execution started** — agents actively implementing features.

### Progress
- **32% complete** (9/28 issues done)
- Project status updated to **In Progress**

### Completed
- ✅ Foundation setup
- ✅ Core configuration

### In Progress
- 🔄 Main feature implementation
- 🔄 UI components

### Up Next
- Testing suite
- Documentation
`;

const mutation = 
`mutation {
  projectUpdateCreate(input: {
    projectId: \"${projectId}\",
    body: ${JSON.stringify(updateBody)},
    health: onTrack
  }) {
    success
    projectUpdate { id }
  }
}`;

fetch('https://api.linear.app/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': process.env.LINEAR_API_KEY },
  body: JSON.stringify({ query: mutation })
}).then(r => r.json()).then(d => console.log(JSON.stringify(d, null, 2)));

```

--------------------------------

### Bulk Sync Script Usage

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

Examples of using the sync script for bulk issue state updates, including dry runs and adding comments.

```bash
# Update multiple issues to Done state (replace PROJ with your team prefix)
LINEAR_API_KEY=lin_api_xxx npm run sync -- --issues PROJ-101,PROJ-102,PROJ-103 --state Done
```

```bash
# Preview changes without applying
LINEAR_API_KEY=lin_api_xxx npm run sync -- --issues PROJ-101,PROJ-102 --state Done --dry-run
```

```bash
# Add comment with state change
LINEAR_API_KEY=lin_api_xxx npm run sync -- --issues PROJ-101 --state Done --comment "Completed in PR #42"
```

--------------------------------

### Add Linear API Key to Environment

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Add your Linear API key to your shell profile to enable authentication. This example shows how to add it to .zshrc and then source the file.

```bash
# Add to shell profile
echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc
source ~/.zshrc
```

--------------------------------

### Setup: Configure MCP for Linear API Key

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Configure MCP to use the LINEAR_API_KEY from environment variables. This JSON snippet shows how to map the environment variable to the MCP server configuration.

```json
{
  "mcpServers": {
    "linear": {
      "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
    }
  }
}
```

--------------------------------

### Programmatic Usage of Linear CLAude Skill

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/labels.md

Demonstrates how to import and use the validation, suggestion, and agent selection functions from the Linear CLAude skill library. Ensure the library is installed and imported correctly.

```typescript
import {
  validateLabels,
  suggestLabels,
  selectAgentsForIssue,
  LABEL_TAXONOMY
} from './lib'

// Validate labels before creating an issue
const validation = validateLabels(['feature', 'security', 'breaking-change'])
if (!validation.valid) {
  console.error('Invalid labels:', validation.errors)
}

// Suggest labels based on title
const suggestions = suggestLabels('Fix XSS vulnerability in login form')
// Returns: [{ label: 'bug', confidence: 0.8 }, { label: 'security', confidence: 0.9 }]

// Get agent recommendations
const agents = selectAgentsForIssue(['security', 'performance'])
// Returns: { primary: ['security-manager'], secondary: ['reviewer', 'tester'] }
```

--------------------------------

### Hook-Triggered Sync Configuration

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sync.md

Configure the `.claude/settings.json` file to automatically suggest sync after code edits. This setup uses a `PostToolUse` hook with a `Write|Edit` matcher to trigger a shell script.

```json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash ~/.claude/skills/linear/hooks/post-edit.sh"
      }]
    }]
  }
}
```

--------------------------------

### Initialize and Use LinearClient

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

Demonstrates how to initialize the LinearClient with an API key and fetch viewer and issue data.

```typescript
import { LinearClient } from '@linear/sdk';

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

// Get viewer
const me = await client.viewer;
console.log(me.name);

// Get issues
const issues = await client.issues({
  filter: { assignee: { id: { eq: me.id } } }
});

for (const issue of issues.nodes) {
  console.log(`${issue.identifier}: ${issue.title}`);
}
```

--------------------------------

### Create a Project

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Use the 'create-project' command to create a new project within an existing initiative.

```bash
npm run ops -- create-project "Phase 1" "My Project"
```

--------------------------------

### Inspect Existing API Implementation

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use cat and head to view the beginning of an existing API implementation file to understand its structure and content.

```bash
# Read the implementation
cat src/pages/api/admin/members/index.ts | head -50
```

--------------------------------

### Create a New Project

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Use this command to create a new project with a specified name and initiative. Ensure you have the 'ops' script available.

```bash
npm run ops -- create-project "Phase X: Feature Name" "My Initiative"
```

--------------------------------

### Manual Project Creation Steps with Utilities

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

For granular control, use individual utility functions to link projects, ensure labels exist, and verify creation. This allows for custom workflows.

```typescript
// Option 3: Manual with utilities
const linkResult = await linkProjectToInitiative(projectId, initiativeId)
const labelResult = await ensureLabelsExist(teamId, ['label1', 'label2'])
const verification = await verifyProjectCreation('Phase X', expectedCount, undefined, initiativeId)
```

--------------------------------

### Get authenticated user

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

Retrieves the details of the currently authenticated user, including their ID, name, and email.

```APIDOC
## Get authenticated user

### Description
Retrieves the details of the currently authenticated user, including their ID, name, and email.

### Method
POST

### Endpoint
https://api.linear.app/graphql

### Parameters
#### Query Parameters
None

#### Request Body
```json
{
  "query": "query Me { viewer { id name email } }"
}
```

### Request Example
```json
{
  "query": "query Me { viewer { id name email } }"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the user.
- **name** (string) - The name of the user.
- **email** (string) - The email address of the user.

#### Response Example
```json
{
  "data": {
    "viewer": {
      "id": "USER_ID",
      "name": "User Name",
      "email": "user@example.com"
    }
  }
}
```
```

--------------------------------

### Get Authenticated User Query

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

A GraphQL query to retrieve the ID, name, and email of the currently authenticated user.

```graphql
query Me {
  viewer {
    id
    name
    email
  }
}
```

--------------------------------

### Get team issues

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

Retrieves a list of issues for a specific team, including issue ID, title, state, and assignee.

```APIDOC
## Get team issues

### Description
Retrieves a list of issues for a specific team, including issue ID, title, state, and assignee.

### Method
POST

### Endpoint
https://api.linear.app/graphql

### Parameters
#### Path Parameters
None

#### Query Parameters
- **teamId** (String!) - Required - The ID of the team to retrieve issues for.

#### Request Body
```json
{
  "query": "query Team($teamId: String!) { team(id: $teamId) { issues { nodes { id title state { name } assignee { name } } } } }",
  "variables": {
    "teamId": "TEAM_ID"
  }
}
```

### Request Example
```json
{
  "query": "query Team($teamId: String!) { team(id: $teamId) { issues { nodes { id title state { name } assignee { name } } } } }",
  "variables": {
    "teamId": "TEAM_ID"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the issue.
- **title** (string) - The title of the issue.
- **state** (object) - The current state of the issue.
  - **name** (string) - The name of the state.
- **assignee** (object) - The user assigned to the issue.
  - **name** (string) - The name of the assignee.

#### Response Example
```json
{
  "data": {
    "team": {
      "issues": {
        "nodes": [
          {
            "id": "ISSUE_ID",
            "title": "Issue Title",
            "state": {
              "name": "Open"
            },
            "assignee": {
              "name": "Assignee Name"
            }
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### View All Commands

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Run the 'help' command to see a list of all available commands for the Linear Claude Skill.

```bash
npm run ops -- help
```

--------------------------------

### Get Team Issues Query

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

A GraphQL query to fetch issues for a specific team, including issue ID, title, state, and assignee.

```graphql
query Team($teamId: String!) {
  team(id: $teamId) {
    issues {
      nodes {
        id
        title
        state { name }
        assignee { name }
      }
    }
  }
}
```

--------------------------------

### Create Project Linked to Initiative

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Use this command to create a new project and link it to an existing initiative.

```bash
npm run ops -- create-project "Phase X: Name" "My Initiative"
```

--------------------------------

### Parallel Agent Execution for Linear Issues

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Example of using the `Linear-specialist` subagent for bulk operations like updating multiple Linear issue statuses.

```javascript
Task({
  description: "Update Linear issues",
  prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
  subagent_type: "Linear-specialist"
})
```

--------------------------------

### New Phase Project Workflow

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

A step-by-step command-line workflow for creating a new project phase. It includes discovery checks, project creation, linking to an initiative, setting content, adding resource links, creating milestones, and adding issues.

```bash
# 0. DISCOVERY - Check for existing project/issues first!
linear projects list | grep -i "phase N"

# 1. Create project via CLI (ONLY if Step 0 found nothing)
linear projects create --name "Phase N: Name" --description "Short summary"

# 2. Link to initiative (use initiativeToProjectCreate mutation - see above)
npm run query -- 'mutation { initiativeToProjectCreate(input: { initiativeId: "<uuid>", projectId: "<uuid>" }) { success } }'

# 3. Set content (main UI panel)
# Use GraphQL to set full markdown content

# 4. Add resource link to implementation doc
# Use entityExternalLinkCreate mutation

# 5. Create milestone for Definition of Done
# Use projectMilestoneCreate mutation

# 6. Create issues via MCP (check for existing first!)
# 7. Add issues to project
```

--------------------------------

### Suggest Labels Based on Issue Title

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Get suggested labels for an issue based on its title. This assists in applying the correct taxonomy to new issues.

```bash
# Suggest labels based on issue title
npm run ops -- labels suggest "Fix XSS vulnerability in login form"
```

--------------------------------

### Check for Existing Projects

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Before creating a new project, use this command to search for existing projects that might match your search terms. This helps prevent duplicates.

```bash
# Check for existing projects
linear projects list | grep -i "phase\|<feature-name>"
```

--------------------------------

### Get user's assigned issues

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

Retrieves a list of issues assigned to the authenticated user, including issue ID, title, and team key.

```APIDOC
## Get user's assigned issues

### Description
Retrieves a list of issues assigned to the authenticated user, including issue ID, title, and team key.

### Method
POST

### Endpoint
https://api.linear.app/graphql

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
```json
{
  "query": "query MyIssues { viewer { assignedIssues { nodes { id title state { name } team { key } } } } }"
}
```

### Request Example
```json
{
  "query": "query MyIssues { viewer { assignedIssues { nodes { id title state { name } team { key } } } } }"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the issue.
- **title** (string) - The title of the issue.
- **state** (object) - The current state of the issue.
  - **name** (string) - The name of the state.
- **team** (object) - The team the issue belongs to.
  - **key** (string) - The key of the team.

#### Response Example
```json
{
  "data": {
    "viewer": {
      "assignedIssues": {
        "nodes": [
          {
            "id": "ISSUE_ID",
            "title": "Issue Title",
            "state": {
              "name": "Open"
            },
            "team": {
              "key": "TEAM_KEY"
            }
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Link Project to Initiative

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Link an existing project to an initiative.

```bash
npm run ops -- link-initiative "Phase X" "My Initiative"
```

--------------------------------

### Show Full Taxonomy

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/labels.md

Use this command to display the complete set of available labels in the taxonomy.

```bash
npm run ops -- labels taxonomy
```

--------------------------------

### Show Agent Recommendations

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/labels.md

Displays agent recommendations for a given set of labels, aiding in routing issues to the appropriate agents.

```bash
npm run ops -- labels agents "security,performance"
```

--------------------------------

### Verify Skill Functionality

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Run the 'whoami' command to confirm that the skill is correctly authenticated and can access your Linear account information.

```bash
npm run ops -- whoami
```

--------------------------------

### Get User's Assigned Issues Query

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

A GraphQL query to retrieve a list of issues assigned to the authenticated user, including issue ID, title, state, and team key.

```graphql
query MyIssues {
  viewer {
    assignedIssues {
      nodes {
        id
        title
        state { name }
        team { key }
      }
    }
  }
}
```

--------------------------------

### Verification Steps for Caching Issue

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/issue-template.md

These bash commands demonstrate how to verify the caching mechanism. They include timing the operation and using an environment variable to disable the cache.

```bash
npm run build && npm test
# then, with a valid LINEAR_API_KEY:
time npm run ops -- labels validate "feature,backend"   # run 3 times back-to-back
# First run: ~400ms (network). Runs 2-3: <50ms each (cached).
LINEAR_DISABLE_LABEL_CACHE=1 npm run ops -- labels validate "feature,backend"
# Should re-fetch, ~400ms again.
```

--------------------------------

### Show Agent Recommendations for Labels

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Retrieve agent-generated recommendations for labels based on specified categories. This can help in refining label selection.

```bash
# Show agent recommendations for labels
npm run ops -- labels agents "security,performance"
```

--------------------------------

### Update Linear Issue Status via MCP or Helper Script

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Examples of updating an issue's status using the MCP server with human-readable state names or via a helper script for bulk operations.

```bash
# Via MCP - use human-readable state names
update_issue with id="issue-uuid", state="Done"
```

```bash
# Via helper script (bulk operations)
node scripts/linear-helpers.mjs update-status Done 123 124 125
```

--------------------------------

### Build Script for esbuild Bundling

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/CLAUDE.md

Demonstrates how the build script (`scripts/build.mjs`) uses esbuild to bundle TypeScript entry points into JavaScript files in the `dist/` directory. External dependencies are not inlined.

```mjs
"ops": "sh scripts/run.sh linear-ops"
```

--------------------------------

### Update Project with Content and Description

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use this mutation to update an existing project, ensuring both the full markdown content and a short description are set. The 'content' field is for the main detail panel, while 'description' is for list views and tooltips.

```graphql
# Content is what users see in the main panel!
mutation {
  projectUpdate(id: "<uuid>", input: {
    content: "# Project Title\n\nFull markdown description...",
    description: "Short 255 char summary for list views"
  }) { success }
}
```

--------------------------------

### Search for Existing Implementations

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use grep to search for specific API endpoints or function names within the source code to check for existing implementations.

```bash
# Before starting any API/feature implementation issue:

# 1. Search for existing implementations
grep -r "apiEndpoint\|functionName" src/
```

--------------------------------

### Common Commands for Linear Claude Skill

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/CLAUDE.md

Provides essential npm commands for setting up, running operations, querying GraphQL, and testing the Linear connection. Ensure LINEAR_API_KEY is set before running.

```bash
# Run setup check (validates LINEAR_API_KEY and dependencies)
npm run setup

# High-level operations CLI
npm run ops -- <command> [args]
npm run ops -- help                          # Show all commands
npm run ops -- create-issue "Project" "Title" "Desc"
npm run ops -- create-sub-issue ENG-100 "Title"
npm run ops -- labels taxonomy               # Show label taxonomy
npm run ops -- labels validate "feature,security"

# Run GraphQL query
npm run query -- "query { viewer { name } }"

# Test Linear connection
npm run test-connection
```

--------------------------------

### Check for Existing Linear Projects

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Before creating a new project, use this command to search for existing projects by name. This helps prevent duplicates.

```bash
# Check for existing projects
linear projects list | grep -i "phase\|feature-name"
```

--------------------------------

### Create Project Update

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

This script demonstrates how to create a project update using the Linear GraphQL API. It's essential to run this command whenever a project's status changes to maintain accurate records. Ensure your LINEAR_API_KEY is set in your environment variables.

```javascript
node --experimental-fetch -e "
const PROJECT_ID = '<uuid>';

const update = `## Status: In Progress 🚀

**Date:** $(date '+%Y-%m-%d')

### Completed
- ✅ Task 1 done
- ✅ Task 2 done

### In Progress
- 🔄 Task 3 in progress

### Up Next
- 📝 Task 4 pending
`;

const mutation = `mutation {
  projectUpdateCreate(input: {
    projectId: \"${PROJECT_ID}\",
    body: ${JSON.stringify(update)},
    health: onTrack
  }) { success projectUpdate { url } }
}`;

fetch('https://api.linear.app/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': process.env.LINEAR_API_KEY },
  body: JSON.stringify({ query: mutation })
}).then(r => r.json()).then(d => console.log('Update created:', d.data?.projectUpdateCreate?.projectUpdate?.url));
"
```

--------------------------------

### Test GraphQL Connection

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Run a simple GraphQL query to test the connection to the Linear API.

```bash
npm run query -- "query { viewer { name } }"
```

--------------------------------

### Export Linear API Key

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Set the LINEAR_API_KEY environment variable for your current session. Replace 'lin_api_your_key_here' with your actual API key.

```bash
export LINEAR_API_KEY="lin_api_your_key_here"
```

--------------------------------

### Link Project to Initiative

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Links an existing project to a specified initiative. Partial matching for project and initiative names is supported.

```bash
npm run ops -- link-initiative <project-name> <initiative-name>
```

```bash
# Link a project to an initiative
npm run ops -- link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"
```

```bash
# Partial matching works
npm run ops -- link-initiative "Phase 8" "Q1 Goals"
```

--------------------------------

### Execute GraphQL Mutation via CLI

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Run GraphQL mutations, such as `initiativeToProjectCreate`, using the `npm run query` command. Ensure the mutation is correctly formatted as a string argument.

```bash
npm run query -- 'mutation {
  initiativeToProjectCreate(input: {
    initiativeId: "<initiative-uuid>",
    projectId: "<project-uuid>"
  }) {
    success
  }
}'
```

--------------------------------

### Show Full Label Taxonomy

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Display the complete taxonomy of labels, including categories and usage guidelines. This ensures consistent issue categorization.

```bash
# Show full taxonomy (25 labels across 3 categories)
npm run ops -- labels taxonomy
```

--------------------------------

### PR Preparation Sync Workflow

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sync.md

Use this workflow before creating a pull request to ensure all referenced issues are updated to the 'In Review' state based on the feature branch.

```bash
# Ensure all referenced issues are updated
npm run sync -- \
  --from-branch feature/search-modal \
  --state "In Review"
```

--------------------------------

### Verify Codebase Files Exist

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Before accepting an issue scope, verify if the relevant files already exist in the source code directory. This is part of codebase verification.

```bash
# Before starting "implement API" issues:
ls src/pages/api/admin/members/
```

--------------------------------

### Spawn Agent for Autonomous Sync

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Initiate an autonomous synchronization process using a Task tool. Define the sync description, prompt, and agent type.

```javascript
Task({
  description: "Sync Phase 11 to Linear",
  prompt: "Update ENG-432,433,434 to Done. Update project to completed.",
  subagent_type: "Linear-specialist"
})
```

--------------------------------

### Discover Existing API Files

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use ls to check for the existence of API files in the specified directory, confirming if the endpoints are already implemented.

```bash
# Check if files exist
ls src/pages/api/admin/members/
```

--------------------------------

### Post-Implementation Sync Workflow

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sync.md

Use this workflow after completing a feature to identify issues from git commits, bulk update their states to 'Done', update the project status, and verify the changes.

```bash
# 1. Identify issues from git commits
git log --oneline -10 | grep -oE 'ENG-[0-9]+'
```

```bash
# 2. Bulk update to Done
npm run sync -- --issues ENG-432,ENG-433,ENG-434 --state Done
```

```bash
# 3. Update project status
npm run sync -- --project "Current Phase" --state completed
```

```bash
# 4. Verify
npm run sync -- --verify ENG-432,ENG-433,ENG-434 --expected-state Done
```

--------------------------------

### Linear CLI Commands

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Use these commands when MCP tools are not available. They cover viewing, creating, updating, and commenting on issues, as well as listing issues.

```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
```

--------------------------------

### Link Existing Project to Initiative

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use the `initiativeToProjectCreate` mutation to associate an existing project with an initiative. This is useful when a project needs to be linked after creation or added to multiple initiatives.

```graphql
mutation {
  initiativeToProjectCreate(input: {
    initiativeId: "<initiative-uuid>",
    projectId: "<project-uuid>"
  }) {
    success
    initiativeToProject { id }
  }
}
```

--------------------------------

### Print Issue Template

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

This command prints the canonical template for creating issues, which can be used to seed the description for new issues.

```bash
# Print the template to seed your description
npm run ops -- create-issue --template
```

--------------------------------

### Create Project with Default Initiative

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

This option simplifies project creation by using a default initiative ID from an environment variable. Ensure LINEAR_DEFAULT_INITIATIVE_ID is set.

```typescript
// Option 2: Use environment variable for initiative
// Requires: LINEAR_DEFAULT_INITIATIVE_ID=<uuid>
const result2 = await createProjectWithDefaults({
  name: 'My Project Phase X: Name',
  shortDescription: 'Short description',
  content: '# Full content...',
  state: 'planned',
  issues: []
})
```

--------------------------------

### Read Existing Code

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use cat to read the content of existing files, such as API implementation files, to verify their completeness.

```bash
# 3. Read existing code
cat src/pages/api/admin/members/index.ts  # May already be complete!
```

--------------------------------

### List Labels using Linear API Wrapper

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Use the linear-api.mjs script to list labels for a specific team.

```bash
node scripts/linear-api.mjs list-labels --team <TEAM>
```

--------------------------------

### Create Issue using Linear API Wrapper

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Use the linear-api.mjs script to create new issues. Replace <TEAM> with your team key.

```bash
node scripts/linear-api.mjs create-issue \
  --team <TEAM> --title "New feature" --description "Details here" --priority 2
```

--------------------------------

### List Issues using Linear API Wrapper

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Use the linear-api.mjs script to list issues based on team, status, and limit.

```bash
node scripts/linear-api.mjs list-issues \
  --team <TEAM> --status "In Progress" --limit 20
```

--------------------------------

### Configure Linear MCP Server

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Configure the Linear MCP server by specifying the command, arguments, and environment variables, including the Linear API key.

```json
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.linear.app/sse"],
      "env": {
        "LINEAR_API_KEY": "your_api_key"
      }
    }
  }
}
```

--------------------------------

### Create External Resource Link

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use this GraphQL mutation to add clickable links to projects, which appear in the Resources section. Provide a valid URL, label, and project ID.

```graphql
mutation {
  entityExternalLinkCreate(input: {
    url: "https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/implementation/phase-N.md",
    label: "Implementation Doc",
    projectId: "<project-uuid>"
  }) { success }
}
```

--------------------------------

### Create External Link for Project

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Add a clickable external link to a project, such as a documentation page. Requires the project's UUID.

```graphql
mutation {
  entityExternalLinkCreate(input: {
    url: "https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/phase-1.md",
    label: "Implementation Doc",
    projectId: "<uuid>"
  }) {
    success
  }
}
```

--------------------------------

### Look up project by name

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

Searches for projects by name and returns a list of matching projects.

```APIDOC
## Look up project by name

### Description
Searches for projects by name and returns a list of matching projects.

### Method
POST

### Endpoint
https://api.linear.app/graphql

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **filter** (object) - Required - The filter object for searching projects.
  - **name** (object) - Required - Filter by project name.
    - **containsIgnoreCase** (string) - Required - The name to search for, case-insensitive.

### Request Example
```json
{
  "query": "query ProjectByName($filter: ProjectFilter!) { projects(filter: $filter, first: 10) { nodes { id name state slugId } } }",
  "variables": {
    "filter": {
      "name": {
        "containsIgnoreCase": "Phase 6A"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the project.
- **name** (string) - The name of the project.
- **state** (string) - The state of the project.
- **slugId** (string) - The slug ID of the project.

#### Response Example
```json
{
  "data": {
    "projects": {
      "nodes": [
        {
          "id": "PROJECT_ID",
          "name": "Phase 6A Project",
          "state": "Active",
          "slugId": "phase-6a"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Create Issue with Template Description

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Create a new issue within a specified project, using a multi-line description provided via heredoc and assigning labels. The `--template` flag is used to generate the description structure.

```bash
npm run ops -- create-issue "Phase X: Feature Name" "Parent task" "$(cat <<'EOF'\n## Context\nImplement the core feature with integration tests and documentation.\n\n## Acceptance Criteria\n- [ ] All API endpoints return correct responses\n- [ ] Test coverage >80% on new modules\nEOF\n)" --labels feature,backend
```

--------------------------------

### Execute GraphQL Queries with @linear/sdk

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

Run GraphQL queries using the provided TypeScript script. Ensure the LINEAR_API_KEY environment variable is set for authentication.

```bash
LINEAR_API_KEY=lin_api_xxx npm run query -- "query { viewer { id name } }"
```

--------------------------------

### Bulk Sync Issues

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Use the npm run sync command for bulk synchronization of issues to a specific state. Specify issue identifiers and the target state.

```bash
npm run sync -- --issues PROJ-101,PROJ-102,PROJ-103 --state Done
```

--------------------------------

### Check API Existence with ls

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Verify if API files exist by listing all TypeScript files within the src/pages/api directory.

```bash
ls src/pages/api/**/*.ts
```

--------------------------------

### Load API Key Configuration

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Check if the LINEAR_API_KEY is loaded using varlock. Pipe output to grep for LINEAR.

```bash
varlock load 2>&1 | grep LINEAR
```

--------------------------------

### Configure Official Linear MCP Server

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Configure your MCP settings to use the official Linear MCP server. Ensure your API key is set.

```json
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.linear.app/sse"],
      "env": { "LINEAR_API_KEY": "your_api_key" }
    }
  }
}
```

--------------------------------

### Create Issue using Linear CLI

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Use the Linear CLI to create a new issue.

```bash
linear issues create --title "Issue title"
```

--------------------------------

### Add Project Update using Linear API Wrapper

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Use the linear-api.mjs script to add an update to a project. Replace <PROJECT_UUID> with the project's UUID.

```bash
node scripts/linear-api.mjs add-project-update \
  --project <PROJECT_UUID> --body "## Status Update\n\nProgress details..." --health onTrack
```

--------------------------------

### Combined Sync for Issues and Projects

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sync.md

Execute a single command to update both issues and project states concurrently. This is useful for synchronizing related changes.

```bash
# Update issues AND project in one command
npm run sync -- \
  --issues ENG-432,ENG-433,ENG-434 \
  --state Done \
  --project "Current Phase" \
  --project-state completed
```

--------------------------------

### Directory Structure of Linear Claude Skill

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/CLAUDE.md

Illustrates the file and directory organization within the linear-claude-skill repository. Key components include API references, SDK patterns, and script utilities.

```tree
linear-claude-skill/
├── SKILL.md              # Main skill instructions (loaded by Claude Code)
├── api.md                # GraphQL API reference
├── sdk.md                # SDK automation patterns
├── sync.md               # Bulk sync patterns
├── docs/
│   └── labels.md         # Label taxonomy documentation
├── hooks/
│   └── post-edit.sh      # Auto-sync hook
├── scripts/
│   ├── run.sh            # Shared runner (dist/ with tsx fallback)
│   ├── linear-ops.ts     # CLI for high-level operations (main entry point)
│   ├── query.ts          # GraphQL query runner
│   ├── setup.ts          # Configuration validator
│   ├── sync.ts           # Bulk sync operations
│   ├── linear-api.mjs    # Direct API wrapper
│   └── lib/              # Shared utilities (imported by scripts)
│       ├── index.ts      # Re-exports all utilities
│       ├── labels.ts     # Label management (CRUD, validation)
│       ├── taxonomy*.ts  # Label taxonomy system (types, data, validation)
│       ├── agent-selection.ts  # Agent routing based on labels
│       ├── initiative.ts # Initiative linking
│       ├── lin-cli.ts    # Optional lin CLI integration (tryLin, detection, typed wrappers)
│       ├── project-template.ts # Project creation with verification
│       └── verify.ts     # Post-creation verification
```

--------------------------------

### Search Issues via GraphQL with Node.js

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/api.md

This snippet demonstrates how to search for issues using GraphQL directly via Node.js with the `--experimental-fetch` flag. Ensure your LINEAR_API_KEY is set in the environment.

```javascript
// Inline GraphQL via node --experimental-fetch
node --experimental-fetch -e "
async function searchIssues() {
  const query = `
    query {
      issues(filter: {
        team: { key: { eq: \"TEAM\" } }
        state: { type: { nin: [\"completed\", \"canceled\"] } }
      }, first: 25) {
        nodes {
          id identifier title state { name } priority
        }
      }
    }
  `;

  const res = await fetch('https://api.linear.app/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': process.env.LINEAR_API_KEY
    },
    body: JSON.stringify({ query })
  });

  const data = await res.json();
  data.data.issues.nodes.forEach(i => {
    console.log(`$${i.identifier}: $${i.title} [$${i.state.name}]`);
  });
}
searchIssues();
"
```

--------------------------------

### Varlock: Check Schema Safely

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Inspect the .env.schema file to understand environment variable requirements without exposing sensitive values. This command is safe as it only displays the schema structure.

```bash
# Check schema (safe - no values)
cat .env.schema | grep LINEAR
```

--------------------------------

### Create Project Update

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/README.md

Post a status update to a project's Updates tab. You can specify the health status as 'onTrack', 'atRisk', or 'offTrack'.

```bash
npm run ops -- create-project-update "Project Name" "## Update\n\nBody" --health onTrack
```

--------------------------------

### Check Feature Implementation with grep

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use grep to search for a specific feature name across all files in the source directory to confirm its implementation.

```bash
grep -r "featureName" src/
```

--------------------------------

### CLI Bulk Sync Project to Completed State

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sync.md

Use this command to update a project's status to 'completed' via the SDK script. Specify the project name.

```bash
# Update project status
npm run sync -- --project "Current Phase" --state completed
```

--------------------------------

### Create a Linear Issue via CLI

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Creates a new issue in Linear using the command-line interface. Requires project name, issue title, and description.

```bash
# Standard approach
npm run ops -- create-issue "Project Name" "Issue title" "Description"
```

--------------------------------

### TypeScript Script Template with Linear SDK

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/sdk.md

A basic template for a TypeScript script using the Linear SDK. It demonstrates fetching viewer information and listing in-progress issues assigned to the viewer. Ensure the LINEAR_API_KEY environment variable is set.

```typescript
#!/usr/bin/env tsx
import { LinearClient } from '@linear/sdk'

const LINEAR_API_KEY = process.env.LINEAR_API_KEY
if (!LINEAR_API_KEY) {
  console.error('LINEAR_API_KEY environment variable required')
  process.exit(1)
}

const client = new LinearClient({ apiKey: LINEAR_API_KEY })

async function main() {
  // Your automation logic
  const me = await client.viewer
  console.log(`Running as: ${me.name}`)

  // Example: Get my open issues
  const myIssues = await client.issues({
    filter: {
      assignee: { id: { eq: me.id } },
      state: { type: { eq: 'started' } }
    }
  })

  console.log(`You have ${myIssues.nodes.length} in-progress issues`)

  for (const issue of myIssues.nodes) {
    console.log(`- ${issue.identifier}: ${issue.title}`)
  }
}

main().catch(error => {
  console.error('Error:', error.message)
  process.exit(1)
})
```

--------------------------------

### Find Skipped Describe Blocks in Tests

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use grep to find 'test.describe.skip' in test files, indicating entire test suites that are skipped.

```bash
# Check why tests fail
grep -r "test.describe.skip" tests/e2e/journeys/admin/
```

--------------------------------

### Create a Linear Issue

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/SKILL.md

Use the 'create-issue' command to generate a new issue within a specified project. Provide the project name, issue title, and a detailed description.

```bash
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."
```

--------------------------------

### View Issue using Linear CLI

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/troubleshooting.md

Use the Linear CLI to view a specific issue. Replace ENG-123 with the issue identifier.

```bash
linear issues view ENG-123
```

--------------------------------

### Create Project Update (GraphQL)

Source: https://github.com/wrsmith108/linear-claude-skill/blob/main/projects.md

Use this GraphQL mutation to create a new project update. Specify the project ID, the update body in Markdown, and the project's health status.

```graphql
mutation {
  projectUpdateCreate(input: {
    projectId: "<project-uuid>",
    body: "## Status Update\n\nMarkdown content here...",
    health: onTrack
  }) {
    success
    projectUpdate {
      id
      url
      createdAt
    }
  }
}
```
Tokens:
Raw