# Workspace Init

> Initialize a new workspace configuration for managing multiple related projects. Use when user says "setup workspace", "create workspace", "init workspace", or wants to configure a new multi-repo environment.

- Skill: `patricio0312rev/workspace-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add patricio0312rev/workspace-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/patricio0312rev/workspace-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: patricio0312rev (https://skillmd.com/u/patricio0312rev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/patricio0312rev/workspace-init

---


# Skill: Workspace Init

## Description

Initialize a new workspace configuration for managing multiple related projects/repositories.

## Arguments

- `--from <url>` - Import workspace configuration from a gist or repository URL

## Instructions

When the user wants to create a new workspace, follow this interactive process:

### Step 0: Check for GitHub MCP Integration

Before starting, check if GitHub MCP tools are available (e.g., `mcp__github__list_repos`, `mcp__github__search_repositories`).

If available:
- Offer to fetch the user's repositories automatically
- Show a list of their repos to select from
- This saves time entering repo URLs manually

Example:
```
I noticed you have GitHub MCP configured. Would you like me to:
1. Fetch your repositories from GitHub to help set up the workspace
2. Enter repository information manually
```

### Step 1: Gather Basic Information

Ask the user for:
1. **Workspace name** - A short identifier (e.g., "acme", "mycompany")
2. **Company/Project name** - Full display name (e.g., "Acme Corp")
3. **Description** - Brief description of the workspace

### Step 2: Add Projects

For each project, collect information with **clear path display**:

1. **Name** - Project identifier
   - If using GitHub MCP: default to the **actual repo name** (e.g., "neosophia-amap-api")
   - User can optionally provide a shorter alias
   - Do NOT substitute with generic names like "api" or "admin"

2. **Repository URL** - Git clone URL
   - If GitHub MCP is available, offer to select from their repos
   - Otherwise ask for the URL directly

3. **Local path** - Where the project lives locally

   **IMPORTANT: Auto-detect existing repos first!**

   Before asking where to clone, search for existing local folders that match the repo name:
   - Check current directory and common locations (`~/Sites`, `~/work`, `~/projects`, `~/code`, `~/dev`)
   - Use `find` or `ls` to locate folders matching the repo name
   - If repo is `neosophia-amap-api`, look for folders named `neosophia-amap-api`

   **If found**: Auto-use that path. Don't ask the user.
   ```
   ✓ Found neosophia-amap-api at /Users/patricio/Sites/neosophia-amap-api
   ```

   **If NOT found**: Then ask where to clone it.
   ```
   Where should neosophia-amap-api be cloned?

   Suggested: /Users/patricio/Sites/neosophia-amap-api
   ```

   This saves time when users already have repos cloned locally.

4. **Stack** - Technologies used (e.g., "Node, Express, PostgreSQL")

5. **Port** - Development server port (if applicable)

**After each project**, show a summary:
```
Project added:
  Name: api
  Repo: git@github.com:acme/api.git
  Path: /Users/patricio/Sites/acme/api
  Stack: Node, Express
  Port: 3000

Add another project? (y/n)
```

### Step 3: Define Relationships (Optional)

Ask if any projects depend on others. Format:
- `frontend -> api` means frontend calls the api

### Step 4: Add Documentation Links (Optional)

Collect any relevant documentation URLs:
- API docs
- Design files (Figma, etc.)
- Wiki/Notion
- Slack channels

### Step 5: Define Commands (Optional)

Ask for common workspace-level commands:
- `start-all` - Start all services
- `stop-all` - Stop all services
- `test-all` - Run all tests

### Step 6: Generate Configuration

Create the workspace directory at `~/.claude/workspaces/<name>/` and generate the WORKSPACE.md file.

### Step 7: Offer to Clone

Ask if the user wants to clone all repositories now using `/workspaces:clone all`.

### Import from URL

If `--from <url>` is provided:
1. Fetch the content from the URL
2. Parse it as WORKSPACE.md format
3. Create the workspace with that configuration

### GitHub MCP Integration Details

If GitHub MCP is available, you can use these tools:

1. **List user's repos**: Use `mcp__github__list_repos` to show available repositories
2. **Search repos**: Use `mcp__github__search_repositories` to find specific repos
3. **Get repo details**: Fetch clone URLs, descriptions, and default branches

**IMPORTANT**: When showing repos from GitHub, display the **actual repository names** exactly as they appear in GitHub. Do NOT substitute with generic names like "api", "landing", "web", "admin".

When listing repos, show them with their **real names**:
```
Your GitHub repositories:
  1. neosophia-amap-api - Backend API for AMAP
  2. neosophia-amap-admin - Admin dashboard for AMAP
  3. neosophia-amap-landing - Landing page
  4. neosophia-experts-dashboard - Experts dashboard
  5. neosophia-screen-api - Screen API service
  6. arkvault - Vault application
  7. arkscan - Block explorer

Select repos to add (comma-separated numbers, e.g., "1,2,4"):
```

When user selects repos:
- **Project name** defaults to the actual repo name (e.g., `neosophia-amap-api`, not `api`)
- User can optionally provide a shorter alias
- Clone URL comes directly from the GitHub repo data
- **Auto-detect local paths**: Search for existing folders matching each repo name before asking

Example auto-detection flow:
```
Selected: neosophia-amap-api, neosophia-amap-landing, neosophia-amap-admin

Scanning for existing repos...
✓ neosophia-amap-api found at /Users/patricio/Sites/neosophia-amap-api
✓ neosophia-amap-landing found at /Users/patricio/Sites/neosophia-amap-landing
✗ neosophia-amap-admin not found locally

Where should neosophia-amap-admin be cloned?
Suggested: /Users/patricio/Sites/neosophia-amap-admin
```

### Example Output

After successful initialization:

```
✓ Workspace 'neosophia' created at ~/.claude/workspaces/neosophia/

Projects configured:
  • neosophia-amap-api
    Path: /Users/patricio/Sites/neosophia-amap-api (existing)
    Port: 3000
  • neosophia-amap-landing
    Path: /Users/patricio/Sites/neosophia-amap-landing (existing)
    Port: 3001
  • neosophia-amap-admin
    Path: /Users/patricio/Sites/neosophia-amap-admin (to clone)
    Port: 3002

Run '/workspaces:clone all' to clone missing repositories.
```