diff --git a/README.md b/README.md
index d4132142..a2483ded 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,21 @@ The first command registers the marketplace; the second installs the plugin. Cod
 
 </details>
 
+<details>
+<summary><b>Dojo Workspace</b></summary>
+
+Installing Dojo Workspace puts the `dojo` command on your PATH:
+
+```bash
+dojo skills add addyosmani/agent-skills
+```
+
+If `dojo` is not on your PATH, add its install folder: `~/.local/bin` on macOS/Linux (`~/.local/bin/dojo`) or `%LOCALAPPDATA%\dojo\bin` on Windows (`dojo.exe`). Or run the binary by its full path.
+
+Skills install into `~/.agents/skills/`; enable the ones you want for each lane (Dojo Solo / Dojo Duo). Add `-p` to install into the current project's `.agents/skills/` instead. You can also install from the app's **Skills** panel → **Add External Skills**. See [docs/dojo-setup.md](docs/dojo-setup.md).
+
+</details>
+
 <details>
 <summary><b>Command Code</b></summary>
 
diff --git a/docs/dojo-setup.md b/docs/dojo-setup.md
new file mode 100644
index 00000000..57ef7a9e
--- /dev/null
+++ b/docs/dojo-setup.md
@@ -0,0 +1,45 @@
+# ⛩️ Using agent-skills with Dojo Workspace
+
+Dojo Workspace is a desktop app that reads skills from the standard `.agents/skills/` folders. Installing it also puts the `dojo` command on your PATH.
+
+If `dojo` is not found, add its install folder to your PATH, or run it by its full path:
+
+| OS | Folder to add to PATH | Full path |
+| --- | --- | --- |
+| macOS / Linux | `~/.local/bin` | `~/.local/bin/dojo` |
+| Windows | `%LOCALAPPDATA%\dojo\bin` | `%LOCALAPPDATA%\dojo\bin\dojo.exe` |
+
+Open a new terminal after the first app launch so the PATH change is picked up.
+
+## Install for all projects
+
+```bash
+dojo skills add addyosmani/agent-skills
+```
+
+Skills install into `~/.agents/skills/` and appear in the **Skills** panel under the `addyosmani-agent-skills` group. Enable the ones you want for each lane (Dojo Solo or Dojo Duo).
+
+## Install for one project
+
+Run from the project root:
+
+```bash
+dojo skills add -p addyosmani/agent-skills
+```
+
+Skills install into the project's `.agents/skills/` and are enabled for that project. Commit `skills-lock.json` to share them with your team.
+
+## Manage
+
+```bash
+dojo skills list                      # add -p for the current project
+dojo skills remove addyosmani/agent-skills
+```
+
+`remove` takes a whole repo or a single skill name.
+
+## How skills load
+
+Only each skill's name and description are listed for the model. The full `SKILL.md` loads on demand when a task matches, so enabling many skills stays cheap. Dojo also reads project instructions from `AGENTS.md`.
+
+If you'd rather add skills through the app's UI, [here is how](https://heydojo.ai/learn/dojo-skills-teach-your-agent-new-workflows).