linear-issue

star 234

Use when creating a Linear issue from the current coding context, or when the user invokes /linear-issue. Infers team, priority, status, and relationships from conversation context, working directory, and git branch.

ReviewStage By ReviewStage schedule Updated 5/5/2026
play_arrow Run Skill in Manus View GitHub

name: linear-issue description: Use when creating a Linear issue from the current coding context, or when the user invokes /linear-issue. Infers team, priority, status, and relationships from conversation context, working directory, and git branch. metadata: internal: true

Creating Linear Issues

Single-pass workflow: gather context, search existing issues, infer fields informed by what's already filed, create issue.

Workflow

1. CONTEXT  → Gather signals: args, conversation, directory, git branch
2. SEARCH   → list_issues broadly to find duplicates, related issues, and inform inference
3. TEAMS    → list_teams to get available teams (informed by search results)
4. INFER    → Determine title, description, team, priority, status, labels, project, links, relationships
5. CREATE   → create_issue with inferred fields + relationships
6. REPORT   → Display created issue summary

Step 1: CONTEXT

Gather all available signals:

  • Args: Description provided after /linear-issue — primary signal
  • Conversation: If no args, summarize current discussion as issue description
  • Directory: Current working directory/package (e.g. packages/ai/ suggests AI-related team)
  • Git branch: Branch name often encodes feature/bug context

Step 2: SEARCH

Search existing issues before anything else — what's already filed informs every downstream decision including team selection.

  1. Call list_issues with keywords extracted from the context (args, conversation summary, branch name)
  2. Search broadly across teams — no team filter yet, since search results may reveal the correct team
  3. Collect results into three buckets:
Bucket Criteria Used for
Duplicates Same intent and scope as new issue Stop and warn user
Related Same area, overlapping context Relationship inference in Step 4
Informative Same team/area but different scope Team/priority/status inference in Step 4

If a strong duplicate is found (same intent and scope): STOP. Do not proceed to Step 4. Report the existing issue:

Possible duplicate found — did not create.
Existing: TEAM-99 "Add retry logic to extraction agent"
Status: In Progress  |  Assignee: @charles
URL: https://linear.app/...

Reply if you still want to create a new issue.

Step 3: TEAMS

Call list_teams → get all workspace teams

Use search results from Step 2 to guide matching — if related issues belong to a specific team, that's strong evidence for the correct team.

Step 4: INFER

Use context from Step 1, search results from Step 2, and team list from Step 3 to determine all fields.

Team

  • Primary signal: which team do related/informative issues belong to?
  • Secondary signal: directory/package name fuzzy-matched against team names from Step 3
  • Fallback: broadest team

Priority

Signal Priority
"ASAP", "urgent", "blocking", "broken", "critical", "P0", "production down" 1 (Urgent)
"soon", "important", "next few days", "high priority", "P1" 2 (High)
No urgency signal / default 3 (Normal)
"low priority", "nice to have", "when we get to it", "P3", "minor" 4 (Low)

Also consider: what priority are related issues set to? Match the neighborhood.

Status

Signal Status
"needs discussion", "RFC", "should we", "not sure if", "explore", "maybe" Backlog
Default / clear actionable task Todo
"I'm working on", "currently", "in progress", "started" In Progress

Title

Extract or generate a concise title in imperative form, under 80 characters.

Description

Format as markdown. Include:

  • What the issue is about
  • Context: branch name, relevant file/package, conversation summary
  • Any acceptance criteria apparent from context

Labels

Infer labels from context and search results:

  • From description: "bug"/"broken"/"error" → bug label, "feature"/"add"/"new" → feature label, "refactor"/"tech debt"/"cleanup" → tech-debt label
  • From related issues: If related issues share a common label, apply it to the new issue too
  • Call list_issue_labels with the inferred team to verify labels exist before applying. Only use labels that actually exist in the workspace.

Project

  • If related issues from Step 3 belong to a project, add the new issue to the same project
  • If the conversation or args explicitly mention a project name, use that
  • Otherwise, leave unset

Links

Add traceability links back to the development context:

  • If on a branch with an open PR, link to the PR URL
  • If the conversation references a specific file or commit, link to it on GitHub
  • Use links: [{url, title}] format

Relationships

Analyze related issues from Step 3:

Sub-issue (parentId) — New issue is a specific task within a broader existing issue. Example: "fix retry in extraction agent" is a sub-issue of "improve chapter generation reliability"

Parent — New issue encompasses existing smaller issues. After creating, call update_issue on each child to set their parentId.

Blocking / Blocked-by (blocks / blockedBy) — Use when:

  • Explicit dependency language: "this blocks X", "can't do Y until this is done"
  • Technical dependency: "migrate DB schema" blocks "add new column"

Related (relatedTo) — Same area, shared context, but neither blocks the other.

Step 5: CREATE

Call create_issue with:

Field Value
title Inferred title (imperative, <80 chars)
description Markdown description with context
team Matched team name
priority Numeric: 1=Urgent, 2=High, 3=Normal, 4=Low
state Status name: "Backlog", "Todo", "In Progress"
labels Array of label names inferred from context
project Project name (if related issues share a project)
links Array of {url, title} linking to PR/branch/commit
parentId Parent issue identifier (if sub-issue)
blocks Array of issue identifiers this blocks
blockedBy Array of issue identifiers blocking this
relatedTo Array of related issue identifiers

If this issue is a parent of existing issues, after creation call update_issue on each child to set parentId.

Step 6: REPORT

Created: TEAM-123 "Add retry logic to chapter generation"
Team: Product  |  Priority: Normal  |  Status: Todo
Labels: bug, ai-pipeline  |  Project: Chapter Gen V2
Parent: TEAM-100 "Improve chapter generation reliability"
Related: TEAM-98 "Audit error handling in AI pipeline"
Links: PR #42 "feat: add retry logic"
URL: https://linear.app/...

Common Mistakes

Mistake Fix
Inferring fields before searching existing issues Always search first — existing issues inform team, priority, and relationships
Creating without checking duplicates Step 3 catches duplicates before any inference work
Setting priority too high by default Default is Normal (3), only escalate with clear urgency signals
Guessing team instead of looking up Always call list_teams and match against actual teams
Searching only within one team Search broadly first — related issues may be in a different team
Forgetting to set relationships Check related bucket from Step 3 for parent/blocking/related
Using IDs instead of names for state create_issue accepts state names directly ("Backlog", "Todo")
Skipping description context Always include branch, directory, and conversation context
Creating parent without updating children After creating a parent issue, call update_issue on children
Applying labels that don't exist Call list_issue_labels to verify labels exist before using them
Ignoring project from related issues If related issues share a project, add the new issue to it
Not linking back to PR/branch Always check for an open PR with gh pr view and link it
Install via CLI
npx skills add https://github.com/ReviewStage/stage-cli --skill linear-issue
Repository Details
star Stars 234
call_split Forks 18
navigation Branch main
article Path SKILL.md
More from Creator
ReviewStage
ReviewStage Explore all skills →