linear-create

name: linear-create description: Create a Linear issue from freeform text with project, label, milestone, and priority suggestions

Create a new Linear issue from user-provided text. The skill interviews the user to capture motivation and success criteria for non-trivial issues, refines the input for clarity and brevity, suggests organizational metadata (project, label, milestone, priority), and presents a complete draft for approval before creating the issue.

Skill Invocation

This skill MUST be invoked with text describing the task to create:

/linear-create

Example: /linear-create fix the bug where users can't log in after password reset

If no text is provided, the agent MUST ask the user to describe the task before proceeding.

Step 1: Parse Input and Determine Context

The agent MUST:

1. Store the raw user input text for later refinement
2. Determine the default project name from the current repository's root directory (e.g., if working inside /Users/name/projects/acme-app, the default project is acme-app)

Step 2: Resolve Team and Project

The agent MUST query Linear for workspace metadata by calling list_teams and list_projects in parallel.

Team Resolution

• If only one team exists, the agent MUST auto-select it
• If multiple teams exist, the agent MUST present them to the user for selection using AskUserQuestion

Project Resolution

The agent MUST check whether a project matching the default name (from Step 1) exists in the query results.

• If the default project exists, the agent MUST present it as the recommended option
• If the default project does not exist, the agent MUST present available projects for selection

The agent MUST use AskUserQuestion to confirm the project, offering:

1. The default project as the recommended option (if it exists)
2. Other available projects
3. An option to skip project assignment

Step 3: Check for Existing Issues

After team and project are resolved, the agent MUST search for open issues that may match the user's input by calling list_issues with:

• query — the user's raw input text (or key terms extracted from it)
• team — the resolved team
• state — restricted to open/in-progress states (exclude completed and cancelled)

If no matches are found, the agent MUST proceed silently to Step 4.

If matches are found, the agent MUST present each match with:

• Issue identifier (e.g., PROJ-123)
• Title
• Current status
• URL (constructed as https://linear.app/team/<team-key>/issue/<identifier>)

The agent MUST then ask the user whether any of the listed issues match their intent using AskUserQuestion:

• Yes, one of these matches — cancel creation and display the matching issue's identifier and URL
• No, none of these match — proceed to Step 4

The agent MUST NOT proceed to issue creation if the user confirms a duplicate exists.

Step 4: Query Labels and Milestones

After team and project are resolved, the agent MUST fetch metadata in parallel:

1. Call list_issue_labels (filtered by the selected team if applicable)
2. If a project was selected, call list_milestones for that project

If no project was selected, the agent MUST skip milestone retrieval.

Step 5: Gather Additional Details

The agent MUST assess whether the user's input provides enough context to craft a precise issue title and description.

Skip Condition

The agent SHOULD skip this step and proceed silently to Step 6 when ALL of the following are true:

• The input clearly describes a single, well-scoped task
• The intent is unambiguous (only one reasonable interpretation exists)
• The task does not require reproduction steps, acceptance criteria, or other structured detail

Examples of input that SHOULD skip this step:

• "fix typo in README installation section"
• "update lodash to version 4.17.21"
• "add .gitignore entry for .env.local"

Simple fixes, dependency bumps, config changes, and housekeeping chores typically satisfy this skip condition. Features, design changes, and improvements typically do not.

Interview

When this step is not skipped, the agent MUST classify the issue type from the input and ask 1–3 targeted follow-up questions based on the classification.

The agent MUST NOT present questions as a form or checklist. Questions SHOULD be conversational and reference what the agent already understands from the input (e.g., "You mentioned X — can you clarify Y?").

Classification and Question Selection

The agent SHOULD classify the input into one of the following categories and select questions accordingly:

Bug report (input contains language like "fix", "broken", "error", "crash", "doesn't work"):

• What is the expected behavior vs. what actually happens?
• Can you describe the steps to reproduce this, or does it happen inconsistently?
• How severe is this — does it block workflows, or is it a minor annoyance?

Feature request (input contains language like "add", "new", "support", "implement", "enable"):

• Who needs this and what problem does it solve for them?
• What does success look like — can you describe the expected behavior or outcome concretely?
• What should this explicitly NOT do, or what is out of scope for now?

Improvement / Refactor (input contains language like "refactor", "improve", "clean up", "optimize"):

• What is the current limitation or pain point, and why does it matter now?
• What does the improved state look like — how would you verify it is better?
• Are there constraints or things that must NOT change (backward compatibility, API contracts, performance budgets)?

Task / Chore (input contains language like "update", "migrate", "configure", "set up"):

• Are there specific versions, configurations, or targets to hit?
• Are there dependencies or ordering constraints?

If the input does not clearly fit one category, the agent SHOULD ask the user to clarify the nature of the task before selecting follow-up questions.

The agent MUST NOT ask more than 3 questions total. If fewer questions are sufficient, the agent SHOULD ask fewer.

Elicitation Goals

Across all classifications, the interview SHOULD aim to capture:

1. Motivation — Why this change is needed (the problem, user story, or trigger)
2. Success criteria — What concrete, testable conditions define "done"
3. Boundaries — What is explicitly out of scope or must not change

The agent SHOULD prioritize questions that fill gaps in the input. If the user's input already conveys motivation clearly, the agent SHOULD focus remaining questions on success criteria or boundaries instead.

Storing Results

The agent MUST retain the user's answers alongside the original input text for use in Step 6 (Craft Title and Suggest Metadata).

Step 6: Craft Title and Suggest Metadata

Title

The agent MUST refine the user's input text into a clear, concise issue title that:

• Captures the core intent of the request
• Incorporates any clarifications or specifics provided during Step 5 (if it was not skipped)
• Uses sentence case — capitalize the first word only, then lowercase (e.g., "Fix login failure after password reset" not "Fix Login Failure After Password Reset")
• Reads as a short, plain sentence describing the task (not a commit message, command, or formatted label)
• Removes filler words ("the issue where", "we need to", "I want to")
• Remains brief (under 80 characters when practical)

Description

If additional details were gathered in Step 5, the agent MUST generate a description in Markdown following the template below. Each section SHOULD only be included if the interview produced content for it. The agent MUST NOT include empty sections or placeholder text.

Description Template

## Problem / Motivation

<Why this change is needed. User story, problem statement, or trigger. Written from the user's or stakeholder's perspective.>

## Expected Outcome

<What success looks like from the user's perspective. Observable behavior, not implementation details.>

## Acceptance Criteria

- [ ] <Testable condition 1>
- [ ] <Testable condition 2>

## Constraints

- <Boundary, non-goal, or invariant that must hold>

Template Rules

• Problem / Motivation — MUST be included for all non-trivial issues. This is the "why."
• Expected Outcome — SHOULD be included when the interview captured what success looks like. For bug reports, this is the expected (correct) behavior.
• Acceptance Criteria — SHOULD be included for features and improvements. Each criterion MUST be a concrete, testable predicate (e.g., "User can select a timezone from a searchable dropdown" not "Timezone feature works"). Criteria SHOULD be formatted as a task list (- [ ]).
• Constraints — SHOULD be included when the interview identified boundaries, non-goals, or things that must not change. If none were identified, this section MUST be omitted.

For bug reports, the agent MAY replace the template with a simpler structure if more appropriate:

## Problem / Motivation

<What is broken and why it matters>

## Steps to Reproduce

1. <Step 1>
2. <Step 2>

## Expected vs. Actual Behavior

**Expected:** <what should happen>
**Actual:** <what happens instead>

The agent SHOULD choose whichever bug format better fits the information gathered.

If Step 5 was skipped, the agent MAY generate a brief description (1–2 sentences) if the title alone does not fully convey the task's requirements. The agent MUST NOT use the structured template for issues where Step 5 was skipped.

Label Suggestion

The agent SHOULD suggest the most appropriate label by analyzing the input text for keywords:

• Bug-related language (e.g., "fix", "broken", "error", "crash") → bug/defect labels
• Feature-related language (e.g., "add", "new", "support") → feature/enhancement labels
• Improvement language (e.g., "refactor", "improve", "clean up") → improvement labels
• Documentation language (e.g., "document", "README", "guide") → documentation labels

The agent SHOULD also consider details gathered in Step 5 when selecting a label. For example, if the user confirmed during the interview that a task is a regression, a regression-specific label SHOULD be preferred over a generic bug label.

If no label is a strong match, the agent SHOULD default to no label rather than forcing a poor fit.

Milestone Suggestion

If milestones were retrieved in Step 4, the agent SHOULD suggest one using the following priority:

1. A milestone whose name is semantically relevant to the task
2. The nearest upcoming milestone by target date (if no semantic match)
3. The first incomplete milestone by sort order (i.e., the active milestone the project is working toward)

The agent SHOULD default to option 3 when milestones exist but neither semantic relevance nor target dates provide a clear match. The agent SHOULD only skip milestone assignment when no milestones exist for the project.

Priority Suggestion

The agent SHOULD suggest a priority based on the issue classification and severity signals from the interview:

• Urgent (1) — Production-breaking bugs, security vulnerabilities, data loss
• High (2) — Bugs blocking workflows, time-sensitive features
• Normal (3) — Standard features, improvements, most tasks
• Low (4) — Nice-to-haves, minor polish, non-blocking chores

The agent SHOULD infer priority from the interview context:

• Bug reports where the user described the issue as blocking or severe → High or Urgent
• Feature requests with no urgency signal → Normal
• Improvements and refactors → Normal (unless the user expressed urgency)
• Simple chores and housekeeping → Low

If the priority is unclear, the agent SHOULD default to Normal (3).

Step 7: Present Draft for Approval

The agent MUST present the complete issue draft to the user before creating it.

The draft MUST be formatted as a Markdown table with a heading:

### Linear Issue Draft

| Field     | Value                              |
|-----------|------------------------------------|
| Title     | <refined title>                    |
| Team      | <selected team>                    |
| Priority  | <suggested priority>               |
| Project   | <selected project or "None">       |
| Label     | <suggested label or "None">        |
| Milestone | <suggested milestone or "None">    |

If a description was generated, the agent MUST render it as a separate Markdown block immediately after the table under a **Description:** heading.

The agent MUST ask the user to approve, edit, or cancel:

• Approve — create the issue as drafted
• Edit — modify specific fields and re-present the draft
• Cancel — abort issue creation

The agent MUST NOT create the issue without explicit user approval.

Step 8: Create Issue

After the user approves, the agent MUST create the issue using create_issue with the approved details:

• title — the refined title
• team — the resolved team
• priority — the suggested priority
• project — the selected project (if any)
• labels — the suggested label (if any)
• milestone — the selected milestone (if any)
• description — the generated description (if any)

After successful creation, the agent MUST display:

• The issue identifier (e.g., PROJ-123)
• The issue title
• A confirmation message

If creation fails, the agent MUST display the error and offer to retry or cancel.