Workspace agent instructions
Give every agent in your workspace shared context about your tools, infrastructure, and working practices.
Workspace instructions are a Markdown block that every agent in your workspace reads. Use them for context that applies across tasks and repositories: cluster endpoints, monitoring dashboards, tool commands, and where to find operational information.
Write instructions
An owner or admin can open Settings → Agent instructions, write the instructions, and save. Members can read the saved text but cannot change it. The block can contain up to 16 KiB of UTF-8 text; leading and trailing whitespace is removed, and saving an empty block clears it.
For example, after adding GKE_READONLY_TOKEN as a workspace secret:
We run the production cluster at https://gke-example.gke.goog.
Use the read-only token through its environment variable:
kubectl --server https://gke-example.gke.goog --token "$GKE_READONLY_TOKEN" get pods -n production
Our metrics dashboard is https://grafana.example.com/d/production.
Use it when investigating latency or error rates.Store credentials in Secrets, not in these instructions. Instructions are visible to workspace members and the agent. Reference secret environment-variable names instead of pasting values, and configure the secret's approved destination hosts to match the commands. Instructions do not grant access or bypass network and credential restrictions.
You do not need to list your workspace secrets here. Sinatra adds a ## Workspace secrets section that names each workspace secret with its allowed hosts and header settings. It never includes the values.
When changes take effect
Sinatra reads the saved block each time it starts an agent and adds it under ## Workspace instructions in ~/.sinatra/AGENTS.md, after Sinatra's rules. A change applies the next time Sinatra starts the agent, including a follow-up in an existing sandbox. It does not change the running agent. If the instructions cannot be loaded, the agent starts without them.
Workspace instructions cannot override Sinatra's rules, credential rules, the runtime prompt, or the task's scope. A repository's AGENTS.md and CLAUDE.md take precedence for repository-specific conventions. Keep repository setup and checks in those files, and use workspace instructions for the context shared across your workspace.