create-workspace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Workspace

创建工作区

A skill for scaffolding structured, multi-repo development workspaces optimized for parallel work by multiple agents and human developers.

这是一个用于搭建结构化多仓库开发工作区的Skill，专为多个Agent与人类开发者的并行工作优化。

Workspace Structure

工作区结构

{workspace-name}/
├── workspace.yaml              # manifest: repos, worktrees, deps, metadata
├── CLAUDE.md                   # project-wide agent context and conventions
├── .gitignore                  # ignores sketch/ directory
├── .claude/
│   └── settings.json           # permissions for coding agents
├── repositories/
│   └── {repoName}/
│       ├── main/               # regular clone at default branch (worktree parent)
│       └── worktrees/
│           └── {worktreeName}/ # git worktree checkouts
├── docs/                       # cross-repo design docs, ADRs, specs
├── deps/
│   └── {depName}/              # full clones of dependency repos
├── tasks/                      # task assignments and coordination
└── sketch/                     # .gitignored agent scratch space

{workspace-name}/
├── workspace.yaml              # 清单文件：包含仓库、工作树、依赖项、元数据
├── CLAUDE.md                   # 项目级Agent上下文与约定
├── .gitignore                  # 忽略sketch/目录
├── .claude/
│   └── settings.json           # 编码Agent的权限设置
├── repositories/
│   └── {repoName}/
│       ├── main/               # 默认分支的常规克隆（工作树父目录）
│       └── worktrees/
│           └── {worktreeName}/ # Git工作树检出目录
├── docs/                       # 跨仓库设计文档、ADR、规格说明
├── deps/
│   └── {depName}/              # 依赖仓库的完整克隆
├── tasks/                      # 任务分配与协调
└── sketch/                     # 被.gitignore忽略的Agent临时工作区

Workflows

工作流程

1. Create a New Workspace

1. 创建新工作区

When the user asks to create a workspace, follow these steps:

Step 1: Gather information. Ask the user for:

Workspace name (will be the root directory name)
A short description of the project/task
Where to create the workspace. Offer the current working directory as the default option, and let the user specify a different path. The workspace will be created as a subdirectory at the chosen location (i.e.,
```
{chosen-path}/{workspace-name}/
```
).
Repositories to include (and which worktrees/branches to create). Accept any of these formats:
- HTTPS URL:
```
https://github.com/user/repo.git
```
- SSH URL:
```
git@github.com:user/repo.git
```
- GitHub shorthand:
```
user/repo
```
  or
```
Username/repoName
```
Dependency repositories (if any), in the same formats above.

If the user provides a

workspace.yaml

file or its contents, parse it directly instead of asking.

Resolving repository references:

When the user provides a GitHub shorthand (

user/repo

) instead of a full URL:

Try
gh
CLI first: Run
```
gh repo view user/repo --json url -q .url
```
to get the HTTPS URL. This works if the user has
```
gh
```
installed and authenticated.
Try GitHub MCP: If
```
gh
```
CLI is not available, use the GitHub MCP
```
get_file_contents
```
or
```
search_repositories
```
tool to verify the repository exists and get its URL.
Fallback — web search: If neither
```
gh
```
CLI nor GitHub MCP is available, use web search to find the repository URL, then ask the user to confirm before cloning.

Once resolved, clone using the full URL. Store the resolved URL in

workspace.yaml

Step 2: Create the directory structure.

bash

mkdir -p {path}/{workspace-name}/{repositories,docs,deps,tasks,sketch}

Where

{path}

is the location chosen in Step 1 (defaults to the current working directory).

Step 3: Generate the workspace.yaml manifest.

Use the template from

assets/workspace.yaml.template

as a reference. The manifest should capture all repositories, their worktrees, and dependencies. Write it to

{workspace-name}/workspace.yaml

Step 4: Resolve and clone repositories.

First, resolve any GitHub shorthand references to full URLs (see "Resolving repository references" above).

Then, for each repository in the manifest:

bash

undefined

当用户要求创建工作区时，请遵循以下步骤：

