Skip to content

Instantly share code, notes, and snippets.

@compwron

compwron/SKILL.md

Created April 8, 2026 19:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save compwron/2429eb859c8ffdb3da2bce027c1e57d9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save compwron/2429eb859c8ffdb3da2bce027c1e57d9 to your computer and use it in GitHub Desktop.
Download ZIP
jira-to-linear: Import Jira issues into Linear via MCP
Raw
SKILL.md
name jira-to-linear
description Import Jira issues into Linear by reading from the Atlassian MCP and creating new issues via the Linear MCP. Use when the user wants to migrate, import, or move issues from Jira to Linear.

Jira to Linear Issue Import

Pre-flight Checks

Before anything else, confirm both MCPs are available:

  1. Atlassian MCP: Check if the user-Atlassian MCP server is accessible. If its STATUS.md indicates authentication is needed, call mcp_auth for user-Atlassian and wait for the user to complete the OAuth flow. If the server is not enabled at all, stop and tell the user to enable the Atlassian MCP in Cursor settings.
  2. Linear MCP: Call list_teams on user-linear with limit: 1. If it succeeds, the MCP is ready. If it errors, stop and tell the user to enable/authenticate the Linear MCP.

Only proceed once both MCPs respond successfully.

Linear teams (required — do not create)

This flow only creates Linear issues. It must not create a Linear team or project.

  • Call list_teams on user-linear and require the user to pick a destination team from that list (prefer the team's ID from the response when passing team to save_issue).
  • If the user names a team that does not appear in list_teams, stop and ask them to choose an existing team. Do not create a team, call save_project, or use any Linear MCP tool whose purpose is creating teams or projects.
  • Do not infer a new team from Jira project name, component, or label — Jira metadata is for mapping fields only, not for provisioning Linear structure.

Step 1: Gather Inputs

Ask the user for:

  1. Jira Issue IDs — fully qualified keys (e.g., PROJ-123, PROJ-456).
  2. Destination Linear Team — must be one of the teams returned by list_teams on user-linear (see Linear teams above). Present the list and have the user confirm which team to use.

Step 2: Load Linear Context

Before importing, fetch the destination team's labels and statuses so you can map correctly:

  • Call list_issue_labels with the destination team to get available labels.
  • Call list_issue_statuses with the destination team to get available statuses.

Hold these in memory for mapping in the next steps.

Step 3: Fetch Jira Issues

For each Jira issue ID, use the Atlassian MCP getJiraIssue (same tool name as in the Cursor Atlassian integration; read its schema before calling). Pass cloudId and the issue key as required by that tool.

From each response, extract at minimum:

  • Summary / title
  • Description (convert to Markdown if needed)
  • status — use the exact name string returned by the MCP (e.g. To Do, In-Progress), not a guess
  • statusCategory (or equivalent) if present — Jira exposes categories such as To Do, In Progress, Done; use them to disambiguate similarly named workflows
  • Resolution (if present) — e.g. Duplicate, Won't Do — to choose Linear Duplicate or Canceled even when the status name alone is unclear
  • Priority
  • Labels
  • Assignee
  • Due date
  • Issue links / blockers (for reference in the description)

Do not invent Jira status names. Every mapping decision must be traceable to fields returned by getJiraIssue.

Step 4: Map Fields

Status Mapping

Target Linear workflow states (use names that exist on the destination team from list_issue_statuses): Triage, Backlog, Todo, In Progress, In Review, Done, Canceled, Duplicate.

1. Prefer MCP fields. For each issue, map using the live getJiraIssue payload in this order:

  1. If resolution or status clearly indicates Duplicate → Linear Duplicate
  2. If resolution or status clearly indicates Won't Fix / Canceled / Cancelled → Linear Canceled
  3. Otherwise combine status name + status category to pick the closest Linear state

2. Parachute WF project (reference). Issues on parachutehealth.atlassian.net / project WF use the workflow documented in plugins/z-quainjn-plugin/skills/jira/SKILL.md. The MCP returns these status names (with Jira categories as documented there). Map them as follows:

Jira status (from MCP) Jira category Linear state
To Do To Do Backlog
Icebox To Do Backlog
Scoping To Do Triage
UX To Do Todo
Engineering Review To Do In Review
Ready for IPM To Do Backlog
Current Queue To Do Todo
In-Progress In Progress In Progress
PR Review In Progress In Review
In Acceptance In Progress In Review
Accepted Done Done
Completed Done Done
Canceled Done Canceled

If you encounter a WF status not listed (e.g. after workflow changes), use getTransitionsForJiraIssue on a sample issue in that status to confirm the canonical status name, then map from category + name and ask the user once if still ambiguous.

3. Other sites / projects. Collect the unique status.name values from the fetched issues, propose a one-time mapping table to the Linear states above, and ask the user to confirm or adjust before bulk-creating. Reuse the same mapping for all issues in that batch.

If a Jira status still does not clearly map after the above, ask the user how to handle it. Batch ambiguous statuses into a single question rather than asking one at a time.

Labels

Compare each Jira issue's labels against the labels fetched from Linear in Step 2 (case-insensitive match). Only attach labels that already exist in Linear. Do not create new labels. Silently drop labels that have no match — do not ask about every missing label.

Priority

In Linear's UI, priority is shown as labels (with keyboard shortcuts), not as numbers: No priority, Urgent, High, Medium, Low.

The Linear MCP save_issue tool still takes priority as a number that matches those levels: 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low. Use that field when creating issues; think in terms of the Linear label, then set the corresponding number.

Jira priority (from getJiraIssue) Linear (UI) save_issue.priority
Highest / Critical / Blocker Urgent 1
High High 2
Medium Medium 3
Low Low 4
Lowest / Trivial Low 4
Unset / None No priority 0 (or omit if the tool treats omission as none)

Description

Prepend a brief provenance note to the description:

> Imported from Jira: [PROJ-123](https://your-domain.atlassian.net/browse/PROJ-123)

Preserve the original description content in Markdown.

Step 5: Create Linear Issues

For each mapped issue, call save_issue on user-linear with:

  • title — original Jira summary
  • description — mapped description with provenance note
  • team — the destination team ID or identifier from Step 1 (must still match a team from list_teams; never substitute a newly created team)
  • state — the mapped Linear status name
  • priority — number matching Linear's labeled levels (0–4; see Priority section)
  • labels — only matching label names
  • dueDate — if present, in ISO format
  • links — attach the original Jira URL as a link: [{url: "https://...", title: "Original Jira issue: PROJ-123"}]

Do not set assignee — ownership will be re-triaged in Linear.

If a creation fails, log the error and continue with remaining issues. Report failures at the end.

Step 6: Summary Table

After all issues are processed, output a Markdown table:

| Jira ID | Jira Title | Jira Link | Linear ID | Linear Link | Notes |
|---------|------------|-----------|-----------|-------------|-------|
| PROJ-123 | Fix login bug | [PROJ-123](https://...) | TEAM-45 | [TEAM-45](https://...) | |
| PROJ-456 | Add search | [PROJ-456](https://...) | — | — | Failed: <reason> |

Include a Notes column for any issues that failed or had ambiguous mappings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment