Create Workspace

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

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

Workflows

1. Create a New Workspace

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

# Clone the repository into the main/ directory
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

# Full clone (not shallow — deps may contain bugs or ongoing work to analyze)
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

2. Add a Repository to an Existing Workspace

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

3. Add a Worktree to an Existing Repository

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

4. Add a Dependency

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

5. Show Workspace Status

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

6. Remove a Worktree

When the user asks to remove a worktree:

Run
```
git worktree remove
```
from the main clone
Update
```
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.

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.

create-workspace

NPX Install

Tags

SKILL.md Content

Create Workspace

Workspace Structure

Workflows

1. Create a New Workspace

2. Add a Repository to an Existing Workspace

3. Add a Worktree to an Existing Repository

4. Add a Dependency

5. Show Workspace Status

6. Remove a Worktree

Conventions

Error Handling