openshell-dashboard: Skill for Claude Code

Add API Capability

Wire a new OpenShell gateway capability through the full stack: SDK surface check → models/request shape → REST handler → route → frontend API function → hook → types.

Arguments

$ARGUMENTS — SDK method or gateway capability name. Example: CreateWorkspace, ListProviders, GetSandboxTemplate

Steps

1. Find the capability in the SDK

Read the SDK surface described in .claude/rules/openshell-api.md. Start with openshell/v1/ and types/ in the pinned module version. Note:

• Which SDK sub-client owns the capability (Sandboxes(), SandboxTemplates(), Workspaces(), Providers(), Exec(), Config(), Policy(), Services(), Health())
• Workspace scoping
• Whether the API addresses a sandbox by name or UUID
• Secret-bearing fields or write-only fields that must not be sent back to the frontend
• Whether the SDK is actually missing what you need; if so, name the gap before adding a direct gRPC call (ADR 0003, decision 4)

If the capability exists upstream but not in the pinned SDK, do not run go get ...@latest to reach it. The SDK moves with the gateway, to the commit of an upstream release tag, and the Follow upstream workflow makes that move on the next branch (ADR 0005, decision 7; see "SDK updates" in .claude/rules/bff-go.md). If the capability is in the upcoming release, the endpoint is work for next: branch from it and open the pull request into it. Also check that the gateway this branch pins (node scripts/gateway-range.mjs prints its release) actually serves the RPC: a gateway answers gRPC UNIMPLEMENTED for an RPC it does not have.

2. Update models / request parsing

If the gateway response needs JSON shaping, add or extend DTO converters in backend/pkg/models/. Never serialize SDK objects directly.

func FromSDKWorkspace(ws *openshell.Workspace) Workspace { ... }

For request bodies:

• Simple request structs live in the handler file.
• Complex SDK-building logic lives in models/sdk_converters.go or models/builders.go.
• Policy payloads must keep using ParseSDKPolicy / marshalSDKPolicy so the frontend's protojson contract stays intact.