productivity / Work & communicate
linear
Use the `linear` CLI to search Linear, inspect issues, manage comments, list workspace metadata, and check Linear platform status.
Put it to work.
Ask your agent to use linear, or let it load the skill when your task matches the description.
Use the linear skill [Linear query, issue id, or action]Invocation syntax varies by agent. Use the skill name in your prompt, or your agent’s supported slash command.
About this skill
Use the linear CLI for Linear issue search, inspection, comments, workspace
metadata, and platform status.
flowchart LR
request[User asks about Linear] --> cli[linear CLI]
cli --> search[Search or list]
search --> issue[Fetch issue details]
issue --> decide[Summarize or modify]
decide --> comment[Comment or update]Install
npx skills@latest add smeltery/skills --skill linearThe skill expects the linear command from
@smeltery/linear-cli. If the CLI
is missing, the skill installs it from GitHub Packages when possible, or from
source as a fallback.
Setup
npm config set @smeltery:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken "$(gh auth token)"
npm install -g @smeltery/linear-cli
linear --help
linear initlinear init configures the API key used by the CLI.
Usage
Use when searching Linear, inspecting bugs or issues, posting comments, listing labels/users/teams/projects, or checking Linear platform status.
Files
SKILL.md— canonical skill definition.
Read the full SKILL.md
Linear
Use the installed linear command for Linear work when available. It returns
JSON, so prefer structured reads with jq or equivalent parsing over brittle
text scraping.
Availability
First check that the CLI exists:
linear --helpIf it is missing, install it from smeltery/linear-cli before continuing.
Prefer the published GitHub Packages install when npm is available:
npm config set @smeltery:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken "$(gh auth token)"
npm install -g @smeltery/linear-cli
linear --helpIf gh auth token is unavailable, ask the user for a GitHub token with
read:packages access and use that value for the _authToken config. Do not
print or persist the token anywhere except npm's package-auth config.
If GitHub Packages installation is unavailable but repository access works, install from source:
git clone https://github.com/smeltery/linear-cli.git
cd linear-cli
bun install
bun link
linear --helpAfter installing, continue with linear init if authentication is missing.
Do not fall back to scraping Linear HTML.
If authentication is missing or stale, run:
linear initThis prompts for a Linear API key and writes the CLI config.
Common Reads
linear search "auth bug"
linear issue ENG-123
linear issues --labels Bug
linear comments-mine
linear teams
linear labels
linear workflow-states
linear projects
linear statusUse linear issue <id> before commenting or updating so you have the current
issue title, state, assignee, labels, and comment context.
Writes
Before mutating Linear, make sure the requested target is unambiguous. Prefer
human-readable issue identifiers such as ENG-123 when the user provides them,
and resolve ambiguous search results with the user rather than guessing.
linear comment-add ENG-123 -b "Comment body"
linear comment-edit <comment-id> -b "Updated comment body"
linear comment-delete <comment-id>
linear issue-create --team <team-id> --title "Issue title"
linear issue-update ENG-123 --title "Updated title"For destructive operations such as deleting issues, comments, labels, projects, documents, webhooks, roadmaps, or initiatives, ask for explicit confirmation unless the user already gave an exact command-level instruction.
Search Flow
When the user asks you to find Linear work:
- Start broad with
linear search "<terms>"or the relevant list command. - Narrow with structured fields such as team, label, state, assignee, or priority where the CLI supports them.
- Fetch promising issues individually with
linear issue <id>. - Summarize findings with issue identifiers, titles, states, assignees, and URLs when present.
Error Handling
- CLI missing: tell the user the
linearcommand is unavailable and provide the install requirement. - Authentication failure: run or suggest
linear init. - Empty search result: say no matching Linear items were found and include the query or filters used.
- Permission failure: report the Linear error without retrying unrelated commands.
- Multiple matches for a write target: stop and ask which issue or resource to modify.