Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 72 additions & 70 deletions .agents/skills/devsy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,112 +10,114 @@ metadata:

# Devsy

Operate Devsy workspaces and providers on behalf of an end user. This skill is
not the contributor guide for changing Devsy itself; for source-development
tasks follow the repository's `AGENTS.md` and normal development instructions.
Operate Devsy workspaces and providers for an end user. For changes to the
Devsy source code, follow the repository's `AGENTS.md` instead.

## Choose the interface

Use the available Devsy MCP tool when it supports the requested operation.
Client tool names may have a server prefix; discover the actual tools rather
than assuming they are connected. Use the Devsy CLI for capabilities MCP does
not expose, or as fallback when MCP is unavailable and shell access exists.
If neither interface is available, report the missing prerequisite and link to
Use a Devsy MCP tool when it supports the operation. Client tool names can
have a server prefix, so discover the actual tools. Do not assume they are
connected.

Use the Devsy CLI for operations MCP does not expose, or when MCP is
unavailable and shell access exists. If neither interface is available, report
the missing prerequisite and link to
[Devsy MCP setup](https://devsy.sh/docs/developing-in-workspaces/mcp-server).
Installing this skill does not install Devsy or configure MCP.

Keep the same Devsy context, provider, and owner scope when switching interfaces.
Do not silently replace Devsy operations with direct Docker, Kubernetes, or
cloud mutations. Devsy owns workspace state; low-level provider diagnosis needs
appropriate user authority and a reason the Devsy diagnostics are insufficient.
Keep the same Devsy context, provider, and owner when you switch interfaces.
Do not replace Devsy operations with direct Docker, Kubernetes, or cloud
changes. Devsy owns workspace state. Low-level provider diagnosis needs the
user's authority and a reason that Devsy diagnostics are not enough.

## Discover and select a workspace

- When identity is uncertain, call `workspace_list` and use a returned name.
Match an explicit user name first, then source/project when unambiguous.
- Reuse an existing suitable workspace when consistent with the request.
An explicit request for another isolated workspace should get a distinct name.
- Inspect saved configuration with `workspace_status`. Its current result is
configuration, **not live running state**. When running state matters, use
`devsy workspace status <name> --result-format json` or `workspace describe`
through the CLI. Existence does not imply the container is running.
- Resolve multiple matching candidates before mutating one.
- If the identity is uncertain, call `workspace_list` and use a returned name.
Match an explicit user name first. Then match source or project, if only one
workspace fits.
- Reuse an existing workspace when it fits the request. A request for another
isolated workspace gets a distinct name.
- `workspace_status` returns saved configuration, not live running state. When
running state matters, run `devsy workspace status <name> --result-format json`
or `workspace describe` through the CLI. A workspace can exist without its
container running.
- Resolve multiple matching candidates before you change one.

## Create and resume

Before creating, list workspaces, determine the source, and consider reuse.
`workspace_create` accepts a Git URL, absolute host-local path, container image,
or canonical source returned by `workspace_list`. A local path belongs to the
host running Devsy, not necessarily the agent's remote filesystem.
Before you create a workspace, list workspaces, identify the source, and check
whether to reuse one. `workspace_create` accepts a Git URL, an absolute
host-local path, a container image, or a canonical source from
`workspace_list`. A local path refers to the host running Devsy, not
necessarily the agent's remote filesystem.

If provider selection matters, call `provider_list` and use the configured name.
Otherwise allow the context's default provider. Add a provider only when setup
is part of the user's request; do not change the global default just to select
one provider for one workspace. Creation starts the workspace. Use its returned
configuration and identity for subsequent work. Use `workspace_start` to resume
an existing workspace, after discovery where needed.
If the provider matters, call `provider_list` and use the configured name.
Otherwise, let the context's default provider apply. Add a provider only when
setup is part of the request. Do not change the global default to pick a
provider for one workspace. Creating a workspace starts it. Use the returned
configuration and identity for later work. Use `workspace_start` to resume an
existing workspace.

### Create timeout recovery

A client timeout does not prove server-side creation stopped. **Do not blindly
retry creation, switch to CLI creation, or pick a second name.** Check
A client timeout does not mean server-side creation stopped. Do not blindly
retry creation, switch to CLI creation, or pick a second name. Check
`workspace_status` for the expected name, or `workspace_list` if the name is
uncertain. A newly visible configuration does not by itself prove setup finished;
check live state and operation diagnostics when needed. Use bounded checks
appropriate to the active task. A single not-found result can race creation;
retry only after evidence establishes that the original operation failed or
ended without creating the workspace. Report an unresolved outcome instead of
creating duplicate infrastructure.
uncertain. Saved configuration does not show that setup finished, so check live
state and operation diagnostics. Use bounded checks. A single not-found result
can race with creation. Retry only after evidence shows that the original
operation failed or ended without creating the workspace. If the outcome is
unresolved, report it. Do not create duplicate infrastructure.

## Execute commands

Ensure the workspace is started. `workspace_exec.command` is an **argv array**:
Make sure the workspace is started. `workspace_exec.command` is an **argv array**:

```json
{"name":"my-workspace","command":["npm","test"]}
```

Use a shell only for shell features such as pipes, redirection, expansion, or
chaining, and only when that shell exists in the workspace:
Use a shell only for shell features, such as pipes, redirection, expansion, or
chaining. The shell must exist in the workspace:

```json
{"name":"my-workspace","command":["sh","-c","npm test && npm run lint"]}
```

Separate direct argv calls are also suitable for sequential commands. Determine
test/build commands from the project or user request; do not guess a package
manager. `workdir` is a container path and `env` maps strings to strings.
Separate direct argv calls work for sequential commands. Find test and build
commands in the project or the user's request. Do not guess the package
manager. `workdir` is a container path. `env` maps strings to strings.

Check tool errors and the optional `error` payload as well as `exit_code`,
`stdout`, and `stderr`. `timed_out` means an execution timeout, not a normal
process exit; `truncated` means captured output is incomplete; `clamped` means
the requested timeout was shortened. Do not automatically rerun a command with
side effects after timeout or incomplete output. Defaults are 5 minutes per
exec, a 30-minute maximum, 100 KiB per output stream, and 8 concurrent
create/start/exec operations per server; server flags can change these limits.
Check tool errors and the optional `error` payload, then `exit_code`, `stdout`,
and `stderr`. `timed_out` means the execution timed out. `truncated` means
captured output is incomplete. `clamped` means the requested timeout was
shortened. Do not rerun a command with side effects after a timeout or
incomplete output. Defaults: 5 minutes per exec, a 30-minute maximum, 100 KiB
per output stream, and 8 concurrent create, start, or exec operations per
server. Server flags can change these limits.

## Stop, delete, and configure providers

Stopping compute uses `workspace_stop`; deletion removes workspace resources.
Do not interpret restart, refresh, fix, or vague cleanup as deletion authority.
For deletion or reset, establish unambiguous intent and target. Explicit deletion
can proceed within that authority without repeated confirmation. Do not default
to `force=true`: forced cleanup can leave provider resources behind and, for
imported workspaces, can also enable remote deletion otherwise skipped.
`workspace_stop` stops compute. Deletion removes workspace resources. Do not
treat restart, refresh, fix, or vague cleanup as permission to delete. For
deletion or reset, confirm the intent and the target. Explicit deletion needs no
repeated confirmation. Do not default to `force=true`. Forced cleanup can leave
provider resources behind. For imported workspaces, it can also enable remote
deletion that ordinary deletion skips.

Provider deletion affects shared configuration and may be refused while
workspaces use it. Do not delete a provider to repair one workspace. Treat
`provider_use` as a default change for subsequent creates, not a per-workspace
selection. Commands executed inside a workspace can themselves be destructive;
assess their effects, not just the tool name.
Provider deletion changes shared configuration, and the provider can refuse
deletion while workspaces use it. Do not delete a provider to repair one
workspace. `provider_use` changes the default for later creates, not the
provider for one workspace. Commands run inside a workspace can be destructive.
Assess what they do, not only the tool name.

## References

Read only the reference relevant to the task:
Read only the reference that fits the task:

- [MCP tool contract](references/mcp-tools.md) — inputs, results, limits, and errors.
- [Workspace workflows](references/workspace-workflows.md) — discovery, creation, resume, execution, stop, delete, recreate/reset.
- [CLI fallback and extended capabilities](references/cli.md) — structured output, diagnostics, and CLI-only operations.
- [Provider workflows](references/providers.md) — provider selection and configuration.
- [Safety and authority](references/safety.md) — destructive actions, credentials, and repository content.
- [Troubleshooting](references/troubleshooting.md) — timeouts, partial output, and unavailable interfaces.
- [MCP tool contract](references/mcp-tools.md): inputs, results, limits, and errors.
- [Workspace workflows](references/workspace-workflows.md): discovery, creation, resume, execution, stop, delete, recreate, and reset.
- [CLI fallback and extended capabilities](references/cli.md): structured output, diagnostics, and CLI-only operations.
- [Provider workflows](references/providers.md): provider selection and configuration.
- [Safety and authority](references/safety.md): destructive actions, credentials, and repository content.
- [Troubleshooting](references/troubleshooting.md): timeouts, partial output, and unavailable interfaces.
Loading
Loading