Manage Linear issues, projects, and teams
Add this skill
npx mdskills install sickn33/linear-claude-skillComprehensive Linear integration with multiple backends, strong security practices, and detailed workflow guidance
1---2name: linear-claude-skill3description: "Manage Linear issues, projects, and teams"4allowed-tools:5- WebFetch(domain: linear.app)6source: "https://github.com/wrsmith108/linear-claude-skill"7risk: safe8---910## When to Use This Skill1112Manage Linear issues, projects, and teams1314Use this skill when working with manage linear issues, projects, and teams.15# Linear1617Tools and workflows for managing issues, projects, and teams in Linear.1819---2021## ⚠️ Tool Availability (READ FIRST)2223**This skill supports multiple tool backends. Use whichever is available:**24251. **MCP Tools (mcp__linear)** - Use if available in your tool set262. **Linear CLI (`linear` command)** - Always available via Bash273. **Helper Scripts** - For complex operations2829**If MCP tools are NOT available**, use the Linear CLI via Bash:3031```bash32# View an issue33linear issues view ENG-1233435# Create an issue36linear issues create --title "Issue title" --description "Description"3738# Update issue status (get state IDs first)39linear issues update ENG-123 -s "STATE_ID"4041# Add a comment42linear issues comment add ENG-123 -m "Comment text"4344# List issues45linear issues list46```4748**Do NOT report "MCP tools not available" as a blocker** - use CLI instead.4950---515253## When to Use This Skill5455Manage Linear issues, projects, and teams5657Use this skill when working with manage linear issues, projects, and teams.58## 🔐 Security: Varlock Integration5960**CRITICAL**: Never expose API keys in terminal output or Claude's context.6162### Safe Commands (Always Use)6364```bash65# Validate LINEAR_API_KEY is set (masked output)66varlock load 2>&1 | grep LINEAR6768# Run commands with secrets injected69varlock run -- npx tsx scripts/query.ts "query { viewer { name } }"7071# Check schema (safe - no values)72cat .env.schema | grep LINEAR73```7475### Unsafe Commands (NEVER Use)7677```bash78# ❌ NEVER - exposes key to Claude's context79linear config show80echo $LINEAR_API_KEY81printenv | grep LINEAR82cat .env83```8485### Setup for New Projects86871. Create `.env.schema` with `@sensitive` annotation:88 ```bash89 # @type=string(startsWith=lin_api_) @required @sensitive90 LINEAR_API_KEY=91 ```92932. Add `LINEAR_API_KEY` to `.env` (never commit this file)94953. Configure MCP to use environment variable:96 ```json97 {98 "mcpServers": {99 "linear": {100 "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }101 }102 }103 }104 ```1051064. Use `varlock load` to validate before operations107108---109110## Quick Start (First-Time Users)111112### 1. Check Your Setup113114Run the setup check to verify your configuration:115116```bash117npx tsx ~/.claude/skills/linear/scripts/setup.ts118```119120This will check:121- LINEAR_API_KEY is set and valid122- @linear/sdk is installed123- Linear CLI availability (optional)124- MCP configuration (optional)125126### 2. Get API Key (If Needed)127128If setup reports a missing API key:1291301. Open [Linear](https://linear.app) in your browser1312. Go to **Settings** (gear icon) -> **Security & access** -> **Personal API keys**1323. Click **Create key** and copy the key (starts with `lin_api_`)1334. Add to your environment:134135```bash136# Option A: Add to shell profile (~/.zshrc or ~/.bashrc)137export LINEAR_API_KEY="lin_api_your_key_here"138139# Option B: Add to Claude Code environment140echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env141142# Then reload your shell or restart Claude Code143```144145### 3. Test Connection146147Verify everything works:148149```bash150npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"151```152153You should see your name from Linear.154155### 4. Common Operations156157```bash158# Create issue in a project159npx tsx scripts/linear-ops.ts create-issue "Project" "Title" "Description"160161# Update issue status162npx tsx scripts/linear-ops.ts status Done ENG-123 ENG-124163164# Create sub-issue165npx tsx scripts/linear-ops.ts create-sub-issue ENG-100 "Sub-task" "Details"166167# Update project status168npx tsx scripts/linear-ops.ts project-status "Phase 1" completed169170# Show all commands171npx tsx scripts/linear-ops.ts help172```173174See [Project Management Commands](#project-management-commands) for full reference.175176---177178179## When to Use This Skill180181Manage Linear issues, projects, and teams182183Use this skill when working with manage linear issues, projects, and teams.184## Project Planning Workflow185186### Create Issues in the Correct Project from the Start187188**Best Practice**: When planning a new phase or initiative, create the project and its issues together in a single planning session. Avoid creating issues in a catch-all project and moving them later.189190#### Recommended Workflow1911921. **Create the project first**:193 ```bash194 npx tsx scripts/linear-ops.ts create-project "Phase X: Feature Name" "My Initiative"195 ```1961972. **Set project state to Planned**:198 ```bash199 npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" planned200 ```2012023. **Create issues directly in the project**:203 ```bash204 npx tsx scripts/linear-ops.ts create-issue "Phase X: Feature Name" "Parent task" "Description"205 npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Description"206 npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 2" "Description"207 ```2082094. **Update project state when work begins**:210 ```bash211 npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" in-progress212 ```213214#### Why This Matters215216- **Traceability**: Issues are linked to their project from creation217- **Metrics**: Project progress tracking is accurate from day one218- **Workflow**: No time wasted moving issues between projects219- **Organization**: Linear views and filters work correctly220221#### Anti-Pattern to Avoid222223❌ Creating issues in a "holding" project and moving them later:224```bash225# Don't do this226create-issue "Phase 6A" "New feature" # Wrong project227# Later: manually move to Phase X # Extra work228```229230---231232## Project Management Commands233234### project-status235236Update a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.237238```bash239npx tsx scripts/linear-ops.ts project-status <project-name> <state>240```241242**Valid States:**243| Input | Description | API Value |244|-------|-------------|-----------|245| `backlog` | Not yet started | backlog |246| `planned` | Scheduled for future | planned |247| `in-progress` | Currently active | started |248| `paused` | Temporarily on hold | paused |249| `completed` | Successfully finished | completed |250| `canceled` | Will not be done | canceled |251252**Examples:**253```bash254# Start working on a project255npx tsx scripts/linear-ops.ts project-status "Phase 8: MCP Decision Engine" in-progress256257# Mark project complete258npx tsx scripts/linear-ops.ts project-status "Phase 8" completed259260# Partial name matching works261npx tsx scripts/linear-ops.ts project-status "Phase 8" paused262```263264### link-initiative265266Link an existing project to an initiative.267268```bash269npx tsx scripts/linear-ops.ts link-initiative <project-name> <initiative-name>270```271272**Examples:**273```bash274# Link a project to an initiative275npx tsx scripts/linear-ops.ts link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"276277# Partial matching works278npx tsx scripts/linear-ops.ts link-initiative "Phase 8" "Q1 Goals"279```280281### unlink-initiative282283Remove a project from an initiative.284285```bash286npx tsx scripts/linear-ops.ts unlink-initiative <project-name> <initiative-name>287```288289**Examples:**290```bash291# Remove incorrect link292npx tsx scripts/linear-ops.ts unlink-initiative "Phase 8" "Linear Skill"293294# Clean up test links295npx tsx scripts/linear-ops.ts unlink-initiative "Test Project" "Q1 Goals"296```297298**Error Handling:**299- Returns error if project is not linked to the specified initiative300- Returns error if project or initiative not found301302### Complete Project Lifecycle Example303304```bash305# 1. Create project linked to initiative306npx tsx scripts/linear-ops.ts create-project "Phase 11: New Feature" "Q1 Goals"307308# 2. Set state to planned309npx tsx scripts/linear-ops.ts project-status "Phase 11" planned310311# 3. Create issues in the project312npx tsx scripts/linear-ops.ts create-issue "Phase 11" "Parent task" "Description"313npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Details"314315# 4. Start work - update to in-progress316npx tsx scripts/linear-ops.ts project-status "Phase 11" in-progress317318# 5. Mark issues done319npx tsx scripts/linear-ops.ts status Done ENG-XXX ENG-YYY320321# 6. Complete project322npx tsx scripts/linear-ops.ts project-status "Phase 11" completed323324# 7. (Optional) Link to additional initiative325npx tsx scripts/linear-ops.ts link-initiative "Phase 11" "Q2 Goals"326```327328---329330331## When to Use This Skill332333Manage Linear issues, projects, and teams334335Use this skill when working with manage linear issues, projects, and teams.336## Tool Selection337338Choose the right tool for the task:339340| Tool | When to Use |341|------|-------------|342| **MCP (Official Server)** | Most operations - PREFERRED |343| **Helper Scripts** | Bulk operations, when MCP unavailable |344| **SDK scripts** | Complex operations (loops, conditionals) |345| **GraphQL API** | Operations not supported by MCP/SDK |346347### MCP Server Configuration348349**Use the official Linear MCP server** at `mcp.linear.app`:350351```json352{353 "mcpServers": {354 "linear": {355 "command": "npx",356 "args": ["mcp-remote", "https://mcp.linear.app/sse"],357 "env": { "LINEAR_API_KEY": "your_api_key" }358 }359 }360}361```362363> **WARNING**: Do NOT use deprecated community servers. See [troubleshooting.md](troubleshooting.md) for details.364365### MCP Reliability (Official Server)366367| Operation | Reliability | Notes |368|-----------|-------------|-------|369| Create issue | ✅ High | Full support |370| Update status | ✅ High | Use `state: "Done"` directly |371| List/Search issues | ✅ High | Supports filters, queries |372| Add comment | ✅ High | Works with issue IDs |373374### Quick Status Update375376```bash377# Via MCP - use human-readable state names378update_issue with id="issue-uuid", state="Done"379380# Via helper script (bulk operations)381node scripts/linear-helpers.mjs update-status Done 123 124 125382```383384### Helper Script Reference385386For detailed helper script usage, see **[troubleshooting.md](troubleshooting.md)**.387388### Parallel Agent Execution389390For bulk operations or background execution, use the `Linear-specialist` subagent:391392```javascript393Task({394 description: "Update Linear issues",395 prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",396 subagent_type: "Linear-specialist"397})398```399400**When to use `Linear-specialist` (parallel):**401- Bulk status updates (3+ issues)402- Project status changes403- Creating multiple issues404- Sync operations after code changes405406**When to use direct execution:**407- Single issue queries408- Viewing issue details409- Quick status checks410- Operations needing immediate results411412See **[sync.md](sync.md)** for parallel execution patterns.413414## Critical Requirements415416### Issues → Projects → Initiatives417418**Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**419420| Entity | Must Link To | If Missing |421|--------|--------------|------------|422| Issue | Project | Not visible in project board |423| Project | Initiative | Not visible in roadmap |424425See **[projects.md](projects.md)** for complete project creation checklist.426427---428429## Conventions430431### Issue Status432433- **Assigned to me**: Set `state: "Todo"`434- **Unassigned**: Set `state: "Backlog"`435436### Labels437438Uses **domain-based label taxonomy**. See [docs/labels.md](docs/labels.md).439440**Key rules:**441- ONE Type label: `feature`, `bug`, `refactor`, `chore`, `spike`442- 1-2 Domain labels: `security`, `backend`, `frontend`, etc.443- Scope labels when applicable: `blocked`, `breaking-change`, `tech-debt`444445```bash446# Validate labels447npx tsx scripts/linear-ops.ts labels validate "feature,security"448449# Suggest labels for issue450npx tsx scripts/linear-ops.ts labels suggest "Fix XSS vulnerability"451```452453## SDK Automation Scripts454455**Use only when MCP tools are insufficient.** For complex operations involving loops, mapping, or bulk updates, write TypeScript scripts using `@linear/sdk`. See `sdk.md` for:456457- Complete script patterns and templates458- Common automation examples (bulk updates, filtering, reporting)459- Tool selection criteria460461Scripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.462463## GraphQL API464465**Fallback only.** Use when operations aren't supported by MCP or SDK.466467See **[api.md](api.md)** for complete documentation including:468- Authentication and setup469- Example queries and mutations470- Timeout handling patterns471- MCP timeout workarounds472- Shell script compatibility473474**Quick ad-hoc query:**475476```bash477npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"478```479480## Projects & Initiatives481482For advanced project and initiative management patterns, see **[projects.md](projects.md)**.483484**Quick reference** - common project commands:485486```bash487# Create project linked to initiative488npx tsx scripts/linear-ops.ts create-project "Phase X: Name" "My Initiative"489490# Update project status491npx tsx scripts/linear-ops.ts project-status "Phase X" in-progress492npx tsx scripts/linear-ops.ts project-status "Phase X" completed493494# Link/unlink projects to initiatives495npx tsx scripts/linear-ops.ts link-initiative "Phase X" "My Initiative"496npx tsx scripts/linear-ops.ts unlink-initiative "Phase X" "Old Initiative"497```498499**Key topics in projects.md:**500- Project creation checklist (mandatory steps)501- Content vs Description fields502- Discovery before creation503- Codebase verification before work504- Sub-issue management505- Project status updates506- Project updates (status reports)507508---509510511## When to Use This Skill512513Manage Linear issues, projects, and teams514515Use this skill when working with manage linear issues, projects, and teams.516## Sync Patterns (Bulk Operations)517518For bulk synchronization of code changes to Linear, see **[sync.md](sync.md)**.519520**Quick sync commands:**521522```bash523# Bulk update issues to Done524npx tsx scripts/linear-ops.ts status Done ENG-101 ENG-102 ENG-103525526# Update project status527npx tsx scripts/linear-ops.ts project-status "My Project" completed528```529530---531532## Reference533534| Document | Purpose |535|----------|---------|536| [api.md](api.md) | GraphQL API reference, timeout handling |537| [sdk.md](sdk.md) | SDK automation patterns |538| [sync.md](sync.md) | Bulk sync patterns |539| [projects.md](projects.md) | Project & initiative management |540| [troubleshooting.md](troubleshooting.md) | Common issues, MCP debugging |541| [docs/labels.md](docs/labels.md) | Label taxonomy |542543**External:** [Linear MCP Documentation](https://linear.app/docs/mcp.md)544
Full transparency — inspect the skill content before installing.