JesusFilm/core / .agents/skills/linear-to-github
linear-to-github
VerifiedConvert Linear tickets — explicit IDs or whole groups (e.g. a project, label, or milestone) — into GitHub issues in JesusFilm/core on the Next Steps org project board.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
SKILL.md
View on GitHub---
name: linear-to-github
description: Convert Linear tickets — explicit IDs or whole groups (e.g. a project, label, or milestone) — into GitHub issues in JesusFilm/core on the Next Steps org project board.
disable-model-invocation: true
---
# Linear → GitHub
Convert Linear tickets into GitHub issues, one issue per ticket (phased migration, ENG-3688). The GitHub side runs entirely through the `gh` CLI (conventions: `docs/agents/issue-tracker.md`); the Linear side through the Linear MCP tools.
<config>
- **Repo**: `JesusFilm/core`
- **Board**: the [Next Steps org project (#8)](https://github.com/orgs/JesusFilm/projects/8) — the only Project converted issues land on; its Status field, labels, milestones, and stable IDs are the contract in `docs/agents/github-projects.md` (the board doc).
- **Provenance marker**: `<!-- linear:ENG-XXXX -->` as the last line of the issue body — the idempotency key.
</config>
## Process
### 1. Resolve the ticket set
Arguments are any mix of:
- **Ticket IDs or URLs** (`ENG-1234`) — taken as-is.
- **Group selectors** — a Linear project, label, milestone, cycle, or team-plus-state; anything the Linear MCP `list_issues` can filter on. Expand each selector with the matching filter, paging until exhausted; for a project milestone, list the project's issues and keep those in that milestone.
Group expansion keeps open tickets (backlog, unstarted, started); completed and canceled tickets join the set only when the user asks for them. Dedupe across selectors.
**Confirmation gate.** Before converting, show the resolved set (count + `ID — title` lines) and get the user's go-ahead.
Done when every argument is expanded, the set is deduped, and the user has confirmed it.
### 2. Choose the set's board home
Ask the invoker (in the same exchange as step 1's confirmation) where the set lands — **one home is enough**:
- **A feature** — the `feature:<kebab-name>` label, optionally plus its `<feature>: <stage>` phase milestone. List the existing labels to pick from:
```sh
gh label list --repo JesusFilm/core --json name --jq '[.[].name | select(startswith("feature:"))]'
```
Create a new one before use:
```sh
gh label create "feature:<kebab-name>" --repo JesusFilm/core --color 0e7c86
```
- **Or a bug/improvement** — the rolling `bugs` / `improvements` **milestones**. The milestone is the whole home: no label of any kind (there are no `Bug`/`Improvement` labels on this board).
Milestones are one per issue. List them, or create a missing phase (formats in the board doc):
```sh
gh api repos/JesusFilm/core/milestones --jq '.[].title'
gh api repos/JesusFilm/core/milestones -f title="<feature>: <stage>"
```
Plus **anything else** the invoker wants as labels (e.g. `ai-auto-workflow`).
**New feature label → new view.** Views are UI-only — prompt the user to add the feature's view on the board (recipe in the board doc).
The choices apply to every ticket in the set; the invoker can name per-ticket exceptions. Done when each ticket has its home decided and anything newly named exists in the repo.
### 3. Fetch each ticket from Linear
Fetch the full ticket: title, description, comments, labels, project milestone, parent and sub-issue relations, attachments (Linear MCP: `get_issue` with relations, plus `list_comments`).
Then follow the context **one hop**: the parent's description, and any ticket the description or comments lean on — enough of each to know what it contributes. One hop is the boundary; no crawling the graph.
Tickets in a `completed` or `canceled` state are reported and skipped — convert one only when the user asked for it by ID, noting the closed state in the report.
Done when every ticket has every field listed above plus its one-hop context in hand (empty is fine; unfetched is not).
### 4. Check for an existing conversion
For each ticket, find its converted issue: search the visible footer text, then confirm the exact marker — GitHub search does not reliably match inside HTML comments, and a false miss here duplicates the issue:
```sh
gh issue list --repo JesusFilm/core --search 'ENG-XXXX in:body' --state all --json number,url,body
```
A candidate counts only when its body contains the literal `<!-- linear:ENG-XXXX -->` — mere mentions of the ticket in other converted issues also match the search. Issues created earlier in the same run count without searching (search indexing lags fresh issues).
A confirmed hit puts that ticket in **update** mode (reuse the found issue number); none puts it in **create** mode.
Done when every ticket is marked create or update, update tickets carrying their issue number.
### 5. Author the issue
The GitHub issue is **authored, not transcribed** — deliberately not one-to-one with the Linear description. Interpret everything step 3 fetched — description, comments, parent, leaned-on tickets — and write the issue that combines it: what to do, the context that shapes it, decisions that landed in comments or relatives. Each point taken from beyond the ticket's own description links its source. The bar: workable from GitHub alone, no Linear tab open.
Linear ticket mentions anywhere in the authored body become plain links — to the mention's GitHub issue if already converted (marker search as in step 4), otherwise to its Linear URL.
The fixed sections around the authored content:
- **Relations**: parent and sub-issues as links, resolved the same way. Omit the section when there are none.
- **Attachments**: the original Linear URLs, kept rather than re-hosted (`uploads.linear.app` needs a Linear session — say so). Omit the section when there are none.
- **History from Linear**: each comment as author, date, and text — the verbatim record behind the synthesis; in the body, not `gh issue comment` posts (`gh` would misattribute them to the converting account).
- **Footer**: provenance line and marker, recording the original Linear labels and milestone as text (the backfill source for the deferred mapping below).
<body-template>
The authored issue: what to do and the context that shapes it, synthesized from the ticket, its comments, parent, and leaned-on tickets — sources linked.
## Relations
- Parent: [ENG-1111 – title](url)
- Sub-issue: [ENG-2222 – title](url)
## Attachments
- [name](https://uploads.linear.app/...) _(requires Linear access)_
## History from Linear
**Author Name** (2026-07-08):
> Comment text.
---
Converted from Linear [ENG-XXXX](https://linear.app/...) · Linear labels: `a`, `b` · milestone: `M`
<!-- linear:ENG-XXXX -->
</body-template>
Done when every ticket has an authored body that is workable standalone — every load-bearing reference distilled in or linked to a converted GitHub issue — ending in its provenance marker.
### 6. Create or update, then confirm board placement
Write each ticket's body to its own temp file (`body-ENG-XXXX.md`), then per mode, with the step-2 home — `--label` and/or `--milestone` as chosen:
```sh
gh issue create --repo JesusFilm/core --title "..." --body-file body-ENG-XXXX.md --label "<step-2 label>" # create
gh issue edit <number> --repo JesusFilm/core --title "..." --body-file body-ENG-XXXX.md --add-label "<step-2 label>" # update
```
**Per-ticket failure**: record it in the report and continue with the remaining tickets.
**Board placement**: put every issue on the board and set its Status to **Triage** explicitly — the auto-add workflow can lag or leave items at No status:
```sh
item=$(gh project item-add 8 --owner JesusFilm --url <issue-url> --format json --jq .id) # idempotent; returns the item id
gh project item-edit --id "$item" --project-id <project-id> --field-id <status-field-id> --single-select-option-id <triage-option-id> # IDs in the board doc
```
The token needs the `project` scope (`gh auth refresh -s project`). Set a different Status only on request (option IDs in the board doc).
**Relation fix-up (multi-ticket runs)**: after the whole set exists, recompose and `gh issue edit` every member whose Relations or mentions still point at Linear for a ticket this run converted — the step-4 search now resolves them.
Done when every ticket has an issue URL, its step-2 home, a board placement at Triage (or the requested Status), and no member links to Linear for a ticket converted in this run.
### 7. Comment back on Linear
Post one comment on each Linear ticket: `Converted to GitHub: <issue-url>`. Skip when any existing comment already contains that URL. Leave the ticket's state untouched.
Done when every converted ticket has a Linear comment linking its GitHub issue, freshly posted or pre-existing.
### 8. Report
A table: Linear ID → GitHub issue URL, mode (created / updated / skipped + reason / failed + error), board Status, labels and milestone applied.
Done when every input ticket has a row.
## Automatic mapping — deferred
Inferring GitHub labels/milestone from Linear metadata is deferred; each run's choices come from the invoker (step 2). The originals ride in the issue footer as the backfill source — record the mapping table here when it's decided.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |