Skip to main content
Agent skill

Linear

Operate on Linear issues — read, create, comment, and close — through a Linear workspace the user's team has bound to Nuphos via OAuth. Use whenever the user asks to open/track/close a Linear issue, file a ticket for an incident, comment on an issue, or check issue status. Nuphos backend hands the agent a workspace access token; the included stateless helpers call api.linear.app/graphql directly.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Linear when an AI agent needs a reusable SKILL.md workflow for this job: Operate on Linear issues — read, create, comment, and close — through a Linear workspace the user's team has bound to Nuphos via OAuth. Use whenever the user asks to open/track/close a Linear issue, file a ticket for an incident, comment on an issue, or check issue status. Nuphos backend hands the agent a workspace access token; the included stateless helpers call api.linear.app/graphql directly.

When not to use it

Skip Linear when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/linear
# Save SKILL.md to ~/.claude/skills/linear/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/linear/SKILL.md. For a shared project, commit the folder at .claude/skills/linear/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Linear skill for this task: Use Linear when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# linear

## Session isolation

Keep CLI credentials and settings inside the current session's `HOME` (`NUPHOS_SESSION_HOME`) and respect the supplied CLI config environment variables. Do not copy another session's or the runtime owner's credentials. Without `NUPHOS_SESSION_HOME`, CLI defaults may use shared runtime configuration; be aware of the affected scope.

Changing runtime-global settings is possible, but strongly discouraged unless the user understands the impact on other sessions and explicitly requests it. Explain the shared scope first; do not unset session isolation variables, write to the runtime owner's home, use a shared OS credential store, or modify shared shell startup files as routine setup. This is configuration isolation, not an OS security boundary.

Use this skill to read or change Linear issues through a workspace already bound to the user's Nuphos team.

## Important execution model

Every shell tool call starts in a fresh process. Shell functions, sourced env files, and exported variables from an earlier call do **not** persist. Never define a `lin()` function or probe guessed token variable names. The helpers in `skills/linear/scripts/` load `~/.linear/nuphos.env` on every invocation.

## Setup

The session's credential context normally lists each enabled Linear workspace with an exact `setupCommand`. When it does, use that command directly. Do not list workspaces again and do not inspect the token or test it with a separate viewer query.

```bash bash skills/linear/scripts/setup-credentials.sh <teamId> <bindingId> ```

Identity: when the turn's member connected a Personal Credential for this workspace, Linear calls are authored by their own account. That member is the sender of a member's message, or the session owner for automated turns. Otherwise they are authored by the team's Linear app. Add `--team` as a third argument to use the app identity on purpose.

Without a team workspace binding: when `list_credentials` lists a selected `personal` / `linear` entry, the conversation owner chose their own Linear account for this conversation. Load it with `bash skills/linear/scripts/setup-credentials.sh <teamId> personal`.

Only if no Linear workspace appears in the session credential context, tell the user to enable one for this session or have an administrator connect it under Cloud → Integrations → Add → Linear. Do not try to discover or bind an unlisted workspace.

The setup command writes a private env file. Never print or paste its token.

## Fast path: create and assign an issue

After setup, fetch issue-routing context with bounded, paginated GraphQL requests:

```bash # Use English aliases when the user named someone in another script/language. bash skills/linear/scripts/issue-context.sh 'matthew|mathew|matt' ```

This filters active users on the server by name, display name, or email, then loads workspace teams in separate paginated queries to stay within Linear's query complexity limit. Up to 10 pipe-separated aliases are accepted per call. Team memberships are loaded only for a unique search match. An empty, ambiguous, or unmatched search returns candidates with `teams: null` (not loaded); no match falls back to all active users. Re-run with the selected member's exact email to resolve memberships, and confirm identity rather than assigning a candidate arbitrarily. Use it instead of separate viewer, users, teams, membership, or token-scope calls.

Pick the team from the user's explicit request or strong conversation context. If multiple teams remain genuinely plausible, ask rather than guessing. Do not query workflow states or invent a priority merely to create an issue: Linear's team defaults are sufficient unless the user requested a particular state or priority.

