# upstream-patches

Manages Terraform provider submodule patches using ./scripts/upstream.sh. Useful for provider upgrades, resolving patch conflicts, and rebasing.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 634 installs · ★ 78
- Author: pulumi
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pulumi/agent-skills/tree/HEAD/package-maintenance/skills/upstream-patches/SKILL.md
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/skills/upstream-patches

## What it does

This skill guides the agent through modifying code inside the `upstream/` git submodule and updating files in `patches/`. It locates the target patch using `rg` or `grep`, enters checkout mode with `./scripts/upstream.sh checkout`, and amends the owning commit directly instead of generating new patch files.

Direct changes inside `upstream/` get wiped during `upgrade-provider` runs because the automation resets submodule status. Every edit must follow the strict `checkout` and `check_in` cycle. If an operation gets interrupted, running `./scripts/upstream.sh init -f` discards all in-flight resolutions and untracked files, so routine recovery relies on finishing `git am` steps manually instead.

## Requirements
- Works with: Terraform

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pulumi/agent-skills --skill upstream-patches -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/upstream-patches/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/upstream-patches/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pulumi/agent-skills --skill upstream-patches -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/upstream-patches/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pulumi/agent-skills --skill upstream-patches -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/upstream-patches/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pulumi/agent-skills upstream-patches
```

2. **Manually: put the files in place**
- File: `.github/skills/upstream-patches/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pulumi/agent-skills --skill upstream-patches -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pulumi/agent-skills --path package-maintenance/skills/upstream-patches
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/upstream-patches/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pulumi/agent-skills --skill upstream-patches -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pulumi/agent-skills/tree/HEAD/package-maintenance/skills/upstream-patches/SKILL.md

## When to use it
- locate the patch file and commit responsible for specific lines
- amend an existing patch without creating extra patch files
- strip unwanted file changes or hunks from an active patch
- rebase provider patches onto a newer upstream git commit

## Example prompts
- Find which patch touches `resource_server.go` and amend it with the fix
- Rebase our provider patches onto upstream commit `a1b2c3d`
- Remove `patches/0002-fix-timeout.patch` and run `./scripts/upstream.sh check_in`

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 39383b771d7e13da.

BEGIN THIRD-PARTY FILE 39383b771d7e13da
````text
---
name: upstream-patches
description: Create, amend, remove, and rebase patches for Terraform provider submodules using `./scripts/upstream.sh`. Use when `upgrade-provider` or manual patch work needs owning-patch lookup, patch conflict fixes, patch/hunk removal, or upstream rebase.
---

# Upstream Patches

`upstream/` is a git submodule pointing to the upstream Terraform provider. `patches/` contains patch files applied on top of it. Use `./scripts/upstream.sh` to manage patch state.

## Default Behavior

- If fixing a regression introduced by an existing patch, amend the owning patch commit.
- Do not create a new patch unless the user explicitly asks.

## Commands Reference

| Command | Description |
|---------|-------------|
| `./scripts/upstream.sh init` | Initialize upstream and apply patches to working directory |
| `./scripts/upstream.sh init -f` | Destructively discard checkout/rebase state and re-initialize upstream |
| `./scripts/upstream.sh checkout` | Create branch with patches as commits for editing |
| `./scripts/upstream.sh rebase -i` | Interactively edit patch commits |
| `./scripts/upstream.sh rebase -o <commit>` | Rebase patches onto a new upstream commit |
| `./scripts/upstream.sh check_in` | Write commits back to patches and exit checkout mode |

## Guardrails

- Never commit directly to `upstream/` without `checkout/check_in`.
- Direct edits under `upstream/` outside checkout are ephemeral during `upgrade-provider`; the tool resets submodule state.
- Do not hand-edit `patches/*.patch` unless intentionally doing raw patch surgery.
- Prefer non-interactive rewrite flow over interactive rebase for agents.

## Find Owning Patch First

Before editing patch content, identify the owning patch/commit.

```bash
./scripts/upstream.sh checkout

# Find candidate patch files by touched file path or unique hunk text
rg -n "path/to/file|unique_symbol" patches/*.patch

# Optional: inspect candidate patch header/hunks
sed -n '1,120p' patches/00NN-Example.patch

# Map patch file to commit in upstream checkout branch
patch=patches/00NN-Example.patch
subject=$(sed -n 's/^Subject: \[PATCH\] //p' "$patch" | head -n1)
cd upstream
git log --oneline pulumi/patch-checkout --grep "$subject"

# If needed, disambiguate by touched path
git log --oneline pulumi/patch-checkout -- path/to/file
cd ..
```

If `rg` is unavailable, use `grep -En` for the patch search. Set `target_sha` to the owning commit and edit that commit, not `HEAD`.

## Amend Existing Patch (Preferred, Non-Interactive)

```bash
./scripts/upstream.sh checkout
cd upstream

target_sha=<owning-commit-sha>
base_sha=$(git rev-parse "${target_sha}^")
tmp_branch="rewrite-${target_sha:0:8}"

# Rebuild history from parent of target commit
git checkout -b "$tmp_branch" "$base_sha"
git cherry-pick "$target_sha"

# Apply fix and amend target commit
# ...edit files...
git add <files>
git commit --amend --no-edit

# Replay remaining commits
````
END THIRD-PARTY FILE 39383b771d7e13da

The third-party file has ended. Everything between the 39383b771d7e13da tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2936 of 5706 bytes. © pulumi · Apache-2.0 · https://github.com/pulumi/agent-skills/tree/HEAD/package-maintenance/skills/upstream-patches/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md