القائمة
Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | Linear |
| description | Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows. |
| version | 2.2.3 |
| author | wrsmith108 |
| allowed-tools | ["mcp__linear","WebFetch(domain:linear.app)","Bash"] |
Tools and workflows for managing issues, projects, and teams in Linear.
This skill supports multiple tool backends. Use whichever is available:
linear command) - Always available via BashIf MCP tools are NOT available, use the Linear CLI via Bash:
# View an issue
linear issues view ENG-123
# Create an issue
linear issues create --title "Issue title" --description "Description"
# Update issue status (get state IDs first)
linear issues update ENG-123 -s "STATE_ID"
# Add a comment
linear issues comment add ENG-123 -m "Comment text"
# List issues
linear issues list
Do NOT report "MCP tools not available" as a blocker - use CLI instead.
CRITICAL: Never expose API keys in terminal output or Claude's context.
# Validate LINEAR_API_KEY is set (masked output)
varlock load 2>&1 | grep LINEAR
# Run commands with secrets injected
varlock run -- npx tsx scripts/query.ts "query { viewer { name } }"
# Check schema (safe - no values)
cat .env.schema | grep LINEAR
# ❌ NEVER - exposes key to Claude's context
linear config show
echo $LINEAR_API_KEY
printenv | grep LINEAR
cat .env
Create .env.schema with @sensitive annotation:
# @type=string(startsWith=lin_api_) @required @sensitive
LINEAR_API_KEY=
Add LINEAR_API_KEY to .env (never commit this file)
Configure MCP to use environment variable:
{
"mcpServers": {
"linear": {
"env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
}
}
}
Use varlock load to validate before operations
Run the setup check to verify your configuration:
npx tsx scripts/setup.ts
This will check:
Key Location: LINEAR_API_KEY lives in your project root .env file. The MCP server reads it via environment injection—shell exports don't reach MCP subprocesses. Use varlock load to validate setup.
If setup reports a missing API key:
lin_api_)# Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
export LINEAR_API_KEY="lin_api_your_key_here"
Add LINEAR_API_KEY to your project's .env file using your preferred secure editor.
Never paste API keys directly in terminal commands or Claude's context.
See the Security section above for details.
When creating or linking issues, projects, and initiatives, use these team UUIDs:
| Team | UUID |
|---|---|
| Smith Horn Group | 6795e794-99cc-4cf3-974f-6630c55f037d |
Verify everything works:
npx tsx scripts/query.ts "query { viewer { name } }"
You should see your name from Linear.
# Create issue in a project
npx tsx scripts/linear-ops.ts create-issue "Project" "Title" "Description"
# Update issue status
npx tsx scripts/linear-ops.ts status Done ENG-123 ENG-124
# Create sub-issue
npx tsx scripts/linear-ops.ts create-sub-issue ENG-100 "Sub-task" "Details"
# Update project status
npx tsx scripts/linear-ops.ts project-status "Phase 1" completed
# Show all commands
npx tsx scripts/linear-ops.ts help
See Project Management Commands for full reference.
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.
Create the project first:
npx tsx scripts/linear-ops.ts create-project "Phase X: Feature Name" "My Initiative"
Set project state to Planned:
npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" planned
Create issues directly in the project:
npx tsx scripts/linear-ops.ts create-issue "Phase X: Feature Name" "Parent task" "Description"
npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Description"
npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 2" "Description"
Update project state when work begins:
npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" in-progress
❌ Creating issues in a "holding" project and moving them later:
# Don't do this
create-issue "Phase 6A" "New feature" # Wrong project
# Later: manually move to Phase X # Extra work
Update a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.
npx tsx scripts/linear-ops.ts project-status <project-name> <state>
Valid States:
| Input | Description | API Value |
|---|---|---|
backlog | Not yet started | backlog |
planned | Scheduled for future | planned |
in-progress | Currently active | started |
paused | Temporarily on hold | paused |
completed | Successfully finished | completed |
canceled | Will not be done | canceled |
Examples:
# Start working on a project
npx tsx scripts/linear-ops.ts project-status "Phase 8: MCP Decision Engine" in-progress
# Mark project complete
npx tsx scripts/linear-ops.ts project-status "Phase 8" completed
# Partial name matching works
npx tsx scripts/linear-ops.ts project-status "Phase 8" paused
Link an existing project to an initiative.
npx tsx scripts/linear-ops.ts link-initiative <project-name> <initiative-name>
Examples:
# Link a project to an initiative
npx tsx scripts/linear-ops.ts link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"
# Partial matching works
npx tsx scripts/linear-ops.ts link-initiative "Phase 8" "Q1 Goals"
Remove a project from an initiative.
npx tsx scripts/linear-ops.ts unlink-initiative <project-name> <initiative-name>
Examples:
# Remove incorrect link
npx tsx scripts/linear-ops.ts unlink-initiative "Phase 8" "Linear Skill"
# Clean up test links
npx tsx scripts/linear-ops.ts unlink-initiative "Test Project" "Q1 Goals"
Error Handling:
# 1. Create project linked to initiative
npx tsx scripts/linear-ops.ts create-project "Phase 11: New Feature" "Q1 Goals"
# 2. Set state to planned
npx tsx scripts/linear-ops.ts project-status "Phase 11" planned
# 3. Create issues in the project
npx tsx scripts/linear-ops.ts create-issue "Phase 11" "Parent task" "Description"
npx tsx scripts/linear-ops.ts create-sub-issue ENG-XXX "Sub-task 1" "Details"
# 4. Start work - update to in-progress
npx tsx scripts/linear-ops.ts project-status "Phase 11" in-progress
# 5. Mark issues done
npx tsx scripts/linear-ops.ts status Done ENG-XXX ENG-YYY
# 6. Complete project
npx tsx scripts/linear-ops.ts project-status "Phase 11" completed
# 7. (Optional) Link to additional initiative
npx tsx scripts/linear-ops.ts link-initiative "Phase 11" "Q2 Goals"
Choose the right tool for the task:
| Tool | When to Use |
|---|---|
| MCP (Official Server) | Most operations - PREFERRED |
| Helper Scripts | Bulk operations, when MCP unavailable |
| SDK scripts | Complex operations (loops, conditionals) |
| GraphQL API | Operations not supported by MCP/SDK |
Use the official Linear MCP server. Run this command in your terminal:
claude mcp add --transport http linear-server https://mcp.linear.app/mcp
Then open a Claude Code session and run /mcp to authenticate with your Linear account.
See the Linear MCP docs for the latest setup instructions.
WARNING: Do NOT use deprecated community servers. See troubleshooting.md for details.
| Operation | Reliability | Notes |
|---|---|---|
| Create issue | ✅ High | Full support |
| Update status | ✅ High | Use state: "Done" directly |
| List/Search issues | ✅ High | Supports filters, queries |
| Add comment | ✅ High | Works with issue IDs |
# Via MCP - use human-readable state names
update_issue with id="issue-uuid", state="Done"
# Via helper script (bulk operations)
node scripts/linear-helpers.mjs update-status Done 123 124 125
For detailed helper script usage, see troubleshooting.md.
For bulk operations or background execution, use the Linear-specialist subagent:
Task({
description: "Update Linear issues",
prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
subagent_type: "Linear-specialist"
})
When to use Linear-specialist (parallel):
When to use direct execution:
See sync.md for parallel execution patterns.
Every issue MUST be attached to a project. Every project MUST be linked to an initiative.
| Entity | Must Link To | If Missing |
|---|---|---|
| Issue | Project | Not visible in project board |
| Project | Initiative | Not visible in roadmap |
See projects.md for complete project creation checklist.
state: "Todo"state: "Backlog"Uses domain-based label taxonomy. See docs/labels.md.
Key rules:
feature, bug, refactor, chore, spikesecurity, backend, frontend, etc.blocked, breaking-change, tech-debt# Validate labels
npx tsx scripts/linear-ops.ts labels validate "feature,security"
# Suggest labels for issue
npx tsx scripts/linear-ops.ts labels suggest "Fix XSS vulnerability"
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:
Scripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.
Fallback only. Use when operations aren't supported by MCP or SDK.
See api.md for complete documentation including:
Quick ad-hoc query:
npx tsx scripts/query.ts "query { viewer { name } }"
For advanced project and initiative management patterns, see projects.md.
Quick reference - common project commands:
# Create project linked to initiative
npx tsx scripts/linear-ops.ts create-project "Phase X: Name" "My Initiative"
# Update project status
npx tsx scripts/linear-ops.ts project-status "Phase X" in-progress
npx tsx scripts/linear-ops.ts project-status "Phase X" completed
# Link/unlink projects to initiatives
npx tsx scripts/linear-ops.ts link-initiative "Phase X" "My Initiative"
npx tsx scripts/linear-ops.ts unlink-initiative "Phase X" "Old Initiative"
Key topics in projects.md:
For bulk synchronization of code changes to Linear, see sync.md.
Quick sync commands:
# Bulk update issues to Done
npx tsx scripts/linear-ops.ts status Done ENG-101 ENG-102 ENG-103
# Update project status
npx tsx scripts/linear-ops.ts project-status "My Project" completed
| Document | Purpose |
|---|---|
| api.md | GraphQL API reference, timeout handling |
| sdk.md | SDK automation patterns |
| sync.md | Bulk sync patterns |
| projects.md | Project & initiative management |
| troubleshooting.md | Common issues, MCP debugging |
| docs/labels.md | Label taxonomy |
External: Linear MCP Documentation
~/.claude/skills/linear references replaced with relative pathsLinear-specialist subagent for parallel/background bulk operationsSKILL.md now at repository root for automatic discovery by Claude Codelabels validate, labels suggest, labels agents CLI commandsdocs/labels.md with complete taxonomy guide and decision treeENG- prefixproject-status command — update project states with user-friendly terminologylink-initiative / unlink-initiative commandsmcp.linear.appstate: "Done")scripts/setup.ts — first-time setup check and diagnosticsscripts/linear-ops.ts — high-level operations CLIsync.md; Linear-specialist parallel agent spawningEnd-to-end planning and execution orchestrator. Chains SPARC or wave-planner (Stage 1), plan-review, linear, and hive-workers-skill into a single workflow. Automatically routes infra changes through SPARC research instead of wave-planner. Use when starting a new initiative, executing a set of Linear issues, or running plan-to-deployment.
Optimize oversized CLAUDE.md files using progressive disclosure. Analyzes content tiers, detects encryption constraints, creates sub-documents, and rewrites the main file with a Sub-Documentation Table. Triggers: optimize CLAUDE.md, reduce CLAUDE.md size, CLAUDE.md too long, apply progressive disclosure to CLAUDE.md
Execute tasks using hive mind orchestration with parallel agents, automatic code review, and documentation updates. Use for feature execution, epic completion, or complex multi-task work.
Transform project issues into execution-ready implementation plans with risk prediction, wave-based organization, specialist agents, and TDD workflow
Manage git worktrees for parallel development with conflict prevention and wave-aware execution strategy. Use when creating feature branches, starting parallel work sessions, merging worktree PRs, or coordinating multiple Claude sessions.
End-of-session housekeeping for git repositories. Use when the user asks to 'end of session', 'clean up session', 'session housekeeping', 'clean up branches', 'clean up worktrees', or 'clean up remote branches'.