步骤1：收集信息。向用户询问以下内容：

工作区名称（将作为根目录名称）
项目/任务的简短描述
工作区的创建位置。提供当前工作目录作为默认选项，同时允许用户指定其他路径。工作区将在选定位置创建为子目录（即
```
{chosen-path}/{workspace-name}/
```
）。
要包含的仓库（以及要创建的工作树/分支）。接受以下任意格式：
- HTTPS URL：
```
https://github.com/user/repo.git
```
- SSH URL：
```
git@github.com:user/repo.git
```
- GitHub简写：
```
user/repo
```
  或
```
Username/repoName
```
依赖仓库（如有），格式同上。

如果用户提供了

workspace.yaml

文件或其内容，则直接解析该文件，无需询问上述信息。

解析仓库引用：

当用户提供GitHub简写（

user/repo

）而非完整URL时：

优先尝试
gh
CLI：运行
```
gh repo view user/repo --json url -q .url
```
获取HTTPS URL。此方法仅在用户已安装并认证
```
gh
```
CLI时有效。
尝试GitHub MCP：如果
```
gh
```
CLI不可用，使用GitHub MCP的
```
get_file_contents
```
或
```
search_repositories
```
工具验证仓库是否存在并获取其URL。
备选方案——网页搜索：如果
```
gh
```
CLI和GitHub MCP均不可用，通过网页搜索查找仓库URL，然后在克隆前请用户确认。

解析完成后，使用完整URL进行克隆。将解析后的URL存储在

workspace.yaml

中。

步骤2：创建目录结构

bash

mkdir -p {path}/{workspace-name}/{repositories,docs,deps,tasks,sketch}

其中

{path}

是步骤1中选定的位置（默认为当前工作目录）。

步骤3：生成workspace.yaml清单文件

以

assets/workspace.yaml.template

中的模板为参考。清单文件应捕获所有仓库、其工作树以及依赖项。将其写入

{workspace-name}/workspace.yaml

。

步骤4：解析并克隆仓库

首先，将所有GitHub简写引用解析为完整URL（参见上方“解析仓库引用”部分）。

然后，针对清单中的每个仓库执行：

bash

undefined

Clone the repository into the main/ directory

将仓库克隆到main/目录

git clone {resolved-url} {workspace-root}/repositories/{repoName}/main

For each worktree, create a branch and worktree

为每个工作树创建分支和工作树

cd {workspace-root}/repositories/{repoName}/main git worktree add ../worktrees/{worktreeName} -b {branchName}


If the branch already exists on the remote, use checkout instead of `-b`:

```bash
git worktree add ../worktrees/{worktreeName} {branchName}

Important worktree notes:

The
```
main/
```
clone is the worktree parent. Agents should avoid switching branches in
```
main/
```
.
Each worktree is an independent working directory with its own HEAD, index, and working tree.
Multiple agents can work on different worktrees of the same repo simultaneously without conflicts.

Step 5: Clone dependencies.

For each dependency in the manifest:

bash

undefined

cd {workspace-root}/repositories/{repoName}/main git worktree add ../worktrees/{worktreeName} -b {branchName}


如果远程仓库中已存在该分支，则使用checkout而非`-b`：

```bash
git worktree add ../worktrees/{worktreeName} {branchName}

工作树重要注意事项：

```
main/
```
克隆是工作树的父目录。Agent应避免在
```
main/
```
目录中切换分支。
每个工作树都是独立的工作目录，拥有自己的HEAD、索引和工作树。
多个Agent可同时在同一仓库的不同工作树上工作，不会产生冲突。

步骤5：克隆依赖项

针对清单中的每个依赖项执行：

bash

undefined

Full clone (not shallow — deps may contain bugs or ongoing work to analyze)

完整克隆（非浅克隆——依赖项可能包含需要分析的Bug或正在进行的工作）

git clone {url} {workspace-name}/deps/{depName}

If a specific ref is specified, check it out

如果指定了特定引用，则检出该引用

cd {workspace-name}/deps/{depName} git checkout {ref}


