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, GetInferenceRoute

Steps

1. Find the capability in the SDK

Read the vendored 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(), Workspaces(), Providers(), Exec(), Inference(), Policy(), Services(), ...)
• 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 public SDK is actually missing what you need; if so, document the gap before adding any escape hatch

2. Update models / request parsing

If the gateway response needs JSON shaping, add or extend DTO converters in backend/internal/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.

3. REST handler

Add a handler in backend/internal/api/. Use package-level helpers from respond.go:

// backend/internal/api/workspaces_handler.go
func (app *App) CreateWorkspace(w http.ResponseWriter, r *http.Request) {
    var body CreateWorkspaceRequest
    if !decodeBody(w, r, &body) {
        return
    }
    if !validDNS1123(body.Name) {
        writeError(w, http.StatusBadRequest, "invalid_name", "name must be a valid DNS-1123 label")
        return
    }
    workspace, err := app.sdk.Workspaces().Create(r.Context(), body.Name, body.Labels)
    if err != nil {
        writeSDKError(w, err)
        return
    }
    writeJSON(w, http.StatusCreated, models.FromSDKWorkspace(workspace))
}