linear-native-node

by jwestburg

Install this Skill

curl -fsSL -o linear-native-node.zip https://skill.seembox.com/api/v1/skills/linear-native-node/download && unzip linear-native-node.zip

Download linear-native-node.zip

SKILL.md About

---
name: linear-native-node
description: Direct Linear workspace helper using Linear's GraphQL API from native Node.js. Use when creating, listing, updating, commenting on, summarizing, or looking up Linear issues, projects, teams, workflow states, priorities, standup notes, or branch names. Can write to Linear via create/comment/status/priority/project-create commands. Reads LINEAR_API_KEY from the process environment only; no OAuth gateway, bash, Python, npm dependencies, or third-party service.
---

# Linear Native Node

Use `scripts/linear.mjs` to talk directly to Linear's GraphQL API at `https://api.linear.app/graphql`.

Native Node 18+. Zero npm dependencies. Windows, macOS, and Linux friendly. No bash, Python, OAuth gateway, browser login, or third-party proxy.

## Security behavior

- Reads `LINEAR_API_KEY` and optional `LINEAR_DEFAULT_TEAM` from the process environment only.
- Does not read credential files or `~/.openclaw/.env`.
- Sends GraphQL requests only to `https://api.linear.app/graphql`.
- Does not write files, log secrets, or print the API key.
- Write commands are explicit commands (`create`, `comment`, `status`, `priority`, `project-create`); read-only commands are the default usage pattern.

## Why this skill

This is the private/direct version of common Linear helper workflows:

- Keeps API access between this machine and Linear only.
- Uses `LINEAR_API_KEY` from the process environment only; never print the key.
- Avoids bash-oriented helpers that break on Windows.
- Avoids third-party OAuth/gateway tools; there is no Maton-style intermediary.
- Keeps a tight auditable scope: viewer/org/team lookup, issue list/read/create/update/comment, practical personal summaries, and branch names.

## Setup

Create a Linear API key at:

```text
https://linear.app/settings/api
```

PowerShell session-only setup:

```powershell
$env:LINEAR_API_KEY = "<your-linear-key>"
$env:LINEAR_DEFAULT_TEAM = "TEAM"
```

macOS/Linux shell session-only setup:

```bash
export LINEAR_API_KEY="<your-linear-key>"
export LINEAR_DEFAULT_TEAM="TEAM"
```
`LINEAR_DEFAULT_TEAM` is optional. Examples below use `TEAM` and `TEAM-123` as placeholders; replace them with your Linear team key and issue identifiers.

## Run

From PowerShell, bash, zsh, or any shell with Node on PATH:

```bash
node "<skill-dir>/scripts/linear.mjs" help
node "<skill-dir>/scripts/linear.mjs" viewer
node "<skill-dir>/scripts/linear.mjs" issues --team TEAM --mine --limit 10
```

From OpenClaw, use the bundled script directly:

```text
Run: node <skill-dir>/scripts/linear.mjs my-issues --team TEAM
Run: node <skill-dir>/scripts/linear.mjs create TEAM "Fix login error" "Users see an error after submitting credentials." --priority high
```

Add `--json` to commands when structured output is useful.

## Commands

Read-only:

```text
help
viewer
organization
teams
projects [--team TEAM] [--limit N]
states <TEAM_KEY>
issues [--team TEAM] [--mine] [--state STATE] [--limit N]
my-issues [--team TEAM] [--state STATE] [--limit N]
my-todos [--team TEAM] [--limit N]
urgent [--team TEAM] [--mine] [--limit N]
standup [--team TEAM] [--limit N]
issue <IDENTIFIER>
branch <IDENTIFIER>
```

Writes to Linear:

For agent use, perform write commands only when the user clearly requested the Linear change or explicitly approved it.

## Examples

List teams, projects, and states:

```powershell
node "<skill-dir>/scripts/linear.mjs" teams
node "<skill-dir>/scripts/linear.mjs" projects --team TEAM --limit 20
node "<skill-dir>/scripts/linear.mjs" states TEAM
```

Create a project:

```powershell
node "<skill-dir>/scripts/linear.mjs" project-create TEAM "Release Planning" "Track launch scope and milestones."
```

List issues:

```powershell
node "<skill-dir>/scripts/linear.mjs" issues --team TEAM --limit 20
node "<skill-dir>/scripts/linear.mjs" issues --team TEAM --mine --state "In Progress"
node "<skill-dir>/scripts/linear.mjs" my-issues --team TEAM
node "<skill-dir>/scripts/linear.mjs" my-todos --team TEAM
node "<skill-dir>/scripts/linear.mjs" urgent --team TEAM
```

Read and update an issue:

```powershell
node "<skill-dir>/scripts/linear.mjs" issue TEAM-123
node "<skill-dir>/scripts/linear.mjs" comment TEAM-123 "Added reproduction notes."
node "<skill-dir>/scripts/linear.mjs" status TEAM-123 "In Progress"
node "<skill-dir>/scripts/linear.mjs" priority TEAM-123 urgent
```

Create an issue:

```powershell
node "<skill-dir>/scripts/linear.mjs" create TEAM "Fix notification delivery" "Notifications are delayed for some users." --priority high
```

Generate a GitHub-friendly branch name from the Linear issue title:

```powershell
node "<skill-dir>/scripts/linear.mjs" branch TEAM-123
```

Get machine-readable output:

```powershell
node "<skill-dir>/scripts/linear.mjs" my-issues --team TEAM --json
```

## Notes

- Prefer issue identifiers like `TEAM-123`; the script resolves them before updates that need Linear IDs.
- Priority values map to Linear's native values: `urgent`, `high`, `medium`, `low`, `none`.
- Missing keys, 401/403 responses, GraphQL errors, missing teams/states, and invalid priorities produce clear stderr errors with non-zero exit codes.
- `standup` summarizes assigned active and recently completed issues; it is intentionally lightweight, not a time tracker.

## Changelog

- `1.0.6`: Package-only cleanup: publish runtime files only (`SKILL.md` and `scripts/linear.mjs`) and keep the local test harness out of the public archive.
- `1.0.5`: Fix GraphQL variable construction in issue list queries (`issues`, `my-issues`, `my-todos`, `urgent`, `standup`) so only actually used variables are declared and passed.

_meta.json Metadata

{
  "ownerId": "kn78bc0rnqe8pnvd4azdnjvmmd858m3q",
  "publishedAt": 1778164905074,
  "slug": "linear-native-node",
  "version": "1.0.7"
}