linear

Name: linear
Author: nousresearch

github.com/nousresearchProductivity258.9k80 installsUpdated today

About linear

A skill for users managing Linear from Hermes through its GraphQL API. It provides curl examples and a zero-dependency Python CLI for querying and changing issues, projects, and documents.

Key features

01Query and search issues
02Create and update issues
03Manage teams, projects, and workflow states
04Retrieve Linear documents
05Use a zero-dependency Python CLI

Use cases

01Review issues assigned to the current user
02Filter team issues and update their status
03Create projects or comment on issues
04Find documents by title or slugId

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nousresearch/hermes-agent --skill linear

After installing, type/linearin Claude Code to confirm it loaded.

Bundled filesscripts/linear_api.py

Details

From the project README

Linear — Issue & Project Management

Manage Linear issues, projects, and teams directly via the GraphQL API using curl. No MCP server, no OAuth flow, no extra dependencies.

Setup

Get a personal API key from Linear Settings > Account > Security & access > Personal API keys (URL: https://linear.app/settings/account/security). Note: the org-level Settings > API page only shows OAuth apps and workspace-member keys, not personal keys.
Set LINEAR_API_KEY in your environment (via hermes setup or your env config)

API Basics

Endpoint: https://api.linear.app/graphql (POST)
Auth header: Authorization: $LINEAR_API_KEY (no "Bearer" prefix for API keys)
All requests are POST with Content-Type: application/json
Both UUIDs and short identifiers (e.g., ENG-123) work for issue(id:)

Base curl pattern:

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name } }"}' | python3 -m json.tool

Python helper script (ergonomic alternative)

For faster one-liners that don't need hand-written GraphQL, this skill ships a stdlib Python CLI at scripts/linear_api.py. Zero dependencies. Same auth (reads LINEAR_API_KEY).

SCRIPT=$(dirname "$(find ~/.hermes -path '*skills/productivity/linear/scripts/linear_api.py' 2>/dev/null | head -1)")/linear_api.py

python3 "$SCRIPT" whoami
python3 "$SCRIPT" list-teams
python3 "$SCRIPT" get-issue ENG-42
python3 "$SCRIPT" get-document 38359beef67c      # fetch a doc by slugId from the URL
python3 "$SCRIPT" raw 'query { viewer { name } }'

All subcommands: whoami, list-teams, list-projects, list-states, list-issues, get-issue, search-issues, create-issue, update-issue, update-status, add-comment, list-documents, get-document, search-documents, raw. Run with --help for flags.

Use the script when: you want a quick answer without crafting GraphQL. Use curl when: you need a query the script doesn't wrap, or you want to compose filters inline.

Workflow States

Linear uses WorkflowState objects with a type field. 6 state types:

Type	Description
`triage`	Incoming issues needing review
`backlog`	Acknowledged but not yet planned
`unstarted`	Planned/ready but not started
`started`	Actively being worked on
`completed`	Done
`canceled`	Won't do

Each team has its own named states (e.g., "In Progress" is type started). To change an issue's status, you need the stateId (UUID) of the target state — query workflow states first.

Priority values: 0 = None, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low

Common Queries

Get current user

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}' | python3 -m json.tool

List teams

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ teams { nodes { id name key } } }"}' | python3 -m json.tool

