Agent skill

linear

Use when managing Linear issues, creating tasks from conversations, tracking work items, or querying project status - provides bash scripts to interact with Linear's GraphQL API without writing queries directly (project, gitignored)

View SKILL.md on GitHub Repository
Stars 11
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/dbmcco/claude-agent-toolkit/tree/main/skills/linear

SKILL.md

Linear Integration

Overview

Comprehensive Linear API integration through simple bash scripts. All scripts handle GraphQL API calls internally - you just provide arguments. Covers the full API: issues, comments, labels, cycles, projects, attachments, and team management.

Core principle: Agents manage Linear without learning GraphQL syntax or API details.

When to Use

  • Creating issues from conversation context
  • Documenting implementation progress via comments
  • Organizing work with labels and cycles
  • Tracking projects and sprint planning
  • Linking external resources (PRs, docs, designs)
  • Querying team structure and workflow states

Environment Setup

Required variables (set in /experiments/skills/.env):

bash
LINEAR_API_KEY=lin_api_xxx
LINEAR_TEAM_ID=xxx-xxx-xxx
LINEAR_TEAM_KEY=LFW
LINEAR_ORG_URL=lightforgeworks

Scripts automatically source the .env file from parent directory.

Quick Reference

Issue Management

Script Purpose Key Arguments
linear-create-issue.sh Create new issue --title, --description, --priority
linear-list-issues.sh List team issues with pagination --state, --assignee-id, --after
linear-update-issue.sh Update issue --issue-id, --state-id, --title
linear-search.sh Search issues with pagination --query, --after

Comments (Essential for AI Documentation)

Script Purpose Key Arguments
linear-create-comment.sh Add comment to issue --issue-id, --body
linear-list-comments.sh List issue comments --issue-id, --limit
linear-update-comment.sh Update comment --comment-id, --body
linear-delete-comment.sh Delete comment --comment-id

Labels (Organization)

Script Purpose Key Arguments
linear-create-label.sh Create team label --name, --description, --color
linear-list-labels.sh List team labels --limit
linear-assign-label.sh Add label to issue --issue-id, --label-id
linear-remove-label.sh Remove label from issue --issue-id, --label-id

Cycles (Sprint Planning)

Script Purpose Key Arguments
linear-create-cycle.sh Create sprint cycle --starts-at, --ends-at, --name
linear-list-cycles.sh List team cycles --include-completed, --limit
linear-update-cycle.sh Update cycle --cycle-id, --completed-at

Projects

Script Purpose Key Arguments
linear-create-project.sh Create project --name, --description, --color
linear-list-projects.sh List team projects --limit

Attachments (External Links)

Script Purpose Key Arguments
linear-create-attachment.sh Link external resource --issue-id, --url, --title
linear-list-attachments.sh List issue attachments --issue-id
linear-delete-attachment.sh Delete attachment --attachment-id

ID Discovery (Essential)

Script Purpose Key Arguments
linear-list-states.sh Get workflow state IDs --limit
linear-list-users.sh Get team member IDs --limit
linear-get-viewer.sh Get authenticated user info None

Common Workflows

Create Issue from Conversation

bash
# Create issue with conversation context
scripts/linear-create-issue.sh \
  --title "Implement user authentication" \
  --description "Based on discussion: Need OAuth2 integration with Google and GitHub providers" \
  --priority 2

Document Implementation Progress

bash
# Add progress comment to issue
scripts/linear-create-comment.sh \
  --issue-id "abc-123" \
  --body "Implemented OAuth2 flow. Tests passing. Ready for review."

# Link PR as attachment
scripts/linear-create-attachment.sh \
  --issue-id "abc-123" \
  --url "https://github.com/org/repo/pull/456" \
  --title "PR: OAuth2 Implementation"

Organize Work

bash
# Get label IDs
scripts/linear-list-labels.sh

# Assign labels to categorize
scripts/linear-assign-label.sh \
  --issue-id "abc-123" \
  --label-id "label-backend"

scripts/linear-assign-label.sh \
  --issue-id "abc-123" \
  --label-id "label-security"

Update Issue State

bash
# First get state IDs
scripts/linear-list-states.sh

# Then update to "In Progress"
scripts/linear-update-issue.sh \
  --issue-id "abc-123" \
  --state-id "state-in-progress-id"

Sprint Planning

bash
# Create cycle
scripts/linear-create-cycle.sh \
  --name "Sprint 42" \
  --starts-at "2025-11-01" \
  --ends-at "2025-11-14" \
  --description "Q4 authentication features"

# Assign issue to cycle
scripts/linear-update-issue.sh \
  --issue-id "abc-123" \
  --cycle-id "cycle-id-from-above"

Pagination for Large Teams

bash
# Get first page
RESULT=$(scripts/linear-list-issues.sh --state "Backlog" --limit 50)

# Check if more pages
HAS_NEXT=$(echo "$RESULT" | jq -r '.pageInfo.hasNextPage')

if [ "$HAS_NEXT" = "true" ]; then
  CURSOR=$(echo "$RESULT" | jq -r '.pageInfo.endCursor')

  # Get next page
  scripts/linear-list-issues.sh --state "Backlog" --limit 50 --after "$CURSOR"
fi

Output Format

All scripts return JSON with relevant data:

Create/Update Operations:

json
{
  "success": true,
  "id": "entity-id",
  "identifier": "LFW-123",
  "title": "Entity title",
  "url": "https://linear.app/..."
}