**Step 6: Generate the CLAUDE.md.**

Use the template from `assets/CLAUDE.md.template` as a starting point. Populate it with:
- The workspace description from the manifest
- The list of repositories with their purposes
- The list of worktrees and what each is for
- The list of dependencies
- Cross-repo relationships (ask the user if not obvious)

**Step 7: Create the .gitignore.**

Write a `.gitignore` at the workspace root:

sketch/


**Step 8: Set up agent permissions.**

Create `.claude/settings.json` at the workspace root using the template from `assets/settings.json.template`. This file configures permissions so that coding agents can perform common development tasks without requiring manual approval for every command, while still blocking dangerous operations.

```bash
mkdir -p {workspace-name}/.claude

Copy the template as-is. The defaults are designed to be safe for multi-repo development:

Allow (no prompt): Read-only tools, git read ops, git worktree management, build/test/lint commands for common package managers, file exploration, version checks.
Ask (prompt once): Git write ops (commit, push, pull, merge, rebase), package installs, docker operations.
Deny (always blocked):
```
rm -rf
```
,
```
sudo
```
, force pushes,
```
git reset --hard
```
, reading
```
.env
```
/
```
.env.local
```
/
```
.env.*.local
```
, secrets, SSH keys, AWS credentials, PEM/key files.

Note:

.env.example

and

.env.template

files are intentionally not blocked — agents need to read these to understand the environment variable setup.

This file is generated once. Users can edit it afterwards to add project-specific rules.

Step 9: Confirm completion. Summarize what was created:

Number of repositories cloned
Number of worktrees created
Number of dependencies cloned
Location of the workspace

cd {workspace-name}/deps/{depName} git checkout {ref}


**步骤6：生成CLAUDE.md**

以`assets/CLAUDE.md.template`中的模板为起点。填充以下内容：
- 清单文件中的工作区描述
- 所有仓库及其用途列表
- 所有工作树及其用途列表
- 依赖项列表
- 跨仓库关系（如果不明确，请询问用户）

**步骤7：创建.gitignore**

在工作区根目录创建`.gitignore`文件：

sketch/


**步骤8：设置Agent权限**

使用`assets/settings.json.template`中的模板，在工作区根目录创建`.claude/settings.json`。该文件用于配置权限，使编码Agent无需每次操作都手动批准即可执行常见开发任务，同时仍会阻止危险操作。

```bash
mkdir -p {workspace-name}/.claude

直接复制模板内容。默认配置专为多仓库开发设计，确保安全性：

允许（无需提示）：只读工具、Git读取操作、Git工作树管理、针对常见包管理器的构建/测试/检查命令、文件探索、版本检查。
询问（提示一次）：Git写入操作（commit、push、pull、merge、rebase）、包安装、Docker操作。
拒绝（始终阻止）：
```
rm -rf
```
、
```
sudo
```
、强制推送、
```
git reset --hard
```
、读取
```
.env
```
/
```
.env.local
```
/
```
.env.*.local
```
、密钥、SSH密钥、AWS凭证、PEM/密钥文件。

注意：

.env.example

和

.env.template

文件不会被阻止——Agent需要读取这些文件以了解环境变量的配置方式。

此文件仅生成一次。用户可在之后编辑该文件，添加项目特定规则。

步骤9：确认完成。总结已创建的内容：

已克隆的仓库数量
已创建的工作树数量
已克隆的依赖项数量
工作区的位置

2. Add a Repository to an Existing Workspace

2. 向现有工作区添加仓库

When the user asks to add a repo to an existing workspace:

Read the existing
```
workspace.yaml
```
Clone the repo into
```
repositories/{repoName}/main/
```
Create any requested worktrees
Update
```
workspace.yaml
```
with the new repository entry
Update
```
CLAUDE.md
```
to include the new repository

当用户要求向现有工作区添加仓库时：

读取现有的
```
workspace.yaml
```
将仓库克隆到
```
repositories/{repoName}/main/
```
创建所有请求的工作树
更新
```
workspace.yaml
```
，添加新仓库条目
更新
```
CLAUDE.md
```
，包含新仓库信息

