How do I install the Buf Bump skill?

Run npx skillmds@latest add mark2685/buf-bump in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Buf Bump safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Buf Bump?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Buf Bump free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Buf Bump?

mark2685 (@mark2685) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Buf Bump by mark2685 — Agent Skill

Name: Buf Bump
Author: mark2685

Buf Bump

Bumps generated protobuf packages in the flow-frontend monorepo and fixes the resulting TypeScript breakage. Use when the user says "buf bump", "bump protos", "update proto types", "pull the latest protos for a service", or "/buf-bump". User-invoked only — this rewrites package pins and patches consuming code.

mark2685 fa59aeb 3.2 KB Updated Sep 17, 2026

File contents

Proto Bump Workflow

Runs in flow-frontend. Updates the @bufteam/* proto packages pinned in the pnpm-workspace.yaml catalog and resolves the TypeScript breakage in consuming code. The packages are prebuilt on the BSR npm registry (hadrian.buf.dev/gen/npm/v1) — nothing is built locally; pnpm install fetches them. Side-effecting: it mutates lockfiles, reinstalls, and edits source. User-invoked only.

Prerequisites

Authenticated to the Buf registry: buf registry login hadrian.buf.dev (cross-repo requirement). Without it, buf-bump:* cannot resolve the upstream modules.

Step 0: Confirm scope

Ask which service(s) to bump. Read the available targets from the root package.json — do not rely on a memorized list. They drift:

node -e "console.log(Object.keys(require('./package.json').scripts).filter(s=>s.startsWith('buf-bump')).join('\n'))"

buf-bump:main pulls every service from main; buf-bump:<service> pulls one.

Steps

Capture the before-state so you can prove the bump changed something: git diff --stat pnpm-workspace.yaml > /tmp/buf-before.txt
Run pnpm buf-bump:<service> (or pnpm buf-bump:main).
Canary — verify the bump actually changed versions. Run git diff pnpm-workspace.yaml. If it is empty, the pins were already current OR the bump silently no-op'd (bad auth, wrong service). Stop and report — do not proceed as if it succeeded.
Install. The bump script runs pnpm install itself; it is what actually fetches the prebuilt packages. Canary: git diff --stat pnpm-lock.yaml must show the new @bufteam/* versions. If the lockfile is unchanged, the install pulled nothing — stop and report; do not proceed as if it succeeded. (If the script's install step failed, run pnpm install yourself and re-check.)
Type-check with pnpm lint:tsc to surface breakage.
Fix the breakage, distinguishing mechanical from non-mechanical:
- Mechanical (renamed field, widened type, new optional field): update the rpcToForm* / formToRpc* converters, server actions referencing the RPC, and direct proto usage in components. Use *Required types from hadrian_protoc-gen-es-required for form validation.
- Non-mechanical (a field was removed, an enum value dropped, semantics changed): escalate to the user. A removed field is a backend contract change — surface it; do not silently insert a null-check or default that hides lost data.
Test with pnpm test.
Report the version delta (from step 3), what you fixed mechanically, and any non-mechanical changes you escalated.

Gotchas

Do not run pnpm build:rpc as part of a bump. Its turbo filter (turbo build --filter *-proto) matches zero workspace packages — the proto packages moved to prebuilt BSR npm packages (Nov 2024), so there is nothing to build locally.

---name: buf-bumpdescription: Bumps generated protobuf packages in the flow-frontend monorepo and fixes the resulting TypeScript breakage. Use when the user says "buf bump", "bump protos", "update proto types", "pull the latest protos for a service", or "/buf-bump". User-invoked only — this rewrites package pins and patches consuming code.---# Proto Bump WorkflowRuns in **flow-frontend**. Updates the `@bufteam/*` proto packages pinned in the`pnpm-workspace.yaml` catalog and resolves the TypeScript breakage in consuming code. Thepackages are prebuilt on the BSR npm registry (`hadrian.buf.dev/gen/npm/v1`) — nothing isbuilt locally; `pnpm install` fetches them. Side-effecting: it mutates lockfiles, reinstalls,and edits source. User-invoked only.## Prerequisites- Authenticated to the Buf registry: `buf registry login hadrian.buf.dev` (cross-repo requirement). Without it, `buf-bump:*` cannot resolve the upstream modules.## Step 0: Confirm scopeAsk which service(s) to bump. Read the available targets from the root `package.json` —do not rely on a memorized list. They drift:```bashnode -e "console.log(Object.keys(require('./package.json').scripts).filter(s=>s.startsWith('buf-bump')).join('\n'))"````buf-bump:main` pulls every service from `main`; `buf-bump:<service>` pulls one.## Steps1. **Capture the before-state** so you can prove the bump changed something: `git diff --stat pnpm-workspace.yaml > /tmp/buf-before.txt`2. **Run** `pnpm buf-bump:<service>` (or `pnpm buf-bump:main`).3. **Canary — verify the bump actually changed versions.** Run `git diff pnpm-workspace.yaml`. If it is empty, the pins were already current OR the bump silently no-op'd (bad auth, wrong service). Stop and report — do not proceed as if it succeeded.4. **Install.** The bump script runs `pnpm install` itself; it is what actually fetches the prebuilt packages. Canary: `git diff --stat pnpm-lock.yaml` must show the new `@bufteam/*` versions. If the lockfile is unchanged, the install pulled nothing — stop and report; do not proceed as if it succeeded. (If the script's install step failed, run `pnpm install` yourself and re-check.)5. **Type-check** with `pnpm lint:tsc` to surface breakage.6. **Fix the breakage**, distinguishing mechanical from non-mechanical: - **Mechanical** (renamed field, widened type, new optional field): update the `rpcToForm*` / `formToRpc*` converters, server actions referencing the RPC, and direct proto usage in components. Use `*Required` types from `hadrian_protoc-gen-es-required` for form validation. - **Non-mechanical** (a field was **removed**, an enum value dropped, semantics changed): **escalate to the user.** A removed field is a backend contract change — surface it; do not silently insert a null-check or default that hides lost data.7. **Test** with `pnpm test`.8. **Report** the version delta (from step 3), what you fixed mechanically, and any non-mechanical changes you escalated.## Gotchas- Do not run `pnpm build:rpc` as part of a bump. Its turbo filter (`turbo build --filter *-proto`) matches zero workspace packages — the proto packages moved to prebuilt BSR npm packages (Nov 2024), so there is nothing to build locally.

Frequently asked questions