Linear Create

Create Linear Issue

Create a Linear issue with a structured five-section body (Context, What, Why, Scope, Solution) and wizard-selected status, label, and assignee. This is the Linear counterpart to issue-create (which files GitHub issues): use it on a project that lists a linear tracker in package.json agents.trackers. The body uses the same fixed five-section structure as issue-create; the Linear-specific metadata (status, labels, assignee) is chosen through a short wizard.

When to Use

• Filing a new Linear ticket on a linear-tracked project
• When invoked from other skills that need to open a Linear issue

Input

Arguments: $ARGUMENTS

Expected form:

• [title hint or short description] — optional free-form hint that seeds the title and body (e.g., "users cannot reset password via email").

Input resolution

• Title hint — $ARGUMENTS → if empty, prompt once via AskUserQuestion: "What is this issue about?" with a free-form slot. Do not abort silently.
• Linear team — collect every linear entry of agents.trackers in the repo-root package.json (via the Read tool) and resolve a single target team in Phase 0. REQUIRED. If no linear tracker is configured, stop and tell the user to file a GitHub issue with /autopilot:issue-create instead.
• Repo label — the chosen linear entry's optional label, pre-selected in Phase 4.

Completion Requirement

This workflow is not complete until Phase 7 calls the Linear MCP save_issue tool and outputs the created issue identifier and URL. Generating a title, body, or wizard selections does not constitute completion.

Linear MCP access: Read linear-mcp-access.md and apply its tool-resolution rule, using the bare tool names save_issue, list_issue_statuses, list_issue_labels.

Phase 0: Resolve Team and Hint

1. Parse $ARGUMENTS as an optional title hint; if empty, prompt once via AskUserQuestion. Retain the resolved hint verbatim (the raw $ARGUMENTS, or the user's exact AskUserQuestion answer — unmodified, un-paraphrased) as the original prompt; Phase 2 emits it as a collapsed preamble at the top of the body.
2. Read package.json and collect all linear entries from agents.trackers, then resolve a single target team:
   • None ⇒ stop: This project is not Linear-tracked. Use /autopilot:issue-create for a GitHub issue.
   • Exactly one ⇒ use its team (and label) — no prompt.
   • Two or more ⇒ ask the user which team to file on via AskUserQuestion (single-select): one option per linear entry, { label: "<team>", description: "<comma-joined keys, or 'no keys'>" }. Bind the chosen entry's team and optional label for the rest of the wizard.

Phase 1: Gather Context

Read metadata.md now and launch its independent metadata reads alongside code-context work. Do not refetch them in selection phases.

Mirror issue-create so the body reflects real code, not hallucinated structure. Unlike issue-create, this skill deliberately omits related-issue/PR detection and the duplicate-warning check — Linear search is not wired through the MCP here, so surfacing related work is out of scope.

1. Search for files/symbols related to the hint with Grep and Glob, then Read the matched sections only.
2. Collect git context (git log -20 --oneline, git status --short).
3. External documentation (best-effort): for a library/framework question, start with required Context7 or one authoritative source; use another provider only for a named gap or an explicit request. On error or empty result, continue — never block creation on MCP availability.

Phase 2: Generate Title and Body

Title: capitalized, ≤ 80 characters, no trailing period, business-focused, NOT Conventional Commits, no prefix.

Body: read issue-body-grammar.md and apply it — the five-section structure, the per-section rules, and the linkability pass that runs after drafting. Links must use the absolute <repo-blob-url> form because the body is posted outside the repo, where relative paths do not resolve.

Original-prompt preamble (prepend last). After the linkability pass, prepend the user's original prompt — the title hint resolved verbatim in Phase 0 — to the top of the body as a collapsed section, so the ticket records exactly what was asked, not only its structured interpretation. Use Linear's GraphQL collapsible fence (+++ Section title to open, +++ to close), documented in the Linear API docs; its content renders initially hidden. Do NOT use <details> HTML — Linear does not render it. Emit the block above ## Context:

+++ Original prompt

<the Phase 0 hint, verbatim>

+++

then a blank line, then the five-section body. This preamble is a permitted metadata block above ## Context; it is not one of the five sections, so it does not change the mandatory section order. Prepend it after the linkability pass and treat the fence content as opaque — like a code specimen, the user's text inside it is never link-transformed or reworded.

Because the hint is reproduced verbatim (unlike the five sections, which paraphrase the input), any secret or PII pasted into it lands unfiltered in the ticket. Do not put credentials, tokens, or personal data in the hint; the Phase 6 preview is the checkpoint to catch and remove any that slipped in before the ticket is created.

Phase 3: Select metadata

Use the candidates fetched during Phase 1. Present status, labels, and assignee in one multi-question interaction when supported; otherwise ask only unresolved fields sequentially. Defaults are suggestions, never submitted choices. Preserve user-supplied valid selections without asking again. Include Leave unassigned and mark the returned self candidate as recommended. Never invent a candidate. The final preview still shows every selected field.

Phase 4: Select Labels

Labels are selected in the combined metadata interaction above from the fetched team list.

Phase 5: Resolve Assignee

Assignee candidates are resolved once through metadata.md and selected in Phase 3.

Phase 6: Verify with User

Present the full issue via AskUserQuestion with a preview carrying the title, the collapsible original-prompt preamble followed by the five-section body, and a metadata line Team: <team> · Status: <status> · Labels: <labels> · Assignee: <assignee or unassigned>. Options: Create issue / Edit content / Cancel, all sharing the same preview. Only proceed to Phase 7 after Create issue.

Phase 7: Create Issue

This phase is mandatory. Create the ticket. The description is the full body assembled in Phase 2 — the collapsible original-prompt preamble followed by the five-section body — so the created ticket carries the preamble, not only its Phase 6 preview:

Linear MCP save_issue  with {
  "title": "<title>",
  "team": "<team>",
  "description": "<original-prompt preamble + five-section body>",
  "state": "<selected status>",
  "labels": ["<selected labels>"],
  "assignee": "<selected assignee, omit when unassigned>"
}

Output the result:

✓ Created Linear issue: <identifier> — <url>

When you generate the issue body, apply the reference-formatting rules in reference-formatting.md (RFC-0001, read it first) to every reference it contains — link files, docs, skills, agents, sections, and commit SHAs as absolute <repo-blob-url> URLs (the body is posted outside the repo, where relative paths do not resolve), link cited external resources to their canonical source URL, and never leave a reference as bare text.