skills.rest
PostHog
PostHogOFFICIAL
Explore all skills by this author →
Website𝕏@PostHogGitHub

upgrade-claude-adapter

Syncs a forked Claude ACP adapter with upstream releases while preserving intentional divergences.

713|118|Updated Aug 11, 2020
Search Tags:#typeScript#claude-agent-sdk#dependency upgrade#upstream sync#fork maintenance#acp adapter#commit triage
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill upgrade-claude-adapter
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: upgrade-claude-adapter
Source: https://github.com/PostHog/posthog-foss/tree/main/products/desktop/packages/agent/src/adapters/claude
Command: npx skills add https://github.com/PostHog/posthog-foss --skill upgrade-claude-adapter

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Keeping a heavily diverged fork of @anthropic-ai/claude-agent-acp current with upstream releases is error-prone: SDK bumps carry hidden breaking changes, upstream commits mix valuable fixes with irrelevant churn, and PostHog-specific behavior can be accidentally overwritten. This runbook provides a repeatable process for triaging upstream commits, porting only the valuable changes, and preserving every intentional fork divergence.

Core Features & Use Cases

  • Commit triage and mapping: Buckets each upstream commit since the last sync into port, dependency-bump, or skip, and maps upstream files (e.g. acp-agent.ts) to the fork's split modules via the UPSTREAM.md file mapping.
  • Dependency and breaking-change handling: Bumps @anthropic-ai/claude-agent-sdk, @agentclientprotocol/sdk, and @anthropic-ai/sdk, then uses typecheck errors across the whole packages/agent workspace to surface the breaking-change surface, including name-mangled ACP generated types.
  • Divergence preservation and verification: Ports bug fixes before features while protecting PostHog-only code (single-session model, gateway models, _posthog/* extensions, steer mode), then runs typecheck, build, biome, and tests, and finally updates UPSTREAM.md with ported and skipped changes.
  • Use Case: When asked to "upgrade the claude adapter" or "bump the agent SDK", follow the runbook to diff the upstream checkout against the last-synced commit, port the relevant changes, verify the full repo compiles, and record the new sync state.

Quick Start

Ask the agent to follow the upgrade skill in the claude adapter directory to sync the fork with the latest upstream claude-agent-acp release, providing the path to your local upstream checkout.

Frequently Asked Questions about upgrade-claude-adapter

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I sync a forked claude-agent-acp adapter with upstream?▼

Read UPSTREAM.md for the last-synced commit and file mapping, then run git log in the upstream checkout to list changes since that commit. Triage each commit into port, dependency bump, or skip, map upstream files to the fork's split modules, and typecheck after each ported group.

How do I bump the claude-agent-sdk and ACP SDK versions?▼

Set @anthropic-ai/claude-agent-sdk, @agentclientprotocol/sdk, and @anthropic-ai/sdk in packages/agent/package.json to the versions in the upstream package.json, then run pnpm install from the repo root. Run pnpm --filter agent typecheck to reveal the breaking-change surface.

Why does the ACP SDK show wrong enum types like "n" in StopReason?▼

The ACP SDK ships name-mangled generated types in dist/schema/*.gen.d.ts, so grepping them is misleading. Read the hand-written dist/acp.d.ts instead, or npm pack the exact target version in /tmp and inspect the extracted type definitions.

Which upstream changes should not be ported to the fork?▼

Skip release commits, CI bumps, pure dev-dependency bumps, and anything in the PostHog-only or Intentional Divergences lists in UPSTREAM.md. Examples include the ACP builder-pattern migration, elicitation-based AskUserQuestion, and upstream model pipelines replaced by gateway models.

What verification steps are required after porting upstream changes?▼

Run pnpm --filter agent typecheck and build, biome check on changed files, a whole-repo pnpm typecheck, and the agent and code package test suites. The apps/code analytics and panelLayoutStore tests are known flaky and should be re-run if they fail.

Related Skills

Explore More Software Engineering Skills→
outfitter-devoutfitter-dev
2

agent-browser-upstream

Sync agent-browser fork with upstream and generate integration documentation.

Official
Advanced
fallow-rsfallow-rs
4.4k

open-draft-pr

Commits, pushes, and opens a ready pull request for local changes on GitHub.

Official
Basic
sih3rronsih3rron

git-helper

Automate git staging, commits, pushes, pulls, and pull requests.

Community
Intermediate
aaronjmarsaaronjmars
626

fork-skill-digest

Compute weekly divergence digests for aeon fork fleets from aeon.yml settings.

Community
Advanced