{"id":54732,"plugin_id":"plugin_asdk_app_6a8061659144819197910ef2762afbc0","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-25T12:04:51.366Z","digest":"15d38ab44f2fe25a3f38e560fa0e3510084af9e0157b02a2505bb2bcc978ccfc","against":null,"payload":{"description":"Gateway operating doctrine. Typed-tool selection, inspection-first operation, durable jobs, privilege and secret handoffs, and the execute_command escape hatch.","included_files":[],"name":"operating-doctrine","skill_md_contents":"---\nname: operating-doctrine\ndescription: \"Gateway operating doctrine. Typed-tool selection, inspection-first operation, durable jobs, privilege and secret handoffs, and the execute_command escape hatch.\"\n---\n\n\n\n# Gateway operating doctrine\n\n## Choose the safest expressive operation\n\n1. Prefer a first-class typed Gateway tool when it cleanly expresses the requested operation.\n2. Inspect and discover first, then use canonical server IDs, exact paths, exact units, exact containers, and explicit overwrite behavior.\n3. Use dry-run and expected-state controls when the selected tool provides them.\n4. Treat a returned job ID as durable work. Use get_job or wait_for_job until the required terminal state instead of assuming a short MCP wait completed the job.\n5. Use execute_command for application-specific work, genuinely novel compositions, or a capability that Gateway does not yet model. It is an intentional escape hatch and must remain available.\n6. If the same shell-composed workflow succeeds repeatedly, treat it as evidence for a future typed operation; do not imply that an unsupported typed tool already exists.\n\n## Privilege\n\nNo tool accepts a sudo password. Privileged work uses privilege sudo or auto, or a typed tool that runs with sudo. When such a call fails with SUDO_PASSWORD_REQUIRED or SUDO_AUTH_FAILED, or a job carries nextAction request_sudo_access, call request_sudo_access for that server. If its state is action_required, ask the user how they would like to grant sudo (just this once, which covers a single privileged job; for a while, 15 minutes to an hour, which suits a task needing several privileged calls; or always: Gateway keeps the sudo password, or a passwordless sudo rule is installed on the server) and send them its setupUrl to choose and enter the password in Gateway. Never ask for a password in chat. Wait for the user to confirm, then retry the original call; the failure happens before the command runs, so retrying is safe. already_root needs no action; unsupported (Windows servers) means use privilege none. To set up a new server, send the user the add_server setupUrl to enter the login password in Gateway; sudo_setup chooses whether that password also grants sudo.\n\n## Secrets\n\nGateway's job is to let the user use an agent without handing it secrets: secret values never pass through the conversation or tool arguments. When work needs a token, API key, registry credential, or secret file, call request_stored_value with a short name (for example github-token) and the purpose. If exists is false, send the user its setupUrl, wait for them to confirm the secret is saved, then pass only its name: stdin_from or env_from on execute_command and typed tools, registry_credential_from for registry access, and content_from on write_secret_file. A call that names a missing, used, or expired secret fails with nextAction request_stored_value before any job is created; follow the same handoff and retry. One-time secrets are consumed by the first job that uses them.\n\n## File movement\n\nUse copy_between_servers for one exact regular-file direct host-to-host copy up to 268,435,456,000 bytes (250 GiB). Recursive directory copy is not supported by v2. Gateway coordinates, authorizes, supervises, and audits the operation. Between directly reachable servers the payload flows only between the source and destination hosts; it never passes through an executor, the application server, artifact storage, or R2, and the copy fails when no direct host path is available rather than falling back to a relay. When either server connects through a Gateway overlay network, Gateway stages the file through regional R2 instead, capped at 5,363,466,240 bytes (4.995 GiB), and deletes it after the transfer. The operation uses short-lived transfer-scoped authorization. sync_between_servers retains staged/R2 transit by default and its existing explicit transport choices. If an artifact is publicly obtainable, prefer fetching it from its authoritative public source at the destination. Reject host-to-host requests above 268,435,456,000 bytes.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}