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
121 changes: 121 additions & 0 deletions .agents/skills/devsy/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
---
name: devsy
description: Operate Devsy workspaces and providers for end users. Use to discover, create, resume, stop, delete, troubleshoot, or run commands in Devsy workspaces, and configure providers. Not for developing Devsy itself. Prefer Devsy MCP tools and use the CLI for additional operations or when MCP is unavailable.
license: MPL-2.0
compatibility: Requires Devsy installed on the controlling host and access to Devsy MCP via devsy mcp serve or shell access to the devsy CLI. Workspace execution also requires a supported container runtime and a running workspace.
metadata:
author: devsy-org
product: devsy
---

# 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.

## 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
[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.

## 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.

## 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.

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.

### 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
`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.

## Execute commands

Ensure 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:

```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.

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.

## 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.

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.

## References

Read only the reference relevant to 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.
101 changes: 101 additions & 0 deletions .agents/skills/devsy/references/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# CLI fallback and extended capabilities

Use an available equivalent MCP tool first. Use CLI when MCP is unavailable or
cannot express the requested behavior. Check `devsy version` and command `--help`
if the installed version differs from this reference. Preserve the MCP server's
context/provider/owner scope when switching, using the corresponding global
flags when set. Do not silently operate in a different context.

## Fallback mappings

| MCP tool | CLI |
| --- | --- |
| `workspace_list` | `devsy workspace list --result-format json` |
| `workspace_status` | `devsy workspace describe <name> --result-format json` (also probes live state) |
| `workspace_create` | `devsy workspace up <source> --ide-launch skip` |
| `workspace_start` | `devsy workspace up <name> --ide-launch skip` (verify the name exists first) |
| `workspace_stop` | `devsy workspace stop <name>` |
| `workspace_delete` | `devsy workspace delete <name>` |
| `workspace_exec` | `devsy workspace exec <name> -- <cmd> [args...]` |
| `provider_list` | `devsy provider list --result-format json` |
| `provider_add` | `devsy provider add <source>` |
| `provider_use` | `devsy provider use <name>` |
| `provider_delete` | `devsy provider delete <name>` |

`workspace up` is create-or-resume, so a missing name can be interpreted as a
source. Never use it as a lookup. Supply `--id <name>` when intentionally naming
a new workspace and `--provider <configured-name>` when selecting its provider.
`--ide-launch skip` avoids launching the host editor/browser for automation;
respect a user request to launch an IDE instead.

Prefer JSON where supported:

```sh
devsy workspace list --result-format json
devsy workspace status my-workspace --result-format json
devsy workspace describe my-workspace --result-format json
devsy workspace events my-workspace --limit 20 --result-format json
```

CLI status returns live `state`; describe adds live state to full configuration.
Unlike these commands, MCP `workspace_status` currently returns configuration
only. Do not scrape decorative tables when JSON exists. Exec stdout/stderr are
command streams, not a JSON result object; adding `--result-format json` does
not turn them into MCP's bounded exec response or reproduce its timeout limits.

## Diagnostics

- `devsy workspace events <name> --limit 20 --result-format json`: recent
lifecycle journal, useful for pending/failed creation and start/stop operations.
- `devsy workspace logs <name>`: agent logs; unsupported for proxy providers.
Bound log collection with the host tool's timeout and focus on relevant errors.
- `devsy workspace ping <name>`: hidden diagnostic for **Devsy Pro workspaces
only**, not a general container-health probe.
- `devsy workspace troubleshoot <name>`: hidden diagnostic that prints JSON
including config/provider/workspace information and an optional `Errors`
array. Inspect partial errors even if the process exits successfully. Review
and redact sensitive output before sharing; it is not a guaranteed clean bill
of health or a downloadable bundle.

## Additional operations

Use only when requested or necessary; inspect installed `--help` for optional
flags before using them.

| Command | Purpose and constraint |
| --- | --- |
| `devsy workspace build <name-or-source>` | Build/prebuild the workspace environment; publishing behavior depends on flags/configuration. Inspect help and requested destination first. |
| `devsy workspace rename <current-name> <new-name>` | Change workspace identity; refresh discovery afterward. |
| `devsy workspace set-ide <name> <ide>` | Change the configured IDE. |
| `devsy workspace export <name>` | Hidden command exporting configuration JSON, **not a data backup**. |
| `devsy workspace import --data '<exported-json>'` | Hidden configuration import; validate intended identities/provider references first. |
| `devsy workspace task list` | Discover background tasks, such as CLI `up --detach` work. |
| `devsy workspace task get <task-id>` | Inspect a task's status. |
| `devsy workspace task logs <task-id> --follow` | Follow a detached operation; bound the host wait. |
| `devsy workspace task cancel <task-id>` | Cancel a task process; mutation requires intent. |
| `devsy workspace task rm <task-id>` | Delete finished task state; not workspace deletion. |
| `devsy workspace ssh <name>` | Interactive/SSH scenarios; prefer MCP exec or CLI exec for one-shot automation. |
| `devsy workspace ssh <name> --command 'command'` | SSH-specific non-interactive command when needed for the task. |

Recreate/reset use `workspace up <name> --recreate` / `--reset`. Recreate loses
container changes outside project paths/mounts; reset discards workspace source
changes. Verify intent and target rather than using either as routine recovery.

## Providers and errors

CLI `provider add` defaults to changing the current default. Use `--use=false`
when adding without changing that default. This installs without initializing.
Before using the new provider, run `devsy provider init <configured-name>` with
required repeatable `--option KEY=VALUE` settings; pass those options to init,
not just to the uninitialized add path. Init does not change the default. Verify
provider status and the preserved default before creating a workspace. If only
installation was requested, report the pending initialization. Obtain option
values from provider docs/metadata; do not invent them.

Preserve actual process exit status and Devsy error code/hint when available.
Distinguish a project command failure from Devsy runtime/transport failure.
Do not suppress unexpected stderr, log credentials, or automatically rerun
mutating commands after an uncertain result.

Syntax is maintained against `cmd/workspace`, `cmd/workspace/up`,
`cmd/provider`, and `cmd/root.go` in the Devsy repository.
95 changes: 95 additions & 0 deletions .agents/skills/devsy/references/mcp-tools.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Devsy MCP tool contract

The stdio server runs as `devsy mcp serve` in its configured Devsy context.
Discover the connected tools and their schemas: the installed binary may differ
from this reference. All names below are unprefixed server tool names.

Tool failures use MCP `isError` with a classified `{code, message}` payload.
Do not treat an absent result or a zero-valued `exit_code` in an error result as
success. Lifecycle and provider mutations normally return `{ok, message?}`;
create/status return workspace configuration.

## Workspace tools

| Tool | Required inputs | Optional inputs | Preconditions and next step |
| --- | --- | --- | --- |
| `workspace_list` | None | None | Discover workspaces in the server's scope; use exact returned names for subsequent operations. |
| `workspace_status` | `name` string | None | Target must exist. Returns saved workspace configuration; use for identity and create-timeout discovery, then CLI status/describe if live state matters. |
| `workspace_create` | `source` string | `name`, `provider`, `ide`, `devcontainer_path` strings | Determine source and provider; creates and starts. Use returned workspace configuration, then exec if work is requested. Check status/list after timeout before retry. |
| `workspace_start` | `name` string | `force` boolean (shared schema; ignored for start) | Existing target only; does not intentionally create a missing workspace. Resume, then execute or verify live state. |
| `workspace_stop` | `name` string | `force` boolean (shared schema; ignored for stop) | Existing target; stops compute while retaining workspace configuration/data for resume. Verify live state if needed. |
| `workspace_delete` | `name` string | `force` boolean, default false | Destructive: verify intent/target. List afterward to verify configuration removal; that alone does not prove remote cleanup after force. |
| `workspace_exec` | `name` string, `command` array of strings | `workdir` string, `env` map of strings, `id_labels` array of strings, `timeout_seconds` integer | Workspace must be running with an execution-supported runtime. Inspect errors, exit status, and partial-output flags. |

`workspace_list` returns `workspaces[]` with `name` and optional `provider`,
`ide`, `source`, `last_used` (RFC 3339 timestamp). Source is canonical and can
be passed back to create; the list does not include live running state.

`workspace_create.source` supports Git URLs (`https://`, `ssh://`,
`git@host:repo`, and canonical `git:https://...`), absolute host-local paths,
and container image references. `provider` is a configured provider name from
`provider_list`; omission uses the active context's default. `devcontainer_path`
is relative to the project. Set `ide` only when requested. Slow pulls, clones,
and post-create commands can outlast client deadlines: server-side work may
continue. Saved configuration can become visible before setup completes.

`workspace_status` currently returns `WorkspaceConfig()` without probing
container/provider state. A successful call proves configuration lookup, not
readiness. The CLI `workspace status --result-format json` probes live state;
`workspace describe --result-format json` combines configuration with live state.

Force-delete can remove local configuration when remote operations fail,
leaving provider resources behind. It also overrides the normal remote-deletion
skip for imported workspaces; force is not merely a local cleanup switch.

## Exec results and limits

Use direct argv, e.g. `["npm", "test"]`. For shell features explicitly use an
available shell, e.g. `["sh", "-c", "npm test && npm run lint"]`. A string such
as `"npm test"` is not valid `command` input. `workdir` is inside the container;
`id_labels` select the runtime container and should not be guessed.

Results contain `stdout`, `stderr`, `exit_code`, `duration_ms`, `truncated`, and
optional `timed_out`, `clamped`, `error` (`{code, message}`). Check the MCP error
indicator first. A nonzero command exit differs from a transport/runtime error.
Errors can carry useful partial streams; retain them without treating them as
complete output or success.

| Setting | Default | Effect |
| --- | --- | --- |
| `--exec-timeout-default` | `5m` | Timeout used when the request has no positive timeout. |
| `--exec-timeout-max` | `30m` | Positive request timeouts above this are clamped; result reports `clamped`. |
| `--exec-output-cap` | `102400` bytes | Each stream is capped separately; output retains the tail with a truncation marker. |
| `--max-concurrent-ops` | `8` | Shared slots for create/start/exec; excess requests wait. |

These are configurable server defaults, not guarantees for every installation.
Timeout covers execution behavior; client deadlines and waiting for a server
slot can also interrupt a call. Neither timeout nor truncated output authorizes
a blind retry of a command with side effects.

## Provider tools

| Tool | Required inputs | Optional inputs | Preconditions and next step |
| --- | --- | --- | --- |
| `provider_list` | None | None | Discover configured provider names/default/status before selecting or mutating one. |
| `provider_add` | `source` string | `name` string, `options` map of strings, `use` boolean | Setup must be in scope; obtain provider-specific options from metadata/docs. List afterward to verify addition and default. |
| `provider_delete` | `name` string | None | Unambiguous configuration-deletion intent; may be refused if workspaces still use it. Inspect dependents, then list to verify. |
| `provider_use` | `name` string | None | Target must be configured; changes default for future creates with provider omitted. Verify with list. |

`provider_list` returns `providers[]` with `name` and optional `version`,
`default`, `status`. Missing `default` means it is not marked default.
Provider status is not proof that every workspace is healthy.

`provider_add.source` accepts a registry name (e.g. `docker`, `kubernetes`),
a GitHub release URL, or a local provider configuration file path. Its options
are provider-specific strings. The current MCP adapter only forwards `--use`
when `use=true`; the CLI add default is already true. **Omitting `use` or passing
false does not reliably preserve the old default.** Inspect the default before
and after adding; if preservation is needed, use CLI `provider add --use=false`
as an operation MCP cannot currently express. That CLI path installs without
initializing; before using the provider, run `provider init <configured-name>`
with required `--option KEY=VALUE` settings and verify provider status/default.
Initialization through CLI does not change the default.

Contracts are maintained against `cmd/mcp/tools_workspace.go`,
`tools_exec.go`, `tools_provider.go`, and `serve.go` in the Devsy repository.
Loading
Loading