New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Upgrade Claude Adapter

by PostHog in PostHog/code

Sync this fork of @anthropic-ai/claude-agent-acp (packages/agent/src/adapters/claude) with a newer upstream release: bump the claude-agent-sdk / @agentclientprotocol/sdk, port upstream bug fixes and…

OfficialMITAuto-check passedDevelopment

Install Upgrade Claude Adapter

skills CLI
$ npx skills add PostHog/code --skill upgrade-claude-adapter -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install PostHog/code upgrade-claude-adapter --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/PostHog/code.git skills-src && mkdir -p .claude/skills && cp -r skills-src/packages/agent/src/adapters/claude .claude/skills/upgrade-claude-adapter && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
upgrade-claude-adapter
GitHub stars
179
Token cost
~2.5k tokens
SKILL.md length
1,097 words
Files
59
Skills in repo
10
Repo updated
First seen
Licence
MIT

At a glance

Sync this fork of @anthropic-ai/claude-agent-acp (packages/agent/src/adapters/claude) with a newer upstream release: bump the claude-agent-sdk / @agentclientprotocol/sdk, port upstream bug fixes and…

  • Works in 8 steps: Orient (read, don't write) → Triage every commit → Map upstream → fork → …
  • Asked to upgrade/sync the claude adapter
  • SKILL.md covers Inputs you need before starting, Process and Fork facts worth remembering
  • Runs TypeScript scripts from its folder; calls pnpm, git and npm

What it does

Upgrade Claude Adapter is an agent skill from PostHog/code, published by the product's own GitHub organization. Sync this fork of @anthropic-ai/claude-agent-acp (packages/agent/src/adapters/claude) with a newer upstream release: bump the claude-agent-sdk / @agentclientprotocol/sdk, port upstream bug fixes and new SDK message handling, preserve the fork's divergences, verify, and update UPSTREAM.md. Use when asked to "upgrade/sync the claude adapter", "bump the agent SDK", or "port upstream claude-agent-acp changes".

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 59 other files (for example `UPSTREAM.md`, `claude-agent.finish.test.ts` and `claude-agent.permission-mode.test.ts`).

It sits in Development, covering Debugging and Building AI agents. It works with PostHog, Claude Agent SDK and Git. The repository describes itself as: The era of self-driving development is here. The licence is MIT.

When your agent uses it

  • Asked to upgrade/sync the claude adapter
  • Bump the agent SDK
  • Port upstream claude-agent-acp changes

Example prompts

  • “s divergences, verify, and update UPSTREAM.md. Use when asked to”
  • “bump the agent SDK”
  • “port upstream claude-agent-acp changes”
  • “/upgrade-claude-adapter”

Requirements

  • Node.js

Workflow steps

8 steps, taken from the step headings in SKILL.md.

  1. Orient (read, don't write)
  2. Triage every commit
  3. Map upstream → fork
  4. Bump dependencies
  5. Find the breaking-change surface
  6. Port in phases — bug fixes first, then features
  7. Verify (all of it)
  8. Update UPSTREAM.md (do this last)

What it can do on your machine

Read from SKILL.md and the folder at commit a4c32df. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships script files (TypeScript, from the files we listed), which the agent can run.

    Shell commands in SKILL.md call:

    • pnpm
    • git
    • npm
    • rg
    • npx
    • node

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use pnpm, git, npm and npx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Upgrade Claude Adapter loads about 2.5k tokens when it runs. Until then it costs about 108 tokens; SKILL.md has 1,097 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~108
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from PostHog/code at commit a4c32df, republished under its MIT licence (© PostHog). 1,097 words, ~2,474 tokens.

Download SKILL.mdSave it as .claude/skills/upgrade-claude-adapter/SKILL.md (or your agent's skills folder). This skill also uses 58 other files; get the full folder from GitHub.
name
upgrade-claude-adapter
description
Sync this fork of @anthropic-ai/claude-agent-acp (packages/agent/src/adapters/claude) with a newer upstream release: bump the claude-agent-sdk / @agentclientprotocol/sdk, port upstream bug fixes and new SDK message handling, preserve the fork's divergences, verify, and update UPSTREAM.md. Use when asked to "upgrade/sync the claude adapter", "bump the agent SDK", or "port upstream claude-agent-acp changes".

Upgrade the Claude ACP adapter (upstream sync)

This is a runbook for syncing our fork of @anthropic-ai/claude-agent-acp (the upstream Zed/agentclientprotocol ACP agent) that lives in packages/agent/src/adapters/claude/ with a newer upstream release. The fork is heavily diverged. The job is to port the valuable upstream changes (SDK bumps, bug fixes, new SDK-message handling) while preserving every intentional divergence — not to make the fork identical to upstream.

UPSTREAM.md (this directory) is the source of truth for the fork point, last-synced version/commit, the file mapping, the PostHog-only code, and the intentional divergences. Read it first, update it last.

This file is a runbook, not an auto-registered slash command. Invoke it by telling Claude to "follow the upgrade skill in the claude adapter dir." Move it to .claude/skills/<name>/SKILL.md if you ever want it runnable as /<name>.

Inputs you need before starting

  1. Upstream source checkout — a local git clone of github.com/agentclientprotocol/claude-agent-acp. You need its history to diff. If the user hasn't given the path, ask for it (it's usually somewhere like ~/Cloud/claude-agent-acp). Do not guess.
  2. This repo — the fork under packages/agent/.

Process

0. Orient (read, don't write)
  • Read UPSTREAM.md. Note Last sync (commit + version), the pinned SDK versions, the File Mapping, PostHog-Only Code (Do Not Sync), and Intentional Divergences.
  • In the upstream checkout, list the change set since the last sync and skim the changelog:
    • git -C <upstream> log --oneline <last-sync-sha>..HEAD
    • git -C <upstream> show <upstream>/CHANGELOG.md:CHANGELOG.md (or just read CHANGELOG.md)
  • Confirm the new target version + HEAD sha and the target SDK versions from the upstream package.json.
1. Triage every commit

Bucket each commit since the last sync:

  • Port — bug fixes and new feature / SDK-message handling that are not in the PostHog-only list and don't fight a divergence.
  • Dep bump — record the target SDK versions; the diff tells you if code changes ride along.
  • Skip — chore(main): release …, actions/* CI bumps, pure dependabot dev-dep bumps, and anything matching the PostHog-only / divergence lists.

Read intent from source diffs (exclude tests + JSON first):

git -C <upstream> show <sha> -- src/ ':(exclude)src/tests/*' ':(exclude)*.json'

A dependabot SDK-bump commit often also carries real code (new message handling). Don't assume "deps" == "no code".

2. Map upstream → fork

Upstream is one large src/acp-agent.ts; our fork is split. Use the File Mapping in UPSTREAM.md. Rough guide:

UpstreamFork
acp-agent.ts prompt loop, lifecycle, cancelclaude-agent.ts
inline message/stream/result/system conversionconversion/sdk-to-acp.ts
inline prompt→SDK conversionconversion/acp-to-sdk.ts
tools.ts (tool_use→ACP, PostToolUse hook)conversion/tool-use-to-acp.ts, hooks.ts
model alias resolutionsession/models.ts, session/model-config.ts
options / system promptsession/options.ts
permissionspermissions/*

For each upstream change, rg the fork for the touched symbol first — the fork usually already has a diverged version of it, so you're editing, not adding.

3. Bump dependencies

In packages/agent/package.json, set @anthropic-ai/claude-agent-sdk, @agentclientprotocol/sdk, and @anthropic-ai/sdk to the upstream package.json versions, then pnpm install from the repo root. (packages/shared pins its own older @agentclientprotocol/sdk; leave it unless a cross-package type error forces a bump.)

4. Find the breaking-change surface

Run pnpm --filter agent typecheck. The errors are your ACP/SDK breaking-change list. Gotchas seen in past syncs:

  • The ACP SDK ships name-mangled generated types. dist/schema/*.gen.d.ts shows enum literals as n (e.g. StopReason = "…" | "n" | "cancelled"). Don't trust grep there. Read the hand-written dist/acp.d.ts, or download the exact target to inspect cleanly:
    cd /tmp && npm pack @agentclientprotocol/sdk@<ver> && tar xzf *.tgz
rg -n "type StopReason|deleteSession|SessionModelState" package/dist/schema/types.gen.d.ts package/dist/acp.d.ts
  • node -e "require('<pkg>/package.json')" may fail on the SDKs (exports map blocks the subpath). Read node_modules/<pkg>/package.json directly for the installed version.
  • An ACP SDK bump can break code outside the claude adapter. The whole packages/agent package must typecheck — expect to also fix adapters/codex/* and server/agent-server.ts. Keep those fixes minimal and behavior-preserving (e.g. when ACP removed the models response field, the codex adapter derived the model id from configOptions instead).
Show full SKILL.md (512 more words)Show less
5. Port in phases — bug fixes first, then features

For each ported change:

  • Preserve divergences (see UPSTREAM.md → Intentional Divergences + PostHog-only). The big ones: single-session this.session (not this.sessions[id]); interruptReason on cancel; gateway models via fetchGatewayModels (not initializationResult.models); _posthog/* ext notifications; the "Unsupported slash command" gate on knownSlashCommands; SYSTEM_REMINDER stripping; plan / questions / MCP-metadata machinery.
  • New SDK system subtypes are safe by default. handleSystemMessage ends in default: break, and the prompt-loop top-level switch (message.type) only unreachable()s unknown top-level types. So a new subtype won't crash the loop — port real handling only where there's user value (e.g. permission_denied → failed tool_call, tool_progress → in_progress, commands_changed → available_commands_update, mirror_error → log).
  • When upstream reads new fields (stop_details, getContextUsage, thinking), confirm the installed SDK .d.ts actually has them before porting. Skip ports the fork can't use (e.g. the fork doesn't read MAX_THINKING_TOKENS, so upstream's resolveThinkingConfig was N/A).
  • Typecheck after each logical group, not just at the end.
6. Verify (all of it)
pnpm --filter agent typecheck
pnpm --filter agent build
npx biome check --write <changed files>      # biome is the formatter/linter, not prettier/eslint
pnpm typecheck                                # whole repo: confirms apps/code compiles vs the new ACP SDK
pnpm --filter agent test
pnpm --filter code test
  • The apps/code renderer unit tests analytics.test.ts and panelLayoutStore.test.ts are flaky — they sometimes throw in getElectronTRPC / electron-trpc ipcLink depending on test ordering. If they fail, re-run; a clean rerun (or git stash + run on the clean tree) passing confirms it's the known flake, not your change.
7. Update UPSTREAM.md (do this last)
  • Bump Last sync (version + HEAD sha + date) and the pinned SDK versions.
  • Add ## Changes Ported in v<X> Sync (one bullet per change, with PR # and short sha) and ## Skipped in v<X> Sync (with the reason for each skip).
  • If a port made a former divergence match upstream, move it out of the Intentional Divergences table.

Fork facts worth remembering

  • Single session. The agent owns one this.session (from BaseAcpAgent), not a sessions map. Upstream's per-session refactors usually collapse to "just use this.session".
  • Prompt loop is a persistent consumer (since the v0.54.1 sync, upstream #780): prompt() enqueues a Turn deferred; runConsumer drains the query stream for the session's life, settles turns at their terminal result, and captures query + session.queryGeneration so the fork-only refreshSession() can retire it (bump generation → abort wake-up → end input). Steer mode, interruptReason, per-turn broadcast-at-activation and the unsupported-slash-command gate all live inside it — port upstream prompt-loop changes into the consumer, not a per-prompt loop.
  • ACP connection classes are the deprecated ones on purpose. The fork stays on AgentSideConnection/ClientSideConnection (still shipped in ACP 1.x) because they carry the extMethod/extNotification surface _posthog/* uses; permission requests reach the client via the class's generic request(..., { cancellationSignal }). Don't port the agent() builder without a plan for the extension surface.
  • Renderer uses config options only. Model/mode/effort selection is SessionConfigOption end to end; the renderer never reads the legacy models response field or calls unstable_setSessionModel. That's why upstream's ACP-0.24/0.25 model-state removals are safe to follow.
  • toolUseCache is never cleared in the fork (created once in the constructor), so long sessions accumulate — keep the prune-at-tool_result behavior, and make any PostToolUse hook close over the data it needs rather than re-reading the cache.
  • Conversion is split out. claude-agent.ts calls handleSystemMessage / handleStreamEvent / handleResultMessage / handleUserAssistantMessage from conversion/sdk-to-acp.ts. Upstream inlines all of this in acp-agent.ts.
  • Don't commit or push unless the user explicitly asks. Leave the work on the current branch.

© PostHog, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 58 other files in packages/agent/src/adapters/claude of PostHog/code.

  • SKILL.md
  • UPSTREAM.md
  • claude-agent.finish.test.ts
  • claude-agent.permission-mode.test.ts
  • claude-agent.refresh.test.ts
  • claude-agent.resume-model.test.ts
  • claude-agent.slash-command.test.ts
  • claude-agent.streamed-text.test.ts
  • claude-agent.task-notification.test.ts
  • claude-agent.ts
  • context-breakdown.test.ts
  • context-breakdown.ts
  • conversion/acp-to-sdk.test.ts
  • conversion/acp-to-sdk.ts
  • conversion/sdk-to-acp.test.ts
  • conversion/sdk-to-acp.ts
  • conversion/task-state.test.ts
  • conversion/task-state.ts
  • conversion/tool-use-to-acp.ts
  • git-command.ts
  • … and 39 more

Open the folder on GitHubat commit a4c32df

Used in 2 other repositories

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders. This page covers the copy in PostHog/code, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Upgrade Claude Adapter next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Upgrade Claude Adapter compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Upgrade Claude Adapter this skillPostHog/code179—~2.5kAutomated safety check: PassMIT
Agent SDK Version Bumppreset-io/agor1.4k—~1.4kAutomated safety check: PassCustom licence
Debugging and Error Recoveryaddyosmani/agent-skills103k1 repos~2.6kAutomated safety check: PassMIT
Git History Bug Auditben-manes/caffeine18k—~3.3kAutomated safety check: PassApache-2.0
Leon Coding Agentleon-ai/leon18k—~1.1kAutomated safety check: PassMIT
Adk Setupgoogle/adk-python22k—~993Automated safety check: NotesApache-2.0

Similar skills

  • Agent SDK Version Bump

    preset-io/agor

    Upgrades a pinned agent SDK in the agor project, such as the Claude, Codex or Gemini CLI one, and plans the release that carries it to packaged installs.

    1.4k GitHub stars~1.4k tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Debugging and Error Recovery

    addyosmani/agent-skills

    Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.

    103k GitHub starsUsed in 1 repo~2.6k tokens
    DevelopmentAuto-check passed

  • Git History Bug Audit

    ben-manes/caffeine

    Audits a module by walking its git history commit by commit, tracking unresolved issues forward, and reporting the ones that survive to HEAD as findings.

    18k GitHub stars~3.3k tokensUpdated today
    DevelopmentAuto-check passed

  • Leon Coding Agent

    leon-ai/leon

    Has Leon's agent investigate, change and verify code in a repository with its file, search and shell tools, staying inside the scope the owner authorized.

    18k GitHub stars~1.1k tokensUpdated today
    DevelopmentAuto-check passed

  • Adk Setup

    google/adk-python

    Official

    Sets up a local ADK Python development environment in a git clone of the open-source adk-python repository: a uv virtual environment, all dependency extras, pre-commit hooks, and a first unit-test…

    22k GitHub stars~993 tokensUpdated today
    DevelopmentAuto-check: notes

  • Debug Tui

    trasta298/keifu

    Drive and debug the real keifu TUI autonomously via its remote-control debug server (--debug-listen) — launch headlessly, inject keys/mouse, dump the rendered screen as text, and inspect app state.

    810 GitHub stars~1.3k tokensUpdated 2 mo ago
    DevelopmentAuto-check passed

More from PostHog/code

All 10 skills in this repo

  • Canvas Templates

    PostHog/code

    Official

    How PostHog "canvas" dashboards work end-to-end — the two rendering tiers (json-render vs freeform React-in-iframe), the agent system prompts that steer each, and the RIGHT way to fetch PostHog data…

    179 GitHub stars~2.2k tokensUpdated 2 mo ago
    Auto-check passed

  • Dynamic Workflows

    PostHog/code

    Official

    How to write JavaScript workflow scripts for the workflow tool - fanning work out across many isolated subagents with agent(), parallel(), and pipeline(), then synthesizing one result.

    179 GitHub stars~2.3k tokensUpdated 2 mo ago
    Auto-check passed

  • MCP Servers

    PostHog/code

    Official

    Install, configure, authenticate, and troubleshoot MCP (Model Context Protocol) servers for this agent.

    179 GitHub stars~1.9k tokensUpdated 2 mo ago
    Auto-check passed

  • Merging PRs

    PostHog/code

    Official

    Merge a PR into main through the Trunk merge queue and babysit it until it lands.

    179 GitHub stars~1.3k tokensUpdated 2 mo ago
    Auto-check passed

  • Onboarding Videos

    PostHog/code

    Official

    Add, replace, and optimize the looping demo videos in the onboarding "welcome" bento grid (packages/ui/src/features/onboarding).

    179 GitHub stars~1.7k tokensUpdated 2 mo ago
    Auto-check passed

  • Quill Code

    PostHog/code

    Official

    Edit the @posthog/quill design system locally and consume the change in this repo (posthog-code) before it is published to npm.

    179 GitHub stars~1.1k tokensUpdated 2 mo ago
    Auto-check passed

Works with

Categories

Questions about Upgrade Claude Adapter

What does Upgrade Claude Adapter do?

Sync this fork of @anthropic-ai/claude-agent-acp (packages/agent/src/adapters/claude) with a newer upstream release: bump the claude-agent-sdk / @agentclientprotocol/sdk, port upstream bug fixes and…. Upgrade Claude Adapter is an agent skill from PostHog/code, published by the product's own GitHub organization.md.

When should I use Upgrade Claude Adapter?

Upgrade Claude Adapter fits situations like: asked to upgrade/sync the claude adapter; bump the agent SDK; port upstream claude-agent-acp changes.

How do I install Upgrade Claude Adapter in Claude Code?

Run `npx skills add PostHog/code --skill upgrade-claude-adapter -a claude-code`. Or copy the skill folder (packages/agent/src/adapters/claude in PostHog/code) into .claude/skills/upgrade-claude-adapter in your project. Claude Code loads it when a task matches its description.

How do I install Upgrade Claude Adapter in Codex?

Run `npx skills add PostHog/code --skill upgrade-claude-adapter -a codex`. Or copy the skill folder (packages/agent/src/adapters/claude in PostHog/code) into .agents/skills/upgrade-claude-adapter in your project. Codex loads it when a task matches its description.

Can I use Upgrade Claude Adapter in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add PostHog/code --skill upgrade-claude-adapter -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/upgrade-claude-adapter, .gemini/skills/upgrade-claude-adapter, .github/skills/upgrade-claude-adapter and .opencode/skills/upgrade-claude-adapter in your project.

What does Upgrade Claude Adapter need to run?

Going by SKILL.md and its folder, Upgrade Claude Adapter needs TypeScript for the scripts in its folder and the command-line tools its instructions call (pnpm, git, npm, rg, npx and node). Our summary lists: Node.js.

Does Upgrade Claude Adapter access the network?

SKILL.md contains no URLs. Its commands use git, npm and npx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Upgrade Claude Adapter safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Upgrade Claude Adapter use?

Upgrade Claude Adapter is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Upgrade Claude Adapter use?

About 2.5k tokens (SKILL.md is roughly 9.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Upgrade Claude Adapter?

Skills that share tags, products or a category with Upgrade Claude Adapter: Agent SDK Version Bump (preset-io/agor, 1.4k stars), Debugging and Error Recovery (addyosmani/agent-skills, 103k stars), Git History Bug Audit (ben-manes/caffeine, 18k stars) and Leon Coding Agent (leon-ai/leon, 18k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Upgrade Claude Adapter?

PostHog (a GitHub organization, an official publisher) maintains it in PostHog/code, which has 179 GitHub stars. The repository holds 10 skills in this directory. The repository was last updated on August 5, 2026.

Source: PostHog/code on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.