diff --git a/skills/workspaces/SKILL.md b/skills/workspaces/SKILL.md
new file mode 100644
index 0000000..9462d1e
--- /dev/null
+++ b/skills/workspaces/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: coder-workspaces
+description: >
+  Use an existing Coder deployment from the command line with the
+  `coder` CLI: list, inspect, create, start, stop, and delete
+  workspaces; run commands and edit files inside a workspace over
+  `coder ssh`; forward ports; and read build and agent logs. Use
+  when the user asks to run something "in my workspace", mentions
+  their Coder workspaces or deployment, or wants a remote
+  environment to work in. Do not use for installing or upgrading
+  Coder itself (use the setup skill), authoring a template from
+  scratch (use the templates skill), or adding registry modules to a
+  template (use the modules skill).
+---
+
+# Workspaces
+
+Operate an existing Coder deployment with the `coder` CLI. A
+workspace is a remote development environment, and it is where a
+coding agent does its work: the agent runs commands, edits files,
+and serves ports inside the workspace instead of on the user's
+machine. This skill covers getting into one, working in it, and
+driving its lifecycle.
+
+## Source of truth
+
+`coder <subcommand> --help` is authoritative for flags and output
+columns, and both change between releases. Read it before running a
+command you have not run in this session. Anything the CLI does not
+cover is at <https://coder.com/docs/llms.txt>.
+
+## Preconditions
+
+Run `coder whoami`. Three outcomes:
+
+- Succeeds: continue.
+- `coder` is not on `PATH`: install it with
+  `curl -fsSL https://coder.com/install.sh | sh`, or use the setup
+  skill if the user has no deployment yet.
+- Authentication fails: tell the user to run
+  `coder login <deployment-url>` and stop. The flow opens a browser
+  for a session token, so they run it, not you.
+
+Then check whether you are already inside a Coder workspace:
+`CODER_AGENT_TOKEN` or `CODER_WORKSPACE_NAME` in the environment
+means you are. In that case work with local tools directly instead
+of `coder ssh`, and never stop or delete the workspace you are
+running in.
+
+## Non-interactive use
+
+Every command below has to run without a human at the terminal.
+
+- Pass `-o json` wherever it is offered and parse that. Table output
+  is for humans and its columns move.
+- Pass `-y` to `coder create`, `start`, `stop`, `restart`, and
+  `delete`. Without it they block on a confirmation prompt.
+- `coder ssh <workspace> -- <command>` runs one command and exits.
+  Bare `coder ssh <workspace>` opens an interactive shell and will
+  hang. Never run it.
+- Commands that stream (`coder logs -f`, `coder port-forward`,
+  `coder ping` without `-n`) run until interrupted. Give them a
+  bound or run them in the background.
+- Workspaces belonging to someone else are addressed as
+  `<owner>/<workspace>`.
+- A workspace with more than one agent needs the agent name:
+  `coder ssh <workspace>.<agent> -- <command>`. Without it the CLI
+  errors and lists the available agents.
+
+## Workflow
+
+1. Find the target. `coder list -o json` lists the user's
+   workspaces; `coder list -o json --search <query>` or `--all`
+   widens it. `coder show <workspace>` prints resources, agents, and
+   apps for one.
+2. Make sure it is running. A stopped workspace shows
+   `status: stopped` in `coder list`. `coder start <workspace> -y`
+   starts it, or let `coder ssh` autostart it.
+3. Do the work (tables below).
+4. Verify. `coder logs <workspace>` for the last build,
+   `coder show <workspace>` for the current state.
+5. Report the outcome in one or two sentences, naming the workspace
+   and its status.
+
+### Lifecycle
+
+| Task | Command |
+| --- | --- |
+| List workspaces | `coder list -o json` (add `--all` or `--search`) |
+| Inspect one | `coder show <workspace>` |
+| Create from a template | `coder create <name> --template <template> -y` (add `--preset <preset>` or `--parameter name=value`) |
+| Discover templates and presets | `coder templates list -o json`, `coder templates presets list <template>` |
+| Start, stop, restart | `coder start <workspace> -y`, `coder stop <workspace> -y`, `coder restart <workspace> -y` |
+| Delete | `coder delete <workspace> -y` |
+| Update to the latest template version | `coder update <workspace>` |
+| Build logs | `coder logs <workspace>` (`-n -1` for the previous build) |
+
+`coder create` fails on a template with required parameters unless
+you supply them. Read them from
+`coder templates presets list <template>` or ask the user; do not
+guess values.
+
+### Inside a workspace
+
+| Task | Command |
+| --- | --- |
+| Run a command | `coder ssh <workspace> -- <command>` |
+| Run with env vars | `coder ssh <workspace> -e KEY=value -- <command>` |
+| Read a file | `coder ssh <workspace> -- cat <path>` |
+| Write a file | `coder ssh <workspace> -- tee <path> < local-file` |
+| Copy files in or out | `coder config-ssh -y`, then `scp`/`rsync` against the generated host |
+| Wait for the startup script | `coder ssh <workspace> --wait yes -- true` |
+| Forward a port | `coder port-forward <workspace> --tcp 8080:8080` |
+| Check connectivity | `coder ping <workspace> -n 3` |
+
+`coder config-ssh -y` writes host entries into `~/.ssh/config`, which
+makes every ssh-aware tool (`scp`, `rsync`, `git`, editors) work
+against the workspace. Prefer it over shell heredocs for anything
+larger than a one-liner. Run `coder config-ssh --dry-run` first to
+see the host names it generates; the pattern depends on the
+deployment's hostname suffix.
+
+A workspace's startup script may still be running right after a
+start. `--wait yes` blocks until it finishes; without it a command
+can land in a half-provisioned environment.
+
+## Rules
+
+- Never delete a workspace without an explicit, separate
+  confirmation. `coder delete` is irreversible.
+- Prefer `stop` over `delete` when the user says "shut down" or
+  "turn off".
+- Stopping a workspace discards anything not on a persistent volume.
+  Warn once before stopping if the user has been editing files.
+- Never stop, delete, or restart the workspace you are running
+  inside.
+- Do not print session tokens, `Coder-Session-Token` headers, or the
+  contents of `~/.config/coderv2`. Do not pass a token on a command
+  line.
+- `coder delete --orphan` leaves cloud resources behind. Use it only
+  when the user asks and a normal delete has already failed.