Menu
Guides strategic analysis of agent runtime dependency upgrades โ changelog categorization, codebase impact assessment, and feature adoption decisions. Use when upgrading SDK-level dependencies that sit behind an abstraction boundary.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Develop, validate, and publish DorkOS marketplace packages โ agents, plugins, skill-packs, and adapters. Use when creating marketplace items, working in the dork-labs/marketplace repo, or helping users build packages for the personal marketplace.
First-touch triage for incoming GitHub issues on dork-labs/dorkos. Use when DorkBot is asked to triage the issue queue: label each new issue by type and runtime, find likely duplicates, and ask the reporter for missing reproduction steps. Read-and-suggest by default; only comments or edits labels when explicitly allowed to act.
Regenerate DorkOS product screenshots and video loops from the real UI, and manage the shot registry, human overrides, and version archives that feed the marketing site, docs, and changelogs. Use when marketing/docs media is stale after UI changes, a new feature or docs page needs a money shot, a person wants to override an automated capture, or a release calls for a fresh capture or archive โ anything under apps/site/public/product/ or the apps/e2e/capture pipeline.
Skill whose frontmatter name does not match its directory name.
Implements the Calm Tech design system using Tailwind CSS v4 and Shadcn UI. Use when writing styles, building components, or theming. For design decisions, see designing-frontend.
Writes human-friendly changelog entries and release notes. Use when populating changelog, preparing releases, or reviewing release notes quality.
| name | upgrading-runtime-dependencies |
| description | Guides strategic analysis of agent runtime dependency upgrades โ changelog categorization, codebase impact assessment, and feature adoption decisions. Use when upgrading SDK-level dependencies that sit behind an abstraction boundary. |
| user-invocable | false |
This skill teaches the judgment calls needed when upgrading dependencies that power agent runtimes. Unlike routine dependency bumps, runtime SDK upgrades require understanding what new capabilities to adopt, not just what breaks.
Runtime dependencies sit behind abstraction boundaries (e.g., the AgentRuntime interface). Changes to the SDK affect a confined set of files, but the implications ripple outward through the features those files enable. Your job is to trace both the direct code impact and the strategic value.
Changelog entries are often vague. Use these heuristics:
| Entry Pattern | Likely Category | Why |
|---|---|---|
| "refactored X internals" | internal | Unless X is a public API you call |
| "improved X performance" | performance | But check if our usage pattern benefits |
| "updated X types" | Could be breaking | Type changes can break compilation |
| "X now accepts Y" | feature | Additive API change |
| "X no longer does Y" | breaking | Subtractive behavior change |
| "deprecated X in favor of Y" | deprecated | Even if X still works |
| "fixed X when Y" | fix | Check if we hit condition Y |
Not all versions deserve equal attention:
When multiple sources exist (GitHub releases, CHANGELOG.md, npm metadata):
time field shows exact publish datesFor the Claude Agent SDK specifically, the AgentRuntime interface is the abstraction boundary (enforced by ADR-0089 via ESLint). Know the mapping:
| SDK Surface | DorkOS Module | Impact Scope |
|---|---|---|
query() function signature | message-sender.ts | Core messaging pipeline |
SDKMessage types | sdk-event-mapper.ts | Event streaming |
Options type | message-sender.ts, plugin-activation.ts | Session configuration |
Session management (renameSession, forkSession) | claude-code-runtime.ts | Session lifecycle |
| MCP server config types | context-builder.ts | Tool/context injection |
| Permission modes | message-sender.ts | Security boundary (ADR-0240) |
Plugin system (options.plugins) | plugin-activation.ts | Marketplace integration (ADR-0239) |
| Error types/categories | sdk-event-mapper.ts | Error handling (ADR-0143) |
| CLI path resolution | sdk-utils.ts | Dependency checking |
| Model/subagent metadata | runtime-cache.ts | Cached metadata |
| Slash command discovery | command-registry.ts | Command system |
Ask these questions for each new SDK feature:
Be honest about effort. A "trivial" SDK API change can have non-trivial implications:
| Change Type | Seems Like | Actually Is |
|---|---|---|
New optional parameter on query() | Trivial | Trivial โ just pass it through |
New required parameter on query() | Moderate | Could be significant if it needs user-facing config |
New event type in SDKMessage | Trivial | Moderate โ needs mapper entry, may need UI support |
| Changed error category taxonomy | Moderate | Significant โ touches error handling, may need UI updates |
New Options field | Trivial | Depends โ if it needs per-session config, touches session store |
| Removed/renamed export | Breaking | Usually moderate โ confined by ESLint boundary |
Before recommending an adoption approach, verify it doesn't violate existing ADRs:
@anthropic-ai/claude-agent-sdk โ services/runtimes/claude-code/, @openai/codex-sdk โ services/runtimes/codex/, @opencode-ai/sdk โ services/runtimes/opencode/. If a new feature needs to surface data outside that boundary, it must go through the AgentRuntime interface.options.plugins. If the SDK changes how plugins work, the activation pipeline needs updating.Create a separate spec (not included in the upgrade spec) when a feature:
Include in the main upgrade spec when a change is:
A good upgrade spec:
The Claude Agent SDK table above is the worked example; the same discipline applies to all three runtime SDKs, each with its own upgrade personality:
| SDK | Adapter | What makes its upgrades different |
|---|---|---|
@anthropic-ai/claude-agent-sdk | runtimes/claude-code | Richest surface (see table above); native-binary packaging changed at 0.2.113, so path resolution is version-sensitive |
@openai/codex-sdk | runtimes/codex | Versions track the Codex CLI train; active alpha dist-tag; event-mapper never exhaustiveness checks are the intended tripwire for new ThreadEvent/ThreadItem members (ADR-0309) |
@opencode-ai/sdk | runtimes/opencode | Client-only SDK that version-couples with the separately-shipped opencode-ai sidecar binary (ADR-0308); server-side release notes can matter more than client type changes; ignore snapshot tags |
Two gates are universal regardless of SDK:
runtimeConformance (@dorkos/test-utils) after a bump: run the adapter's suite (pnpm vitest run apps/server/src/services/runtimes/<runtime>) before calling any upgrade validated.contributing/adding-a-runtime.md (section: Bumping a pinned SDK) is the canonical validation sequence; the config's per-package upgrade_notes point to it and add package-specific judgment.The same principles generalize to any future runtime dependency behind an abstraction boundary:
The .claude/config/runtime-deps.json file maps each runtime dependency to its boundary, codebase root, changelog sources, SDK surface map, related ADRs, and upgrade notes. Consult it before starting analysis, and keep it true when the integration surface changes.