domains / software-engineering / linear-issue-management / linear

linear

Skill card

combined

The copies describe two different integration paths for the same task. The openai and composio copies are identical and rely on the Linear MCP server with a structured 5-step workflow (setup, clarify, select tools, batch execute, summarize). The LeoYeAI copy relies on a local bash script (linear.sh) and the Linear GraphQL API, and it adds a detailed Git worktree workflow that ties Linear branch names to GitHub PR automation. Because the LeoYeAI copy contains material steps (bash commands, worktree creation, branch naming) that the MCP copies lack, and the MCP copies contain a structured tool-calling workflow that the bash copy lacks, crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

# Linear

Manage issues, projects, and team workflows in Linear. Choose the integration method based on your environment: **MCP Server** (for Codex/agent-native tool calling) or **Bash Script** (for CLI/terminal workflows).

## Method 1: Linear MCP Server (Codex/Agent)

### Prerequisites
- Linear MCP server connected via OAuth.
- Access to relevant Linear workspace, teams, and projects.

### Setup (if not configured)
1. Add MCP: `codex mcp add linear --url https://mcp.linear.app/mcp`
2. Enable remote MCP: Set `[features] rmcp_client = true` in `config.toml` or run `codex --enable rmcp_client`.
3. Login: `codex mcp login linear`
4. Restart Codex if prompted.

*Windows/WSL Note:* If connection errors occur, configure MCP to run via WSL:
```json
{"mcpServers": {"linear": {"command": "wsl", "args": ["npx", "-y", "mcp-remote", "https://mcp.linear.app/sse", "--transport", "sse-only"]}}}
```

### Workflow
1. **Clarify:** Define goal (triage, sprint planning, etc.) and scope (team, project, priority).
2. **Select Tools:** Identify required MCP tools (e.g., `list_issues`, `create_issue`). Confirm identifiers (Issue ID, Team Key).
3. **Execute:** Batch calls logically. Read first to build context, then create/update. Explain grouping logic for bulk ops.
4. **Summarize:** Report results, gaps, and next actions.

### Available Tools
- **Issues:** `list_issues`, `get_issue`, `create_issue`, `update_issue`, `list_my_issues`, `list_issue_statuses`, `list_issue_labels`, `create_issue_label`
- **Projects/Teams:** `list_projects`, `get_project`, `create_project`, `update_project`, `list_teams`, `get_team`, `list_users`
- **Docs/Collab:** `list_documents`, `get_document`, `search_documentation`, `list_comments`, `create_comment`, `list_cycles`

## Method 2: Bash Script (CLI)

### Setup
```bash
export LINEAR_API_KEY="your-api-key"
export LINEAR_DEFAULT_TEAM="TEAM" # Optional
```

### Quick Commands
- **My Stuff:** `linear.sh my-issues`, `linear.sh my-todos`, `linear.sh urgent`
- **Browse:** `linear.sh teams`, `linear.sh team <KEY>`, `linear.sh project <name>`, `linear.sh issue <ID>`, `linear.sh branch <ID>`
- **Actions:** `linear.sh create <TEAM> "Title" ["Desc"]`, `linear.sh comment <ID> "Text"`, `linear.sh status <ID> <status>`, `linear.sh assign <ID> <user>`, `linear.sh priority <ID> <level>`
- **Overview:** `linear.sh standup`, `linear.sh projects`

### Git Workflow (Linear ↔ GitHub)
**Always use Linear-derived branch names** for automatic status tracking.

1. **Get Branch Name:**
   ```bash
   BRANCH=$(linear.sh branch TEAM-212)
   # Returns: dev/team-212-fix-auth-timeout-bug
   ```
2. **Create Worktree:**
   ```bash
   cd /path/to/repo
   git checkout main && git pull origin main
   git worktree add .worktrees/team-212 -b "$BRANCH" origin/main
   cd .worktrees/team-212
   ```
3. **Work & Push:**
   ```bash
   # Make changes
   git add -A && git commit -m "fix: implement TEAM-212"
   git push -u origin "$BRANCH"
   gh pr create --title "TEAM-212: <title>" --body "Closes TEAM-212"
   ```

**⚠️ Never modify files on main.** All changes happen in worktrees.

## Priority Levels
| Level | Value | Use for |
|-------|-------|---------|
| urgent | 1 | Production issues, blockers |
| high | 2 | This week, important |
| medium | 3 | This sprint/cycle |
| low | 4 | Nice to have |
| none | 0 | Backlog, someday |

## Practical Workflows
- **Sprint Planning:** Review open issues, pick top items by priority, create a new cycle with assignments.
- **Bug Triage:** List critical/high-priority bugs, rank by impact, move top items to "In Progress."
- **Documentation Audit:** Search docs, open labeled "documentation" issues for gaps.
- **Team Workload Balance:** Group active issues by assignee, flag high load, suggest redistributions.
- **Release Planning:** Create a project with milestones, generate issues with estimates.
- **Cross-Project Dependencies:** Find "blocked" issues, identify blockers, create linked issues.
- **Automated Status Updates:** Find stale issues, add status comments.
- **Smart Labeling:** Analyze unlabeled issues, suggest/apply labels.
- **Sprint Retrospectives:** Generate report for last cycle, note completed vs. pushed work.

## Tips
- Batch operations for related changes.
- Use natural queries when possible.
- Break large updates into smaller batches to avoid rate limits.
- Cache or reuse filters when listing frequently.

## Troubleshooting
- **Authentication:** Clear cookies, re-run OAuth (MCP) or verify API key (Bash).
- **Tool Calling Errors:** Confirm model supports multiple tool calls (MCP) or check script permissions (Bash).
- **Missing Data:** Refresh token, verify workspace access, check for archived projects.
- **Performance:** Batch bulk operations, use specific filters.