全部 Skill/Linear 项目管理平台

Linear 项目管理平台 Skill

Linear 是纯 GraphQL 的项目管理平台，唯一 endpoint api.linear.app/graphql，没有平行的 REST API，且鉴权 header 格式因入口而异——个人 API Key 直连不带 Bearer，OAuth token 带，官方 MCP Server 不管哪种 key 统一都要 Bearer。这份 skill 按开发者要做的事拆成 8 个能力域，并标出了 cycleCreate 已废弃不可用、WorkflowState/Cycle ID 团队私有等最容易踩的坑。

文档版 · 未实测linearapi.linear.app个人 API Key（无 Bearer 前缀）或 OAuth2 Bearer token，官方 MCP Server 统一要求 BearerAgent 工具更新 2026-09-21
8份 reference
6个易错点
0条无凭证探测
2026-09-21文档抓取
INSTALL · 安装

安装

选你用的 Agent，复制命令。

npx -y skills add fxp/skillify --skill linear --agent claude-code --yes

装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。

或者让 Agent 自己装

读 https://github.com/fxp/skillify/blob/main/skills/linear/prompt.md 并照它执行
下载 linear.skill 53 KB 源文件 ↗

装对了的标志：references/ 下有 8 份文档。

TRY ASKING · 装好后可以这样问

装好后，可以这样问你的 Agent

这份 Skill 覆盖的典型任务。点一下复制。

CAPABILITIES · 能力清单

8 类能力

每类能力对应一份 reference，Agent 按任务只打开需要的那份。

鉴权与 Endpoint

个人 API Key / OAuth2 / Actor Authorization / Client Credentials 四种鉴权方式、header 格式差异、文件存储鉴权

references/auth-and-endpoint.mdPOST /graphql · POST /oauth/token · POST /oauth/revoke

Issue 与评论

Issue 查询/创建/更新/删除、批量创建、标签增删、评论、文件上传附到 issue

references/issues-and-comments.mdissueCreate · issueUpdate · issueDelete · commentCreate · fileUpload

团队 / 项目 / 周期 / 状态

Team/Project/Cycle/WorkflowState/IssueLabel 查询与增删改，按名字反查 ID

references/teams-projects-cycles-states.mdteams · projects · cycles · workflowStates · issueLabels

分页与过滤

Relay cursor 分页精确 shape、过滤器比较器语法、相对时间过滤

references/pagination-and-filtering.mdXxxConnection (all list fields)

Webhook

创建/查询/删除数据变更 webhook、投递重试策略、HMAC-SHA256 签名验证

references/webhooks.mdwebhookCreate · webhookDelete · webhooks

Agent 会话与官方 MCP

Agent Session 生命周期、五种 Activity、Signals、Agent Plans，以及官方远程 MCP Server

references/agents-and-mcp.mdagentActivityCreate · agentSessionUpdate · https://mcp.linear.app/mcp

SDK 与客户端

官方 TypeScript SDK 用法、没有官方 Python SDK 时怎么手写 GraphQL、SDK 错误类型

references/sdk-and-clients.md@linear/sdk

错误与限流

错误响应两种形状、查询复杂度算法、请求数与复杂度配额、deprecation 机制

references/errors-and-rate-limits.mdGlobal · 2,500–5,000 req/hr depending on auth
FACTS · 当前事实

当前事实

整理自官方文档（抓取于 2026-09-21），还没有用真实凭证验证。

项值
Endpoint唯一 POST https://api.linear.app/graphql，没有平行 REST API（OAuth token/revoke 与文件上传预签名 URL 除外）
鉴权 header个人 API Key Authorization: <KEY>（无 Bearer）；OAuth2 Authorization: Bearer <TOKEN>；官方 MCP Server 统一要 Bearer
按 ID 查找Team/Project/Cycle/WorkflowState/IssueLabel 只能按 UUID 查，不接受名字/key，需先用 filter 查出 ID
分页Relay cursor 模型，first/last 默认 50，不传会静默截断，需检查 pageInfo.hasNextPage
限流API Key 请求数 2,500/小时、复杂度 3,000,000/小时；OAuth App 请求数 5,000/小时、复杂度 2,000,000/小时——两个维度不同向
Cycle 创建cycleCreate 已废弃不可用，Cycle 只能靠 Team 的 cyclesEnabled 等设置自动生成
GOTCHAS · 易错点

照通用经验写容易错的 6 件事

来自官方文档，还没有用真实凭证验证。

  1. 没有 REST API，只有一个 GraphQL endpoint。业务读写全部走 POST https://api.linear.app/graphql，只有 OAuth 的 /oauth/token//oauth/revoke（表单编码）和文件上传的预签名 URL 例外。
  2. 两种错误形状都要处理，别只认一种。校验/权限类错误是 HTTP 200 + 顶层 errors 数组（GraphQL 标准部分成功）；触发限流是 HTTP 400 + extensions.code == "RATELIMITED"——只看状态码会漏掉 200 里的失败，只看 errors 数组会把限流和普通输入错误混为一谈。
  3. 鉴权 header 因入口而不同，三选一别混用。个人 API Key 直连主端点不加 Bearer；OAuth token 直连要加；官方 MCP Server（mcp.linear.app）不管哪种 key 统一都要加 Bearer——从直连迁到 MCP 最容易漏加。
  4. WorkflowState/Cycle 的 ID 是团队私有的，IssueLabel 恰好相反。把 A 团队的 stateId 传给 B 团队的 issue 是最常见的跨团队自动化 bug；IssueLabel 的 team 字段可空，null 即工作区级、任意团队可用。
  5. cycleCreate 已废弃且不可用（@deprecated(reason: "Cycle creation is not supported.")），Cycle 只能通过 Team 的 cyclesEnabled/cycleDuration 等设置自动生成，程序化只能改、归档或平移，没有"新建一个 Cycle"的可用 API。
  6. issueDelete 默认是 30 天宽限期的软删除，不是立即物理删除；只有管理员传 permanentlyDelete: true 才会跳过宽限期硬删，issueArchive（归档）是完全不同的语义。
STATUS · 验证状态

验证状态

文档版：整理自官方文档（抓取于 2026-09-21），还没有用真实凭证调用验证。页面和 Skill 里标「文档原文，未实测」的报错与行为都来自文档本身。

有这个平台的沙箱或 API Key？联系我们——补测并做完装与不装的对照测试后，它会升级为「已实测」。