List workflow states for a team

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ workflowStates(filter: { team: { key: { eq: \"ENG\" } } }) { nodes { id name type } } }"}' | python3 -m json.tool

List issues (first 20)

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(first: 20) { nodes { identifier title priority state { name type } assignee { name } team { key } url } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

List my assigned issues

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { assignedIssues(first: 25) { nodes { identifier title state { name type } priority url } } } }"}' | python3 -m json.tool

Get a single issue (by identifier like ENG-123)

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issue(id: \"ENG-123\") { id identifier title description priority state { id name type } assignee { id name } team { key } project { name } labels { nodes { name } } comments { nodes { body user { name } createdAt } } url } }"}' | python3 -m json.tool

Search issues by text

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issueSearch(query: \"bug login\", first: 10) { nodes { identifier title state { name } assignee { name } url } } }"}' | python3 -m json.tool

Filter issues by state type

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(filter: { state: { type: { in: [\"started\"] } } }, first: 20) { nodes { identifier title state { name } assignee { name } } } }"}' | python3 -m json.tool

Filter by team and assignee

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(filter: { team: { key: { eq: \"ENG\" } }, assignee: { email: { eq: \"[email protected]\" } } }, first: 20) { nodes { identifier title state { name } priority } } }"}' | python3 -m json.tool

List projects

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects(first: 20) { nodes { id name description progress lead { name } teams { nodes { key } } url } } }"}' | python3 -m json.tool

List team members

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users { nodes { id name email active } } }"}' | python3 -m json.tool

List labels

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issueLabels { nodes { id name color } } }"}' | python3 -m json.tool

Common Mutations

Create an issue

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }",
    "variables": {
      "input": {
        "teamId": "TEAM_UUID",
        "title": "Fix login bug",
        "description": "Users cannot login with SSO",
        "priority": 2
      }
    }
  }' | python3 -m json.tool

Update issue status

First get the target state UUID from the workflow states query above, then:

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { stateId: \"STATE_UUID\" }) { success issue { identifier state { name type } } } }"}' | python3 -m json.tool

Assign an issue

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { assigneeId: \"USER_UUID\" }) { success issue { identifier assignee { name } } } }"}' | python3 -m json.tool

Set priority

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { priority: 1 }) { success issue { identifier priority } } }"}' | python3 -m json.tool

Add a comment

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { commentCreate(input: { issueId: \"ISSUE_UUID\", body: \"Investigated. Root cause is X.\" }) { success comment { id body } } }"}' | python3 -m json.tool

Set due date

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { dueDate: \"2026-04-01\" }) { success issue { identifier dueDate } } }"}' | python3 -m json.tool

Add labels to an issue

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { labelIds: [\"LABEL_UUID_1\", \"LABEL_UUID_2\"] }) { success issue { identifier labels { nodes { name } } } } }"}' | python3 -m json.tool

Add issue to a project

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { projectId: \"PROJECT_UUID\" }) { success issue { identifier project { name } } } }"}' | python3 -m json.tool

Create a project

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: ProjectCreateInput!) { projectCreate(input: $input) { success project { id name url } } }",
    "variables": {
      "input": {
        "name": "Q2 Auth Overhaul",
        "description": "Replace legacy auth with OAuth2 and PKCE",
        "teamIds": ["TEAM_UUID"]
      }
    }
  }' | python3 -m json.tool

Documents

Linear Documents are prose docs (RFCs, specs, notes) stored alongside issues. They have their own documents root query and document(id:) single-fetch.

Document URLs and `slugId`

Document URLs look like:

https://linear.app/<workspace>/document/<slug>-<hexSlugId>

The trailing hex segment is the slugId. Example: https://linear.app/nousresearch/document/rfc-hermes-permission-gateway-discord-38359beef67c → slugId is 38359beef67c.

Important schema detail: the Markdown body is in the content field. The ProseMirror JSON is in contentState (not contentData — that field does not exist and the API returns 400).

Fetch a document by slugId

document(id:) only accepts UUIDs. To fetch by the URL's hex slug, filter the collection:

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "query($s: String!) { documents(filter: { slugId: { eq: $s } }, first: 1) { nodes { id title content contentState slugId url creator { name } project { name } updatedAt } } }", "variables": {"s": "38359beef67c"}}' \
  | python3 -m json.tool

Or via the Python helper:

python3 scripts/linear_api.py get-document 38359beef67c

Fetch a document by UUID

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ document(id: \"11700cff-b514-4db3-afcc-3ed1afacba1c\") { title content url } }"}' \
  | python3 -m json.tool

List recent documents

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ documents(first: 25, orderBy: updatedAt) { nodes { id title slugId url updatedAt project { name } } } }"}' \
  | python3 -m json.tool

Search documents by title

Linear's schema has no searchDocuments root. Use a title-substring filter instead:

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ documents(filter: { title: { containsIgnoreCase: \"RFC\" } }, first: 25) { nodes { title slugId url } } }"}' \
  | python3 -m json.tool

Pagination

Linear uses Relay-style cursor pagination:

# First page
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(first: 20) { nodes { identifier title } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

# Next page — use endCursor from previous response
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(first: 20, after: \"CURSOR_FROM_PREVIOUS\") { nodes { identifier title } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

Default page size: 50. Max: 250. Always use first: N to limit results.

Filtering Reference

Comparators: eq, neq, in, nin, lt, lte, gt, gte, contains, startsWith, containsIgnoreCase

Combine filters with or: [...] for OR logic (default is AND within a filter object).

Typical Workflow

Query teams to get team IDs and keys
Query workflow states for target team to get state UUIDs
List or search issues to find what needs work
Create issues with team ID, title, description, priority
Update status by setting stateId to the target workflow state
Add comments to track progress
Mark complete by setting stateId to the team's "completed" type state

Rate Limits

5,000 requests/hour per API key
3,000,000 complexity points/hour
Use first: N to limit results and reduce complexity cost
Monitor X-RateLimit-Requests-Remaining response header

Important Notes

Always use terminal tool with curl for API calls — do NOT use web_extract or browser
Always check the errors array in GraphQL responses — HTTP 200 can still contain errors
If stateId is omitted when creating issues, Linear defaults to the first backlog state
The description field supports Markdown
Use python3 -m json.tool or jq to format JSON responses for readability

Comments

Markdown supported

Details

Author: nousresearch
Repository: nousresearch/hermes-agent
Category: Productivity
Installs: 80
GitHub stars: 258,865

Report

More skills

All skills

lark-base

open.feishu.cn

834.8k

Operate on Feishu Base: create tables, fields, records, and views; handle statistics, formulas/lookups, forms, dashboards, app mode (BaseApp/AppMode pages and components), Workspace directories, workflows, role permissions, and the template center (Base template categories, lists, and search). Use when encountering Base/multidimensional tables/bitable, BaseApp/AppMode, or /base/ or /app/ links. Do not use lark-apps for BaseApp; route file import/export to lark-drive and authentication/authorization to lark-shared.

lark-drive

open.feishu.cn

834.8k

Feishu cloud storage (Drive): manage Drive files and folders, including uploads/downloads, folder creation, copying/moving/deleting, viewing metadata, checking permission settings, comments/permissions/subscriptions, titles, versions, Feishu document security labels (secure labels), and local file imports. Use when users need to organize Drive folders, handle cloud storage resource URLs/tokens, identify link types/actual tokens/titles, or import Word/Markdown/Excel/CSV/PPTX/.base as docx/sheet/bitable/slides. Route doubao.com cloud storage URLs/tokens by resource path and token too; do not fall back to WebFetch. Not responsible for: editing document content (use lark-doc), spreadsheet/Base table data operations (use lark-sheets/lark-base), knowledge space node/member management (use lark-wiki), or native Markdown file read/write/patch/diff (use lark-markdown).

lark-shared

open.feishu.cn

834.5k

Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling _notice JSON.

lark-im

open.feishu.cn

833.8k

Feishu instant messaging: send and receive messages and manage group chats. Send and reply to messages, search chat history, manage group members, upload and download images and files, manage emoji reactions, send urgent notifications in-app/by SMS/by phone, send and handle Interactive Cards, and listen for card button callbacks (card.action.trigger). Use when users need to send messages, view or search chat history, download chat files, view group members, search groups, create group or topic chats, manage marker data, manage Feed pins (add/remove/search pinned conversations), manage tag data, or handle card callbacks.

linear

About linear

Key features

Use cases

Install

Details

Linear — Issue & Project Management

Setup

API Basics

Python helper script (ergonomic alternative)

Workflow States

Common Queries

Get current user

List teams

List workflow states for a team

List issues (first 20)

List my assigned issues

Get a single issue (by identifier like ENG-123)

Search issues by text

Filter issues by state type

Filter by team and assignee

List projects

List team members

List labels

Common Mutations

Create an issue

Update issue status

Assign an issue

Set priority

Add a comment

Set due date

Add labels to an issue

Add issue to a project

Create a project

Documents

Document URLs and slugId

Fetch a document by slugId

Fetch a document by UUID

List recent documents

Search documents by title

Pagination

Filtering Reference

Typical Workflow

Rate Limits

Important Notes

Comments

Document URLs and `slugId`