From fa75d84b75d06ce273f9b3c465aec6c2268487c5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 13 Jan 2026 06:04:45 +0000
Subject: [PATCH] docs: clarify clawdhub workdir defaults

---
 docs/start/faq.md        | 2 +-
 docs/tools/clawdhub.md   | 5 +++--
 docs/tools/skills.md     | 3 ++-
 skills/clawdhub/SKILL.md | 2 +-
 4 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/start/faq.md b/docs/start/faq.md
index 795b358f2..177a40601 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -238,7 +238,7 @@ clawdhub install <skill-slug>
 clawdhub update --all
 ```
 
-ClawdHub installs into `./skills` under your current directory; Clawdbot treats that as `<workspace>/skills` on the next session. For shared skills across agents, place them in `~/.clawdbot/skills/<name>/SKILL.md`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills) and [ClawdHub](/tools/clawdhub).
+ClawdHub installs into `./skills` under your current directory (or falls back to your configured Clawdbot workspace); Clawdbot treats that as `<workspace>/skills` on the next session. For shared skills across agents, place them in `~/.clawdbot/skills/<name>/SKILL.md`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills) and [ClawdHub](/tools/clawdhub).
 
 ### Is there a dedicated sandboxing doc?
 
diff --git a/docs/tools/clawdhub.md b/docs/tools/clawdhub.md
index 298db66ec..7a7716922 100644
--- a/docs/tools/clawdhub.md
+++ b/docs/tools/clawdhub.md
@@ -48,7 +48,7 @@ bun add -g clawdhub
 
 ## How it fits into Clawdbot
 
-By default, the CLI installs skills into `./skills` under your current working directory. Clawdbot loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.clawdbot/skills` or bundled skills, workspace skills take precedence.
+By default, the CLI installs skills into `./skills` under your current working directory. If a Clawdbot workspace is configured, `clawdhub` falls back to that workspace unless you override `--workdir` (or `CLAWDHUB_WORKDIR`). Clawdbot loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.clawdbot/skills` or bundled skills, workspace skills take precedence.
 
 For more detail on how skills are loaded, shared, and gated, see
 [Skills](/tools/skills).
@@ -67,7 +67,7 @@ For more detail on how skills are loaded, shared, and gated, see
 
 Global options (apply to all commands):
 
-- `--workdir <dir>`: Working directory (default: current dir).
+- `--workdir <dir>`: Working directory (default: current dir; falls back to Clawdbot workspace).
 - `--dir <dir>`: Skills directory, relative to workdir (default: `skills`).
 - `--site <url>`: Site base URL (browser login).
 - `--registry <url>`: Registry API base URL.
@@ -201,4 +201,5 @@ export CLAWDHUB_DISABLE_TELEMETRY=1
 - `CLAWDHUB_SITE`: Override the site URL.
 - `CLAWDHUB_REGISTRY`: Override the registry API URL.
 - `CLAWDHUB_CONFIG_PATH`: Override where the CLI stores the token/config.
+- `CLAWDHUB_WORKDIR`: Override the default workdir.
 - `CLAWDHUB_DISABLE_TELEMETRY=1`: Disable telemetry on `sync`.
diff --git a/docs/tools/skills.md b/docs/tools/skills.md
index e78db559a..2e50b318b 100644
--- a/docs/tools/skills.md
+++ b/docs/tools/skills.md
@@ -58,7 +58,8 @@ Common flows:
   - `clawdhub sync --all`
 
 By default, `clawdhub` installs into `./skills` under your current working
-directory; Clawdbot picks that up as `<workspace>/skills` on the next session.
+directory (or falls back to the configured Clawdbot workspace). Clawdbot picks
+that up as `<workspace>/skills` on the next session.
 
 ## Format (AgentSkills + Pi-compatible)
 
diff --git a/skills/clawdhub/SKILL.md b/skills/clawdhub/SKILL.md
index 7033453da..d9e9fdac2 100644
--- a/skills/clawdhub/SKILL.md
+++ b/skills/clawdhub/SKILL.md
@@ -49,5 +49,5 @@ clawdhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.2.0 --
 
 Notes
 - Default registry: https://clawdhub.com (override with CLAWDHUB_REGISTRY or --registry)
-- Default workdir: cwd; install dir: ./skills (override with --workdir / --dir)
+- Default workdir: cwd (falls back to Clawdbot workspace); install dir: ./skills (override with --workdir / --dir / CLAWDHUB_WORKDIR)
 - Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set