3. Add a Worktree to an Existing Repository

3. 向现有仓库添加工作树

When the user asks to add a worktree:

Read
```
workspace.yaml
```
to find the repository

Create the worktree:

bash

cd {workspace}/repositories/{repoName}/main
git worktree add ../worktrees/{worktreeName} -b {branchName}

Update
```
workspace.yaml
```
with the new worktree entry

当用户要求添加工作树时：

读取
```
workspace.yaml
```
找到目标仓库

创建工作树：

bash

cd {workspace}/repositories/{repoName}/main
git worktree add ../worktrees/{worktreeName} -b {branchName}

更新
```
workspace.yaml
```
，添加新工作树条目

4. Add a Dependency

4. 添加依赖项

When the user asks to add a dependency:

Clone the dependency into
```
deps/{depName}/
```
Optionally check out a specific ref
Update
```
workspace.yaml
```
Update
```
CLAUDE.md
```

当用户要求添加依赖项时：

将依赖项克隆到
```
deps/{depName}/
```
可选：检出特定引用
更新
```
workspace.yaml
```
更新
```
CLAUDE.md
```

5. Show Workspace Status

5. 查看工作区状态

When the user asks about workspace status:

Read
```
workspace.yaml
```
For each repository and worktree, run
```
git status
```
and
```
git log --oneline -3
```
Report: current branches, uncommitted changes, recent commits

当用户询问工作区状态时：

读取
```
workspace.yaml
```
针对每个仓库和工作树，运行
```
git status
```
和
```
git log --oneline -3
```
报告：当前分支、未提交的更改、最近的三次提交

6. Remove a Worktree

6. 删除工作树

When the user asks to remove a worktree:

Run
```
git worktree remove
```
from the main clone
Update
```
workspace.yaml
```

当用户要求删除工作树时：

在主克隆目录中运行
```
git worktree remove
```
更新
```
workspace.yaml
```

Conventions

约定

Never modify the
main/
clone's branch — it anchors all worktrees. Document this in CLAUDE.md.
Worktree names should match branch names when possible for clarity. If the branch has slashes (e.g.,
```
feature/auth
```
), use a slugified name for the worktree directory (e.g.,
```
feature-auth
```
).
The
sketch/
directory is ephemeral — agents can write anything there. It is always gitignored.
The
tasks/
directory is for coordination between agents and humans. Files here describe work items, assignments, and status.
The
docs/
directory is for durable design documentation that outlives any single task.

切勿修改
main/
克隆的分支——它是所有工作树的锚点。请在CLAUDE.md中记录此规则。
工作树名称应尽可能与分支名称匹配，以保证清晰性。如果分支名称包含斜杠（如
```
feature/auth
```
），则使用短横线替换斜杠作为工作树目录名称（如
```
feature-auth
```
）。
sketch/
目录为临时目录——Agent可在其中写入任意内容。该目录始终被git忽略。
tasks/
目录用于Agent与人类之间的协作协调。此目录中的文件描述工作项、分配情况和状态。
docs/
目录用于存储持久化的设计文档，这些文档的生命周期长于单个任务。

Error Handling

错误处理

If a
```
git clone
```
fails, report the error and continue with remaining repos. Mark failed repos in the output.
If a worktree branch already exists locally, use
```
git worktree add ../worktrees/{name} {branch}
```
without
```
-b
```
.
If a worktree directory already exists, warn the user and skip unless they confirm overwriting.
If
```
workspace.yaml
```
already exists when creating a new workspace, ask before overwriting.

如果
```
git clone
```
失败，报告错误并继续处理剩余仓库。在输出中标记失败的仓库。
如果工作树分支已在本地存在，则使用
```
git worktree add ../worktrees/{name} {branch}
```
，无需添加
```
-b
```
参数。
如果工作树目录已存在，向用户发出警告，除非用户确认覆盖，否则跳过创建。
如果创建新工作区时
```
workspace.yaml
```
已存在，在覆盖前请用户确认。