Skip to main content
linear-data-handling Data synchronization, backup, and consistency patterns for Linear.
Use when implementing data sync, creating backups, exporting data,
or ensuring data consistency between Linear and local state.
Trigger: "linear data sync", "backup linear", "linear export",
"linear data consistency", "sync linear issues".
跳到安装 Skills Marketplace 发现并探索由社区构建的 Agent Skills
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill linear-data-handling命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
下载 Zip 下载中... 同仓库更多 Skills Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
jeremylongshore
jeremylongshore/claude-code-plugins-plus-skills
打开 GitHub 仓库 name linear-data-handling description Data synchronization, backup, and consistency patterns for Linear.
Use when implementing data sync, creating backups, exporting data,
or ensuring data consistency between Linear and local state.
Trigger: "linear data sync", "backup linear", "linear export",
"linear data consistency", "sync linear issues".
allowed-tools Read, Write, Edit, Grep, Bash(node:*) version 1.12.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","linear","backup"] compatibility Designed for Claude Code, also compatible with Codex and OpenClaw
Linear Data Handling
Overview
Implement reliable data synchronization, backup, and consistency for Linear integrations. Covers full sync, incremental webhook sync, JSON/CSV export, consistency checks, and conflict resolution.
Prerequisites
@linear/sdk with API key configuredDatabase for local storage (any ORM — Drizzle, Prisma, Knex)
Understanding of eventual consistency
Instructions
Step 1: Data Model Schema
import { z } from "zod" ;
export const LinearIssueSchema = z.object ({
id : z.string ().uuid (),
identifier : z.string (),
title : z.string (),
description : z.string ().nullable (),
priority : z.number ().int ().min (0 ).max (4 ),
estimate : z.number ().nullable (),
stateId : z.string ().uuid (),
stateName : z.string (),
stateType : z.string (),
teamId : z.string ().uuid (),
teamKey : z.string (),
assigneeId
string
uuid
nullable
projectId
string
uuid
nullable
cycleId
string
uuid
nullable
parentId
string
uuid
nullable
dueDate
string
nullable
createdAt
string
updatedAt
string
completedAt
string
nullable
canceledAt
string
nullable
syncedAt
string
export
type
LinearIssue
infer
typeof
LinearIssueSchema
Step 2: Full Sync Paginate through all issues, resolve relations, and upsert locally.
import { LinearClient } from "@linear/sdk" ;
interface SyncStats {
total : number ;
created : number ;
updated : number ;
deleted : number ;
errors : number ;
}
async function fullSync (client : LinearClient , teamKey : string Promise <SyncStats > {
const stats : SyncStats = { total : 0 , created : 0 , updated : 0 , deleted : 0 , errors : 0 };
const remoteIds = new Set <string >();
let cursor : string | undefined ;
let hasNext = true ;
while (hasNext) {
const result = await client.client .rawRequest (`
query FullSync($teamKey: String!, $cursor: String) {
issues(
first: 100,
after: $cursor,
filter: { team: { key: { eq: $teamKey } } },
orderBy: updatedAt
) {
nodes {
id identifier title description priority estimate
dueDate createdAt updatedAt completedAt canceledAt
state { id name type }
team { id key }
assignee { id }
project { id }
cycle { id }
parent { id }
}
pageInfo { hasNextPage endCursor }
}
}
` , { teamKey, cursor });
const issues = result.data .issues ;
for (const issue of issues.nodes ) {
remoteIds.add (issue.id );
stats.total ++;
try {
const mapped : LinearIssue = {
id : issue.id ,
identifier : issue.identifier ,
title : issue.title ,
description : issue.description ,
priority : issue.priority ,
estimate : issue.estimate ,
stateId : issue.state .id ,
stateName : issue.state .name ,
stateType : issue.state .type ,
teamId : issue.team .id ,
teamKey : issue.team .key ,
assigneeId : issue.assignee ?.id ?? null ,
projectId : issue.project ?.id ?? null ,
cycleId : issue.cycle ?.id ?? null ,
parentId : issue.parent ?.id ?? null ,
dueDate : issue.dueDate ,
createdAt : issue.createdAt ,
updatedAt : issue.updatedAt ,
completedAt : issue.completedAt ,
canceledAt : issue.canceledAt ,
syncedAt : new Date ().toISOString (),
};
const existing = await db.issues .findById (issue.id );
if (existing) {
await db.issues .update (issue.id , mapped);
stats.updated ++;
} else {
await db.issues .insert (mapped);
stats.created ++;
}
} catch (error) {
stats.errors ++;
console .error (`Error syncing ${issue.identifier} :` , error);
}
}
hasNext = issues.pageInfo .hasNextPage ;
cursor = issues.pageInfo .endCursor ;
if (hasNext) await new Promise (r =>setTimeout (r, 100 ));
}
const localIds = await db.issues .listIds ({ teamKey });
for (const localId of localIds) {
if (!remoteIds.has (localId)) {
await db.issues .softDelete (localId);
stats.deleted ++;
}
}
console .log (`Full sync complete:` , stats);
return stats;
}
Step 3: Incremental Sync via Webhooks async function processWebhookSync (event : {
action: "create" | "update" | "remove" ;
type : string ;
data: any ;
}if (event.type !== "Issue" ) return ;
const syncedAt = new Date ().toISOString ();
switch (event.action ) {
case "create" :
await db.issues .insert ({
id : event.data .id ,
identifier : event.data .identifier ,
title : event.data .title ,
description : event.data .description ,
priority : event.data .priority ,
estimate : event.data .estimate ,
stateId : event.data .stateId ?? event.data .state ?.id ,
stateName : event.data .state ?.name ?? "Unknown" ,
stateType : event.data .state ?.type ?? "unknown" ,
teamId : event.data .teamId ?? event.data .team ?.id ,
teamKey : event.data .team ?.key ?? "" ,
assigneeId : event.data .assigneeId ?? null ,
projectId : event.data .projectId ?? null ,
cycleId : event.data .cycleId ?? null ,
parentId : event.data .parentId ?? null ,
dueDate : event.data .dueDate ?? null ,
createdAt : event.data .createdAt ,
updatedAt : event.data .updatedAt ,
completedAt : event.data .completedAt ?? null ,
canceledAt : event.data .canceledAt ?? null ,
syncedAt,
});
break ;
case "update" :
await db.issues .update (event.data .id , {
...event.data ,
syncedAt,
});
break ;
case "remove" :
await db.issues .softDelete (event.data .id );
break ;
}
}
Step 4: Data Export / Backup async function exportToJson (client : LinearClient , outputDir : string const timestamp = new Date ().toISOString ().replace (/[:.]/g , "-" );
const teams = await client.teams ();
const backup = {
exportedAt : new Date ().toISOString (),
version : "1.0" ,
teams : teams.nodes .map (t =>id : t.id , key : t.key , name : t.name })),
projects : [] as any [],
issues : [] as any [],
};
const projects = await client.projects ();
backup.projects = projects.nodes .map (p =>id : p.id , name : p.name , state : p.state ,
targetDate : p.targetDate , progress : p.progress ,
}));
for (const team of teams.nodes ) {
let cursor : string | undefined ;
let hasNext = true ;
while (hasNext) {
const result = await client.issues ({
first : 100 ,
after : cursor,
filter : { team : { id : { eq : team.id } } },
});
for (const issue of result.nodes ) {
backup.issues .push ({
id : issue.id ,
identifier : issue.identifier ,
title : issue.title ,
description : issue.description ,
priority : issue.priority ,
estimate : issue.estimate ,
createdAt : issue.createdAt ,
updatedAt : issue.updatedAt ,
});
}
hasNext = result.pageInfo .hasNextPage ;
cursor = result.pageInfo .endCursor ;
if (hasNext) await new Promise (r =>setTimeout (r, 100 ));
}
}
const path = `${outputDir} /linear-backup-${timestamp} .json` ;
await fs.writeFile (path, JSON .stringify (backup, null , 2 ));
console .log (`Exported ${backup.issues.length} issues to ${path} ` );
}
Step 5: Consistency Check async function checkConsistency (client : LinearClient , teamKey : string Promise <{
missing : string [];
stale : string [];
orphaned : string [];
}> {
const remote = await client.issues ({
first : 50 ,
filter : { team : { key : { eq : teamKey } } },
orderBy : "updatedAt" ,
});
const missing : string [] = [];
const stale : string [] = [];
for (const issue of remote.nodes ) {
const local = await db.issues .findById (issue.id );
if (!local) {
missing.push (issue.identifier );
} else if (local.updatedAt < issue.updatedAt ) {
stale.push (issue.identifier );
}
}
const orphaned : string [] = [];
const localSample = await db.issues .findRecent (50 );
for (const local of localSample) {
try {
await client.issue (local.id );
} catch {
orphaned.push (local.identifier );
}
}
const result = { missing, stale, orphaned };
console .log (`Consistency check: ${missing.length} missing, ${stale.length} stale, ${orphaned.length} orphaned` );
if (missing.length > 10 || stale.length > 10 ) {
console .warn ("High inconsistency — triggering full sync" );
await fullSync (client, teamKey);
}
return result;
}
Step 6: Conflict Resolution type ConflictStrategy = "remote-wins" | "local-wins" | "merge" | "manual" ;
interface ConflictResult {
resolved : boolean ;
strategy : ConflictStrategy ;
winner : "local" | "remote" | "merged" ;
}
function resolveConflict (
local : LinearIssue ,
remote : any ,
strategy : ConflictStrategy ,
mergeFields ?: string []
): ConflictResult {
switch (strategy) {
case "remote-wins" :
db.issues .update (remote.id , { ...remote, syncedAt : new Date ().toISOString () });
return { resolved : true , strategy, winner : "remote" };
case "local-wins" :
return { resolved : true , strategy, winner : "local" };
case "merge" :
const merged = { ...local };
for (const field of mergeFields ?? ["title" , "priority" , "stateId" ]) {
(merged as any )[field] = remote[field];
}
merged.syncedAt = new Date ().toISOString ();
db.issues .update (remote.id , merged);
return { resolved : true , strategy, winner : "merged" };
case "manual" :
throw new Error (`Conflict on ${local.identifier} requires manual resolution` );
}
}
Error Handling Issue Cause Solution Sync timeout Too many records Use smaller page sizes, add delays Conflict detected Concurrent edits Apply conflict resolution strategy Stale data Missed webhook events Trigger full sync via consistency check Export failed Rate limit during backup Add 100ms delay between pagination calls Duplicate entries Webhook retry without dedup Deduplicate by Linear-Delivery header
Resources 