Linear CLI专家

面向在 Agent（Claude Code / Codex / Cursor 等）中调用 linear CLI 的开发者。 聚焦 v3 执行模型下的稳定 JSON 契约、预演式写入、Markdown 安全传参、批量操作与鉴权自愈。 核心能力: - Agent 优先执行循环：capabilities 发现 →...

核心功能: 本技能提供化工作流场景等能力。

在 Agent 运行时中安全、稳定地操作 Linear。所有写操作遵循"预览-执行-校验"闭环，所有 Markdown 内容走文件/stdin 而非内联，批量操作有并发与限速保护.

前置检查

请求格式

参数名	类型	必填	说明
input	string	是	Linear CLI专家处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

bash

linear --version          # 必须可用
linear auth status        # 鉴权状态
linear capabilities       # 命令能力清单（机器可读）

未安装时，按官方文档安装 linear CLI 并运行 linear auth login。Agent 检测到 command not found 应直接告知用户安装步骤，不要继续后续流程.

Agent 推荐执行循环

按此顺序执行，写操作必须先 dry-run：

1. 发现能力：linear capabilities（旧消费者用 --compat v1）
2. 读状态：默认 JSON 输出或显式 --json
3. 预演写入：--dry-run --json（命令支持时）
4. 执行写入：在机器可读通道上执行，然后检查 operation、receipt、error.details
5. 校验结果：查退出码与 error.details，不要解析带样式的终端文本

人/调试模式是次要且显式的：--profile human-debug --interactive。Agent 默认使用 --profile agent-safe（旧自动化兼容）. 当上游工具传入 Slack/工单信封时：优先 --context-file，若信封已含确定性 team/state/label 提示则加 --apply-triage，需要 suggest-only 或 preview-required 暂存时显式选 --autonomy-policy.

Markdown 安全传参决策表

场景	推荐方式	反模式（禁用）
已有 .md 文件作为描述	issue create --description-file path.md	--description "$(cat file)"
已有 .md 文件作为评论	comment add --body-file path.md	--body "$(cat file)"
流式生成的 Markdown	cat desc.md | linear issue create --title "..."	内联 --description "多行\n文本"
单行简单内容	内联 --description "一句话"	仍用文件（过度工程）

为什么禁止大段内联：

• Linear Web UI 中格式错乱
• shell 转义破坏换行与特殊字符
• 字面量 \n 出现在 markdown 中
• 脚本/管道中多行内容难维护

文件优先示例：

bash

cat > /tmp/description.md <<'EOF'
## Summary
- 领先项
- 第二项
# ...
## Details
这是带格式的详细描述.
EOF
# ...
linear issue create --title "My Issue" --description-file /tmp/description.md
linear issue comment add ENG-123 --body-file /tmp/comment.md

命令速查

命令	用途
linear auth	鉴权管理（login / status / token / refresh）
linear issue	issue 增删改查、批量操作
linear team / linear project / linear cycle / linear milestone	团队/项目/周期/里程碑
linear initiative / linear initiative-update	举措与时间线帖
linear label / linear project-label	issue 标签与项目标签
linear document	Linear 文档
linear notification / linear webhook	通知与 webhook
linear workflow-state / linear user	工作流状态与用户
linear config	交互式生成 .linear.toml
linear schema	输出 GraphQL schema 到 stdout
linear api	原始 GraphQL 请求（兜底）
linear capabilities	Agent 命令面描述
linear resolve	不变更地解析引用

任何命令加 --help 查看子命令与 flag。机器可读发现：linear capabilities 或 linear capabilities --compat v1.

批量操作模板

模板1：批量创建 issue（CSV → Linear）

bash

# issues.csv: title,team,description
# 已知限制
tail -n +2 issues.csv | xargs -P 4 -I {} bash -c '
  IFS=, read -r title team desc <<< "{}"
  echo "$desc" > /tmp/desc_$$.md
  linear issue create --title "$title" --team "$team" --description-file /tmp/desc_$$.md --json
  rm -f /tmp/desc_$$.md
'

并发上限默认 4，超过 8 易触发 Linear API 速率限制（每分钟 1500 请求/工作区）.

模板2：批量状态流转

bash

# backlog-to-in-progress.sh
linear issue list --status Backlog --json \
  | jq -r '.data[].identifier' \
  | xargs -P 4 -I {} linear issue update {} --status "In Progress" --dry-run --json \
  | tee /tmp/preview.json
# ...
# 预览无误后去掉 --dry-run 重跑

模板3：跨团队标签同步

bash

# 把 ENG 团队的 "bug" 标签复制到 WEB 团队
linear label list --team ENG --json | jq -r '.data[].name' | while read label; do
  linear label create --team WEB --name "$label" --dry-run
done

鉴权自愈流程

text

检测到 401/403 或 "unauthorized"
 ├─ linear auth status          # 看当前状态
 ├─ linear auth refresh         # 尝试刷新 token
 ├─ 仍失败？
 │   ├─ 检查环境变量 LINEAR_API_KEY 是否存在 → 用 linear auth login --token "$LINEAR_API_KEY"
 │   └─ 提示用户重新登录：linear auth login
 └─ 成功 → 重试原命令（最多 3 次，指数退避）

GraphQL 兜底工作流

优先用 CLI。仅当 CLI 未覆盖时用 linear api.

Schema 检索（节省流量）

bash

# 首次：转储 schema 到本地，后续只 grep
linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"

仅当本地转储超过 7 天或查询字段不存在时才重新拉取.

GraphQL 请求

含 ! 非空标记的查询必须用 heredoc stdin，避免转义问题：

bash

linear api --variable teamId=abc123 <<'GRAPHQL'
query($teamId: String!) { team(id: $teamId) { name } }
GRAPHQL
# ...
linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'
query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }
GRAPHQL

简单查询可内联：linear api '{ viewer { id name email } }'.

curl 兜底（需完全 HTTP 控制时）

bash

curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $(linear auth token)" \
  -d '{"query": "{ viewer { id } }"}'

用法示例

场景1：把 Slack 工单信封转成 Linear issue

bash

# 信封已含 team/state/label 提示
linear issue create \
  --context-file /tmp/slack-envelope.json \
  --apply-triage \
  --autonomy-policy preview-required \
  --dry-run --json | tee /tmp/preview.json
# ...
# 用户确认后
linear issue create --context-file /tmp/slack-envelope.json --apply-triage --json

场景2：清理 6 个月未更新的 backlog

bash

linear issue list --status Backlog --json \
  | jq -r --arg cutoff "$(date -d '6 months ago' +%Y-%m-%d)" \
      '.data[] | select(.updatedAt < $cutoff) | .identifier' \
  | xargs -I {} linear issue update {} --status Canceled --dry-run

场景3：PR 合并自动关 issue

bash

# git hook 中调用
PR_TITLE=$(git log -1 --pretty=%B)
ISSUE_IDS=$(echo "$PR_TITLE" | grep -oE '[A-Z]+-[0-9]+')
for id in $ISSUE_IDS; do
  linear issue update "$id" --status Done --comment-file /tmp/pr-merge.md
done

功能边界

• 本skill的能力范围受限于核心能力章节中定义的功能,不支持超出范围的操作
• 复杂业务场景建议结合人工经验判断
• 执行效率受模型能力与网络环境影响

用户常见疑问

Q1: --dry-run 不是所有命令都支持怎么办？ A: 不支持 dry-run 的命令（如 label create）改用"先 list 确认不存在 → 再创建"的预检模式。写操作前永远先读. Q2: 大量 issue 创建时频繁 429？ A: 并发降到 2，并在每次请求间加 sleep 0.5。Linear 速率限制按工作区计，跨工作区不会累计. Q3: JSON 输出字段不稳定？ A: 用 linear capabilities --compat v1 获取稳定契约。字段名变更时优先看 error.details，它给出字段路径. Q4: heredoc 在 Windows PowerShell 报错？ A: PowerShell 不支持 heredoc。改用文件：把查询写入 .graphql 文件，用 linear api --query-file query.graphql（如 CLI 不支持该 flag，则用 Get-Content query.graphql -Raw | linear api）. Q5: token 存哪里？ A: linear auth login 交互式登录后存于 ~/.config/linear/credentials.json。CI 环境用 LINEAR_API_KEY 环境变量，不要写入代码仓库.

排错指南

现象	排查路径
command not found: linear	未安装 → 按 README 安装 → 重开终端
401 Unauthorized	走"鉴权自愈流程"
429 Too Many Requests	降并发到 2 → 加 sleep → 检查是否有其他自动化在跑
error.details 显示字段路径	用 linear schema grep 该类型定义 → 按定义修正查询
dry-run 通过但实写失败	检查是否有 webhook/automation 在写时触发副作用 → 查 Linear 审计日志
Markdown 中出现字面 \n	检查是否用了内联 --description → 改为 --description-file
--context-file 报格式错	信封必须为 JSON 且含 source、title、description 字段

环境要求

运行环境

• Agent 平台: 任意支持 SKILL.md 的 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统: Windows / macOS / Linux（Windows 下避免 heredoc，用文件传参）
• Shell: bash / zsh 推荐；PowerShell 需用文件传参替代 heredoc

依赖详情

依赖项	类型	是否必需	获取方式
linear CLI（v3）	命令行工具	必需	官方仓库安装
jq	JSON 处理	强烈推荐	系统包管理器
curl	HTTP 兜底	可选	系统自带
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

• 交互式：linear auth login（浏览器 OAuth）
• CI/自动化：环境变量 LINEAR_API_KEY（Personal API Key，从 Linear → Settings → API 获取）
• 凭证存储：~/.json（勿提交到仓库）

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 必须通过 exec 执行 linear CLI 命令）
• 说明: 基于自然语言指令驱动 Agent 通过 CLI 操作 Linear，所有写操作走预演-执行-校验闭环

功能特点

面向在 Agent（Claud

面向在 Agent（Claude Code / Codex / Cursor 等）中调用 linear CLI 的开发者

处理: 解析面向在 Agent（Claud的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回面向在 Agent（Claud的响应数据,含执行状态与操作日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

聚焦 v3 执行模型下的稳定

聚焦 v3 执行模型下的稳定 JSON 契约、预演式写入、Markdown 安全传参、批量操作与鉴权自愈

处理: 解析聚焦 v3 执行模型下的稳定 的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回聚焦 v3 执行模型下的稳定 的响应数据,含执行状态与操作日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

核心能力(补充)

核心能力:

处理: 解析核心能力的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回核心能力的响应数据,含执行状态与操作日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

  • Agent 优先执行循环：capabilities 发现 → 读 → dry-run 预览 → 写 → 校验 receipt/error 技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置. 能力覆盖范围：能力范围包括以下关键词：解析难、内联转义炸、批量操作慢、鉴权易失效痛点、中稳跑、Use、when、需要代码生成、编程辅助、调试测试、开发部署时使用、不适用于无明确技、术栈的模糊需求等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

迅速上手

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

典型场景

适用于需要解决JSON解析难、内联转义炸、批量操作慢、鉴权易失效痛点，让Linear CLI在Agent中稳跑的场景。具体使用场景请参考下方详细说明.

使用说明

...

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

...

...

输出规范

json

{
  "success": true,
  "data": {
    "result": "Linear CLI专家处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "linear cli pro"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

...

功能介绍

• 自动化执行: 解决JSON解析难、内联转义炸、批量操作慢、鉴权易失效痛点，让Linear CLI在Agent中稳跑
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

量化评估

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

优势分析

对比维度	Linear CLI专家	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	解决JSON解析难、内联转义炸、批量操作慢、鉴权易失效痛点，让Linear CL	通用场景	通用场景

Q1: Linear CLI专家支持哪些输入格式？

A1: 解决JSON解析难、内联转义炸、批量操作慢、鉴权易失效痛点，让Linear CLI在Agent中稳跑。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。