Create the issue in one shell call. Put the description directly on stdin; do not stage a markdown file just to draft it. After creating the issue, `issue-create.sh` automatically creates an idempotent Linear attachment titled `Nuphos session`. This puts the current session URL in Linear's native **Links** field, not in the description. Do not manually add that URL to the description.

```bash bash skills/linear/scripts/issue-create.sh \ --team '<teamId>' \ --assignee '<userId>' \ --title '<title>' <<'MARKDOWN' ## Summary

Relevant context, evidence, links, and concrete follow-ups. MARKDOWN ```

Optional flags are `--state <stateId>`, `--priority <0-4>`, and `--description-file <path>`. Use them only when the user or existing context actually specifies those values. Report the returned identifier and URL.

## Generic GraphQL helper

For reads, comments, updates, and closes, send a JSON GraphQL payload through the stateless helper. It automatically loads the correct env file and fails on HTTP or GraphQL errors.

```bash bash skills/linear/scripts/graphql.sh <<'JSON' {"query":"query($id:String!){ issue(id:$id){ id identifier title url state{name type} } }","variables":{"id":"EX-123"}} JSON ```

### Search open issues

```bash bash skills/linear/scripts/graphql.sh <<'JSON' {"query":"query($team:ID){ issues(filter:{team:{id:{eq:$team}},state:{type:{nin:[\"completed\",\"canceled\"]}}},first:25){nodes{id identifier title url state{name}}}}","variables":{"team":"<teamId>"}} JSON ```

### Comment

```bash bash skills/linear/scripts/graphql.sh <<'JSON' {"query":"mutation($input:CommentCreateInput!){commentCreate(input:$input){success comment{id}}}","variables":{"input":{"issueId":"<issueId>","body":"<comment>"}}} JSON ```

### Close or move an issue

Only query workflow states when the requested operation needs a specific state:

```bash bash skills/linear/scripts/graphql.sh <<'JSON' {"query":"query($team:ID){workflowStates(filter:{team:{id:{eq:$team}}}){nodes{id name type}}}","variables":{"team":"<teamId>"}} JSON ```

Then update with the selected completed/canceled state:

```bash bash skills/linear/scripts/graphql.sh <<'JSON' {"query":"mutation($id:String!,$input:IssueUpdateInput!){issueUpdate(id:$id,input:$input){success issue{id identifier state{name type}}}}","variables":{"id":"<issueId>","input":{"stateId":"<stateId>"}}} JSON ```

## Safety and errors

- Reads are safe. Before a mutation, summarize workspace/team and the intended change unless the user already explicitly requested it. - Match a named team or assignee; do not silently substitute a different one. - Never echo `LINEAR_ACCESS_TOKEN` or include it in an issue/comment. - A setup 403 means the caller is outside the binding allow-list; ask an admin to grant access or enable a different workspace. - A setup 404 means the binding was removed; ask the user to update the session's selected credentials. - An authentication error from `graphql.sh` means the stored grant was revoked. Re-run the exact setup command once in case the backend can refresh it. If it still fails, ask an admin to reconnect the workspace; do not loop retries. - `success:false` means the mutation input was rejected. Reuse `issue-context.sh` or query the required state, then retry once with corrected IDs.

## Link work to the current conversation

After creating or adopting a PR or issue for the current task, use `bind_session_resource` when that native tool is available. This registers a verified resource link in the session sidebar. For GitHub pass `provider: github`, the selected `installationId`, `repository` (`owner/repo`) and PR `number`. For Linear pass `provider: linear`, the selected binding's `workspaceId` and `issueId` (UUID or identifier). This is separate from Linear's Nuphos session attachment; retain that attachment too. Do not bind unrelated search results.

Bound GitHub PR events durably wake this conversation with its existing permissions. A receipt means the binding exists, not that an event was delivered or that checks passed. Never promise a sandbox watcher will survive the turn. Use `unlink_session_resource` when asked to stop following a resource; it does not modify the external PR or issue. An event restores an archived session.

Intended uses

  • Use Linear when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.