List Operations with Pagination:

json
{
  "issues": [...],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "cursor-string-for-next-page"
  }
}

Common Patterns

AI Agent Workflow

  1. Create issue from user conversation
  2. Add comment documenting implementation approach
  3. Update state to "In Progress"
  4. Add attachment linking to PR/branch
  5. Add comment with completion notes
  6. Update state to "Done"

ID Discovery Pattern

bash
# Always get IDs first before operations
STATES=$(scripts/linear-list-states.sh)
IN_PROGRESS_ID=$(echo "$STATES" | jq -r '.[] | select(.name=="In Progress") | .id')

USERS=$(scripts/linear-list-users.sh)
MY_ID=$(echo "$USERS" | jq -r '.[] | select(.email=="me@example.com") | .id')

# Then use in operations
scripts/linear-update-issue.sh \
  --issue-id "abc-123" \
  --state-id "$IN_PROGRESS_ID" \
  --assignee-id "$MY_ID"

Common Mistakes

Missing environment variables

  • Scripts check for LINEAR_API_KEY and LINEAR_TEAM_ID
  • Error message shows which variables are missing

Using Linear CLI syntax

  • ❌ Don't: linear issue create "Title"
  • ✅ Do: linear-create-issue.sh --title "Title"

Forgetting to get IDs first

  • State IDs, project IDs, user IDs, label IDs must be fetched
  • Use list scripts to discover IDs before operations

Not handling pagination

  • Teams with 100+ issues need pagination
  • Always check pageInfo.hasNextPage in list operations
  • Use --after parameter with endCursor for next page

Not documenting work

  • Comments are essential for AI agents to track progress
  • Always add comments when making significant changes
  • Link related resources (PRs, docs) via attachments

Anti-Patterns

Creating issues without context

bash
# ❌ Bad: Minimal context
scripts/linear-create-issue.sh --title "Fix bug"

# ✅ Good: Rich context from conversation
scripts/linear-create-issue.sh \
  --title "Fix authentication timeout on mobile Safari" \
  --description "Users report auth timeout after 30s on iOS Safari. Need to increase token TTL and add retry logic." \
  --priority 1

Silent updates

bash
# ❌ Bad: Update state without documentation
scripts/linear-update-issue.sh --issue-id "abc-123" --state-id "done"

# ✅ Good: Document completion
scripts/linear-create-comment.sh \
  --issue-id "abc-123" \
  --body "Implemented fix. Increased token TTL to 120s and added exponential backoff. All tests passing."

scripts/linear-update-issue.sh --issue-id "abc-123" --state-id "done"

Ignoring pagination

bash
# ❌ Bad: Only get first 50 issues
scripts/linear-list-issues.sh --limit 50

# ✅ Good: Handle all pages
while true; do
  RESULT=$(scripts/linear-list-issues.sh --limit 50 ${CURSOR:+--after "$CURSOR"})
  echo "$RESULT" | jq -r '.issues[]'

  HAS_NEXT=$(echo "$RESULT" | jq -r '.pageInfo.hasNextPage')
  [ "$HAS_NEXT" = "false" ] && break

  CURSOR=$(echo "$RESULT" | jq -r '.pageInfo.endCursor')
done

Script Location

All scripts in: /Users/braydon/projects/experiments/skills/linear/scripts/

Can be called from any directory - they auto-source the parent .env file.

API Coverage

This skill covers the full Linear GraphQL API:

  • ✅ Issues (CRUD, search, filtering)
  • ✅ Comments (CRUD)
  • ✅ Labels (CRUD, assignment)
  • ✅ Cycles (CRUD, sprint management)
  • ✅ Projects (CRUD)
  • ✅ Attachments (CRUD, external linking)
  • ✅ Workflow States (query)
  • ✅ Team Members (query)
  • ✅ Authenticated User (query)
  • ✅ Pagination (cursor-based)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

dbmcco/claude-agent-toolkit

gemini-cli-extension-porting

Use when porting beads or superpowers workflows into Gemini CLI extensions or designing Gemini CLI command prompts that emulate multi-step agent workflows - covers extension layout, GEMINI.md context, command TOML patterns, and enforceable guardrails (tests/CI/pre-commit)

11 2
Explore
dbmcco/claude-agent-toolkit

rifts

11 2
Explore
dbmcco/claude-agent-toolkit

obsidian-vault-intelligence

Use when working with Obsidian vault via MCP - covers effective search patterns, note operations, intelligent queries, and cross-reference strategies for knowledge extraction

11 2
Explore
dbmcco/claude-agent-toolkit

keynote-slides

Build Keynote-style single-file HTML slide decks with brand-ready templates, minimal navigation, and Gemini nano banana media generation. Includes Narrative Engine integration for framework-driven deck creation with 17 proven storytelling structures and 5-agent review panel. Use when creating or editing slide decks, transforming content into presentations, or generating slide visuals.

11 2
Explore
dbmcco/claude-agent-toolkit

google-docs-automation

Use when automating Google Workspace (Docs, Sheets, Slides) operations - covers authentication, common patterns, and best practices for gspread and googleapiclient

11 2
Explore
dbmcco/claude-agent-toolkit

workspace-cleanup

Intelligent workspace cleanup using multi-signal detection (similarity, timestamps, references) to identify and archive clutter with two-stage safety review

11 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results