Linear

Linear GraphQL

Use this skill for raw Linear GraphQL work during Symphony app-server sessions.

Primary tool

Use the linear_graphql client tool exposed by Symphony's app-server session. It reuses Symphony's configured Linear auth for the session.

Tool input:

{
  "query": "query or mutation document",
  "variables": {
    "optional": "graphql variables object"
  }
}

Tool behavior:

• Send one GraphQL operation per tool call.
• Treat a top-level errors array as a failed GraphQL operation even if the tool call itself completed.
• Keep queries/mutations narrowly scoped; ask only for the fields you need.

Discovering unfamiliar operations

When you need an unfamiliar mutation, input type, or object field, use targeted introspection through linear_graphql.

List mutation names:

query ListMutations {
  __type(name: "Mutation") {
    fields {
      name
    }
  }
}

Inspect a specific input object:

query CommentCreateInputShape {
  __type(name: "CommentCreateInput") {
    inputFields {
      name
      type {
        kind
        name
        ofType {
          kind
          name
        }
      }
    }
  }
}

Common workflows

Query an issue by key, identifier, or id

Use these progressively:

• Start with issue(id: $key) when you have a ticket key such as SKP-42.
• Fall back to issues(filter: ...) when you need identifier search semantics.
• Once you have the internal issue id, prefer issue(id: $id) for narrower reads.

Lookup by issue key:

query IssueByKey($key: String!) {
  issue(id: $key) {
    id
    identifier
    title
    state {
      id
      name
      type
    }
    project {
      id
      name
    }
    branchName
    url
    description
    updatedAt
    links {
      nodes {
        id
        url
        title
      }
    }
  }
}

Edit an existing comment

mutation UpdateComment($id: String!, $body: String!) {
  commentUpdate(id: $id, input: { body: $body }) {
    success
    comment {
      id
      body
    }
  }
}

Create a comment

mutation CreateComment($issueId: String!, $body: String!) {
  commentCreate(input: { issueId: $issueId, body: $body }) {
    success
    comment {
      id
      url
    }
  }
}

Move an issue to a different state

mutation MoveIssueToState($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue {
      id
      identifier
      state {
        id
        name
      }
    }
  }
}

Attach a GitHub PR to an issue

mutation AttachGitHubPR($issueId: String!, $url: String!, $title: String) {
  attachmentLinkGitHubPR(
    issueId: $issueId
    url: $url
    title: $title
    linkKind: links
  ) {
    success
    attachment {
      id
      title
      url
    }
  }
}

Usage rules

• Use linear_graphql for comment edits, uploads, and ad-hoc Linear API queries.
• Prefer the narrowest issue lookup that matches what you already know: key -> identifier search -> internal id.
• For state transitions, fetch team states first and use the exact stateId instead of hardcoding names inside mutations.
• Prefer attachmentLinkGitHubPR over a generic URL attachment when linking a GitHub PR to a Linear issue.
• Do not introduce new raw-token shell helpers for GraphQL access.