Linear Agent Skill

A single-file, zero-dependency CLI for the Linear GraphQL API. 30 commands covering issues, cycles, projects, milestones, notifications, and more — in one bash script.

Built for AI coding agents (Antigravity, Claude Code, Cursor, Gemini CLI), but works great as a standalone CLI too.

Why This Exists

Feature	This Skill	Other Linear Skills
Dependencies	None (bash + curl + jq)	Node.js + npm + TypeScript
Install	Copy one file	git clone + npm install + npm run build
Startup	Instant	~50ms (pre-compiled) to ~1s (tsx)
Agent Support	Any agent	Usually Claude Code only
Commands	30	~10-15
File Count	1 script	15+ files

Quick Start

1. Get Your API Key

Go to Linear → Settings → Security & access → Personal API keys and create a new key.

# Add to your shell profile
echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc
source ~/.zshrc

2. Install

# Option A: Clone the repo
git clone https://github.com/Watermelon4000/linear-agent-skill.git

# Option B: Just grab the script
curl -o linear.sh https://raw.githubusercontent.com/Watermelon4000/linear-agent-skill/main/scripts/linear.sh

3. Setup (Run Once)

Auto-discovers your workspace — team, user, workflow states, and labels:

bash scripts/linear.sh setup

This creates ~/.linear-agent.json with your workspace config. All state/label names (e.g., "Todo", "Bug") are automatically mapped to UUIDs.

4. Use It

bash scripts/linear.sh create --title "Fix login bug" --state "Todo" --priority 2
bash scripts/linear.sh list --state "In Progress"
bash scripts/linear.sh batch-create --file tasks.json

Commands (30 total)

Category	Commands
Issues	create, update, delete, list, search, get, comment, reminder
Batch	batch-create, batch-update
Relations	relation-create, relation-delete
Cycles	cycle-create, cycle-list, cycle-update, cycle-archive
Projects	create-project, project-update, project-updates
Milestones	milestone-create, milestone-list, milestone-delete
Notifications	notifications, notification-count, notification-read-all, notification-archive-all
Data	sync, archive, graphql
Setup	setup

Run bash scripts/linear.sh help for full usage.

Use as an AI Skill

Drop the SKILL.md and scripts/ directory into your agent's skill folder:

• Antigravity: ~/.gemini/antigravity/skills/linear-agent-skill/
• Claude Code: ~/.claude/skills/linear/
• Cursor: Reference in your .cursorrules

The agent will automatically discover available commands from SKILL.md.

Batch Operations

Batch Create

[
  {"title": "Task 1", "state": "Todo", "priority": 3, "dueDate": "2026-06-01"},
  {"title": "Task 2", "state": "Backlog", "label": "Bug"}
]

bash scripts/linear.sh batch-create --file tasks.json

Batch Update

# CLI mode
bash scripts/linear.sh batch-update --ids "id1,id2,id3" --state "Done"

# File mode
bash scripts/linear.sh batch-update --file update.json

Prerequisites

• bash (macOS/Linux built-in)
• curl (usually pre-installed)
• jq (install guide)
• python3 (for batch operation JSON transforms)

License

MIT — see LICENSE.

Author

Zihong Chen (小西瓜)