linear-issue-management

Linear Issue Management

Use this skill when working with Linear issues through the API.

Prime directive

Discover before writing. Never guess the team, project, state, assignee, or label IDs from memory when creating or updating a Linear issue.

Before any mutation:

1. Confirm the target workspace/team from the user request or current project context.
2. Query Linear for the exact team/project/label/state IDs.
3. Search for an existing issue to avoid duplicates.
4. Show the intended mutation summary if the action is externally visible or ambiguous.
5. Execute one focused GraphQL mutation.
6. Return the issue key + URL and record any important follow-up context.

Safety rules

• Do not print, paste, log, or commit the Linear API token.
• Prefer 1Password-backed env injection or an existing secret manager. Do not write tokens to files.
• Treat issue creation, updates, comments, assignment changes, and state transitions as external state-changing actions. Get explicit user approval unless the user already gave a direct instruction in the current conversation.
• Use GraphQL variables. Do not interpolate untrusted user text into a GraphQL query string.
• Keep issue text factual. Do not file speculation as confirmed defects.
• Do not file in a team just because an issue key prefix looks familiar; confirm via API.

Auth pattern

Use a Linear API key in LINEAR_API_KEY.

Preferred shape:

op run --env-file <linear-env-file> -- <command using LINEAR_API_KEY>

or, when the shell already has the token:

curl https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @payload.json

Never echo the token. If debugging auth, print only whether LINEAR_API_KEY is set, not its value.

Workflow: create an issue

1. Read references/graphql-recipes.md for query/mutation templates.
2. Discover teams and choose the exact teamId.
3. Search existing issues by relevant keywords and repo/project names.
4. Discover labels/projects/states only after the team is known.
5. Resolve label conflicts before mutation.
6. Create the issue with title, description, teamId, optional projectId, optional labelIds, and optional priority.
7. Return the created issue identifier and URL.