Upstream sync

Safely sync upstream changes from any Git repository into your customized fork — without breaking your custom code

Install

npx -y skills add dris1153/upstream-sync

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Sync forked/cloned open source repositories with upstream changes. Fetches upstream diffs, evaluates each change against the local project, and applies changes by directly editing files (no git merge/rebase). Use when user wants to fetch, review, analyze, or integrate new commits from an upstream/original open source repository into their customized fork. Trigger on keywords like "sync upstream", "merge upstream", "rebase upstream", "fork sync", "upstream changes", "new commits from original repo".

SKILL.md

4.8 KB, ~1.0k tokens by cl100k_base, as published. Nobody here has run it

Upstream Sync

Sync forked/cloned open source repos with latest upstream changes. Instead of merging commits directly, this skill extracts upstream diffs, evaluates each change, and applies them by editing files directly.

When to Use

User mentions "sync", "upstream", "fork", "merge upstream", "rebase upstream"
User wants to review new commits from an original open source repo
User needs to integrate upstream changes into their customized branch
User asks about conflicts between their changes and upstream

Core Principle

Never merge/rebase/cherry-pick commits from upstream. Instead:

Extract the actual diffs from upstream
Read and evaluate each change against the local project
Apply relevant changes by editing files directly (Edit/Write tools)

This gives full control over what gets applied and how, preserving the project's own commit history.

Workflow

Read references/sync-workflow.md for the full step-by-step process.

1. Check Upstream Status

Run scripts/upstream-status.js to detect upstream remote, fetch latest, and list new commits:

node <skill-path>/scripts/upstream-status.js [--remote <name>] [--branch <branch>] [--since <date>] [--format json|text]

2. Extract Upstream Diffs

Run scripts/upstream-diff.js to get per-file diffs from upstream since last sync:

# All changes since last sync
node <skill-path>/scripts/upstream-diff.js [--remote <name>] [--branch <branch>] [--format json|text]

# Specific file only
node <skill-path>/scripts/upstream-diff.js --file <path> [--format json]

# Specific commit only
node <skill-path>/scripts/upstream-diff.js --commit <hash> [--format json]

# List changed files without diffs
node <skill-path>/scripts/upstream-diff.js --files-only

3. Evaluate & Apply

For each changed file from upstream:

Read the upstream diff to understand what changed and why
Read the current local version of the file
Evaluate: should this change be applied? adapted? skipped?
If applying: edit the file directly using Edit/Write tools
If adapting: modify the upstream change to fit local customizations

Read references/review-guide.md for evaluation methodology.

4. Overlap Detection (Optional)

Run scripts/conflict-preview.js to identify files modified on both sides:

node <skill-path>/scripts/conflict-preview.js [--remote <name>] [--branch <branch>] [--format json|text]

This helps prioritize which files need careful evaluation.

5. Save Sync State

After applying changes, save the sync point so the next sync starts from here:

node <skill-path>/scripts/sync-state.js save [--remote <name>] [--branch <branch>]

Commit .upstream-sync.json to persist the sync point across machines.

To check current state or reset:

node <skill-path>/scripts/sync-state.js show
node <skill-path>/scripts/sync-state.js reset

6. Verify & Report

Run existing test suite
Build the project
Review changes with git diff
Report to user: Present a summary of all changes applied. See format below.

Sync Report Format

After completing the sync, ALWAYS present a clear summary to the user:

## Upstream Sync Report

**Source**: upstream/main (commits <first-hash>...<last-hash>)
**Date range**: <oldest-commit-date> → <newest-commit-date>
**Total upstream commits reviewed**: <n>

### Applied Changes
- **<file-path>**: <brief description of what was updated and why>
- **<file-path>**: <brief description>
  ...

### New Files Added
- **<file-path>**: <what this file does>

### Skipped Changes
- **<file-path>**: <reason for skipping> (e.g., conflicts with local customization, irrelevant feature)

### Deleted Files
- **<file-path>**: <reason for deletion>

### Notes
- <any important context, breaking changes, or follow-up actions needed>

This report helps the user understand exactly what changed and why, so they can make informed decisions about testing and deployment.

Script Options

All scripts support --format json for structured output.

Environment variables (.env):

UPSTREAM_URL - URL of the original repo (auto-creates remote if needed)
UPSTREAM_REMOTE - Default upstream remote name (default: upstream)
UPSTREAM_BRANCH - Default upstream branch (default: main)