Linear Claude Skill

何时使用此技能

管理 Linear issue、项目和团队

当需要管理 Linear issue、项目和团队时使用此技能。

Linear

管理 Linear 中 issue、项目和团队的工具与工作流。

⚠️ 工具可用性（先读此节）

此技能支持多种工具后端，按可用性选择：

1. MCP 工具 (mcp__linear) — 如可用则优先使用
2. Linear CLI（linear 命令） — 始终可通过 Bash 使用
3. 辅助脚本 — 用于复杂操作

如 MCP 工具不可用，通过 Bash 使用 Linear CLI：

# 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

不要将"MCP 工具不可用"报告为阻碍 — 改用 CLI。

何时使用此技能

管理 Linear issue、项目和团队

当需要管理 Linear issue、项目和团队时使用此技能。

🔐 安全：Varlock 集成

关键：绝不在终端输出或 Claude 上下文中暴露 API 密钥。

安全命令（始终使用）

# 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 
printenv | grep LINEAR
cat .env

新项目配置

1. 创建 .env.schema 并添加 @sensitive 标注：

   # @type=string(startsWith=lin_api_) @required @sensitive
   LINEAR_API_KEY=
   

2. 将 LINEAR_API_KEY 添加到 .env（切勿提交此文件）

3. 配置 MCP 使用环境变量：

   {
     "mcpServers": {
       "linear": {
         "env": { "LINEAR_API_KEY": "" }
       }
     }
   }
   

4. 操作前用 varlock load 验证

快速入门（首次使用）

1. 检查配置

运行配置检查以验证环境：

npx tsx ~/.claude/skills/linear/scripts/setup.ts

检查内容：

• LINEAR_API_KEY 已设置且有效
• @linear/sdk 已安装
• Linear CLI 可用性（可选）
• MCP 配置（可选）

2. 获取 API 密钥（如需）

如配置检查提示缺少 API 密钥：

1. 在浏览器中打开 Linear
2. 进入 Settings（齿轮图标）-> Security & access -> Personal API keys
3. 点击 Create key 并复制密钥（以 lin_api_ 开头）
4. 添加到环境：

# Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
export LINEAR_API_KEY="lin_api_your_key_here"

# Option B: Add to Claude Code environment
echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env

# Then reload your shell or restart Claude Code

3. 测试连接

验证一切正常：

npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"

应看到你在 Linear 中的用户名。

4. 常用操作

# 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

完整参考见项目管理命令。

何时使用此技能

管理 Linear issue、项目和团队

当需要管理 Linear issue、项目和团队时使用此技能。

项目规划工作流

从一开始就在正确的项目中创建 issue

最佳实践：规划新阶段或新计划时，在同一次规划会话中一起创建项目及其 issue。避免先在临时项目中创建 issue 再后续移动。

推荐工作流

1. 先创建项目：

   npx tsx scripts/linear-ops.ts create-project "Phase X: Feature Name" "My Initiative"
   

2. 将项目状态设为 Planned：

   npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" planned
   

3. 直接在项目中创建 issue：

   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"
   

4. 工作开始时更新项目状态：

   npx tsx scripts/linear-ops.ts project-status "Phase X: Feature Name" in-progress
   

为什么这样做

• 可追溯性：issue 从创建起就关联到项目
• 指标准确性：项目进度追踪从第一天就准确
• 工作流效率：无需在项目间移动 issue
• 组织性：Linear 视图和筛选器正常工作

应避免的反模式

❌ 在"暂存"项目中创建 issue 再后续移动：

# Don't do this
create-issue "Phase 6A" "New feature"  # Wrong project
# Later: manually move to Phase X      # Extra work

项目管理命令

project-status

更新 Linear 中的项目状态。接受用户友好的术语，自动映射到 Linear API。

npx tsx scripts/linear-ops.ts project-status <project-name> <state>

有效状态：

示例：

# 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-initiative

将已有项目关联到计划。

npx tsx scripts/linear-ops.ts link-initiative <project-name> <initiative-name>

示例：

# 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"

unlink-initiative

将项目从计划中移除。

npx tsx scripts/linear-ops.ts unlink-initiative <project-name> <initiative-name>

示例：

# 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"

错误处理：

• 项目未关联到指定计划时返回错误
• 项目或计划未找到时返回错误

完整项目生命周期示例

# 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"

何时使用此技能

管理 Linear issue、项目和团队

当需要管理 Linear issue、项目和团队时使用此技能。

工具选择

根据任务选择合适的工具：

MCP 服务器配置

使用官方 Linear MCP 服务器 mcp.linear.app：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.linear.app/sse"],
      "env": { "LINEAR_API_KEY": "your_api_key" }
    }
  }
}

警告：不要使用已弃用的社区服务器。详见 troubleshooting.md。

MCP 可靠性（官方服务器）

快速状态更新

# 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

辅助脚本参考

辅助脚本的详细用法见 troubleshooting.md。

并行智能体执行

批量操作或后台执行时，使用 Linear-specialist 子智能体：

Task({
  description: "Update Linear issues",
  prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
  subagent_type: "Linear-specialist"
})

何时使用 Linear-specialist（并行）：

• 批量状态更新（3 个以上 issue）
• 项目状态变更
• 创建多个 issue
• 代码变更后的同步操作

何时使用直接执行：

• 单个 issue 查询
• 查看 issue 详情
• 快速状态检查
• 需要即时结果的操作

并行执行模式详见 sync.md。

关键要求

Issue → 项目 → 计划

每个 issue 必须关联到项目。每个项目必须关联到计划。

完整的项目创建检查清单见 projects.md。

约定

Issue 状态

• 已分配给我：设为 state: "Todo"
• 未分配：设为 state: "Backlog"

标签

使用基于领域的标签分类体系。详见 docs/labels.md。

核心规则：

• 一个类型标签：feature、bug、refactor、chore、spike
• 1-2 个领域标签：security、backend、frontend 等
• 适用时添加范围标签：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"

SDK 自动化脚本

仅在 MCP 工具不够用时使用。 涉及循环、映射或批量更新的复杂操作，用 @linear/sdk 编写 TypeScript 脚本。详见 sdk.md：

• 完整脚本模式和模板
• 常见自动化示例（批量更新、筛选、报表）
• 工具选择标准

脚本提供完整类型提示，多步操作比原生 GraphQL 更易调试。

GraphQL API

仅作后备。 在 MCP 或 SDK 不支持的操作时使用。

完整文档见 api.md，包括：

• 认证与配置
• 查询和变更示例
• 超时处理模式
• MCP 超时替代方案
• Shell 脚本兼容性

快速临时查询：

npx tsx ~/.claude/skills/linear/scripts/query.ts "query { viewer { name } }"

项目与计划

高级项目和计划管理模式见 projects.md。

快速参考 — 常用项目命令：

# 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"

projects.md 中的关键主题：

• 项目创建检查清单（必填步骤）
• Content 与 Description 字段区别
• 创建前先发现
• 工作前验证代码库
• 子 issue 管理
• 项目状态更新
• 项目进展报告

何时使用此技能

管理 Linear issue、项目和团队

当需要管理 Linear issue、项目和团队时使用此技能。

同步模式（批量操作）

代码变更到 Linear 的批量同步见 sync.md。

快速同步命令：

# 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

参考

外部链接： Linear MCP 文档

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 输出不能替代环境特定的验证、测试或专家评审。
• 如缺少必要输入、权限、安全边界或成功标准，应停下来请求澄清。