home / skills / openclaw / skills / linear-issues

linear-issues skill

safe

This skill manages Linear issues through scripts/linear.sh, enabling creation, updates, searches, comments, assignments, and status changes.

npx playbooks add skill openclaw/skills --skill linear-issues

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

1.6 KB

---
name: linear
description: Interact with Linear for issue tracking. Use when creating, updating, listing, or searching issues. Supports viewing assigned issues, changing status, adding comments, and managing tasks.
---

# Linear

Manage Linear issues via `scripts/linear.sh`.

## Setup

Store API key in `~/.clawdbot/credentials/linear.json`:
```json
{"apiKey": "lin_api_..."}
```

## Commands

```bash
# List my assigned issues
scripts/linear.sh issues --mine

# List team issues
scripts/linear.sh issues --team TEAM_ID

# Get issue details
scripts/linear.sh get CLP-123

# Search issues
scripts/linear.sh search "auth bug"

# Create issue
scripts/linear.sh create --team TEAM_ID --title "Bug: login fails" --description "Details"

# Update issue (status, title, assignee, priority)
scripts/linear.sh update CLP-123 --state STATE_ID

# Add comment
scripts/linear.sh comment CLP-123 "Fixed in PR #42"

# List teams (to get TEAM_ID)
scripts/linear.sh teams

# List states (to get STATE_ID)
scripts/linear.sh states

# List users (to get assignee ID)
scripts/linear.sh users
```

Use `--json` flag for raw API output: `scripts/linear.sh --json issues --mine`

## Workflow Examples

**Create and assign a bug:**
```bash
# Find team ID
scripts/linear.sh teams
# Create with priority 2 (high)
scripts/linear.sh create --team abc123 --title "Critical: API down" --priority 2
```

**Move issue to In Progress:**
```bash
# Find state ID
scripts/linear.sh states
# Update
scripts/linear.sh update CLP-45 --state xyz789
```

See [references/api-examples.md](references/api-examples.md) for GraphQL details.

Overview

This skill integrates with Linear to manage issue tracking from the command line. It supports creating, updating, listing, searching, and commenting on issues, plus inspecting teams, states, and users. Credentials are read from a local credentials file so API access remains secure.

How this skill works

The skill wraps Linear API operations in simple shell commands (scripts/linear.sh) that accept flags for team, state, assignee, priority, and output format. Use --json to return raw API JSON for automation. Credentials are stored in ~/.clawdbot/credentials/linear.json and the script issues GraphQL requests under the hood.

When to use it

Create new issues and assign them to a team or user from a CI script or local shell.
List issues assigned to you or your team to review current workload.
Search issues by keyword to find related bugs, tasks, or features.
Update issue state, priority, or assignee during triage or sprint planning.
Add comments to issues to record fixes, PR links, or status updates.

Best practices

Keep your Linear API key in ~/.clawdbot/credentials/linear.json and restrict file permissions.
Use teams, states, and users commands to fetch IDs before create/update operations.
Use --json output when integrating with scripts or CI pipelines for reliable parsing.
Include clear titles and structured descriptions when creating issues to speed triage.
Prefer numeric priority and explicit state IDs to avoid ambiguous updates.

Example use cases

Create a high-priority incident and assign it to the on-call team via scripts/linear.sh create --team TEAM_ID --title "Critical: API down" --priority 2
List all issues assigned to the current user with scripts/linear.sh issues --mine to prepare a daily standup.
Search for related authentication bugs with scripts/linear.sh search "auth bug" to group duplicates.
Move a ticket into In Progress by looking up state IDs and running scripts/linear.sh update ISSUE_ID --state STATE_ID
Post a short status comment referencing a PR: scripts/linear.sh comment ISSUE_ID "Fixed in PR #42"

FAQ

Where do I store the API key?

Put the key in ~/.clawdbot/credentials/linear.json as {"apiKey": "lin_api_..."} and secure the file with proper permissions.

How do I get team, state, or user IDs?

Run scripts/linear.sh teams, scripts/linear.sh states, or scripts/linear.sh users to list available IDs before creating or updating issues.