Workspace Init

Name: Workspace Init
Author: patricio0312rev

patricio0312rev/workspaces

1 installs
9 repo stars
Updated January 25, 2026
patricio0312rev/workspaces

Initializes a new workspace configuration interactively for managing multiple related projects, optionally importing repos via GitHub MCP or a URL.

About

Creates a new workspace configuration through an interactive process gathering workspace name, projects, repos, paths and ports. A developer uses it when configuring a new multi-repo environment.

Optionally fetches repos via GitHub MCP integration
Supports importing config from a gist or repo URL with --from

Workspace Init by the numbers

1 all-time installs (skills.sh)
Ranked #2,476 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/patricio0312rev/workspaces --skill workspace-init

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/patricio0312rev/workspaces/workspace-init.svg)](https://skillselion.com/skills/patricio0312rev/workspaces/workspace-init)

Installs	1
repo stars	★ 9
Last updated	January 25, 2026
Repository	patricio0312rev/workspaces ↗

What it does

Initializes a new workspace configuration interactively for managing multiple related projects, optionally importing repos via GitHub MCP or a URL.

Files

SKILL.mdMarkdownGitHub ↗

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.

#!/bin/bash
# Initialize a new workspace directory structure

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"

# Source utilities
source "$PLUGIN_DIR/lib/workspace-utils.sh"

# Usage
usage() {
    echo "Usage: $0 <workspace-name> [--from <url>]"
    echo ""
    echo "Arguments:"
    echo "  workspace-name    Short identifier for the workspace (e.g., 'acme')"
    echo ""
    echo "Options:"
    echo "  --from <url>      Import configuration from a URL"
    echo ""
    exit 1
}

# Parse arguments
WORKSPACE_NAME=""
IMPORT_URL=""

while [[ $# -gt 0 ]]; do
    case $1 in
        --from)
            IMPORT_URL="$2"
            shift 2
            ;;
        -h|--help)
            usage
            ;;
        *)
            if [ -z "$WORKSPACE_NAME" ]; then
                WORKSPACE_NAME="$1"
            fi
            shift
            ;;
    esac
done

if [ -z "$WORKSPACE_NAME" ]; then
    print_error "Workspace name is required"
    usage
fi

# Validate workspace name (lowercase, alphanumeric, hyphens)
if ! [[ "$WORKSPACE_NAME" =~ ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$ ]]; then
    print_error "Workspace name must be lowercase alphanumeric with optional hyphens"
    exit 1
fi

# Check if workspace already exists
if workspace_exists "$WORKSPACE_NAME"; then
    print_error "Workspace '$WORKSPACE_NAME' already exists at $(get_workspace_path "$WORKSPACE_NAME")"
    exit 1
fi

# Ensure workspaces directory exists
ensure_workspaces_dir

# Create workspace directory structure
WORKSPACE_PATH=$(get_workspace_path "$WORKSPACE_NAME")
mkdir -p "$WORKSPACE_PATH/tasks"

# If importing from URL
if [ -n "$IMPORT_URL" ]; then
    print_info "Importing workspace configuration from: $IMPORT_URL"

    # Try to fetch the URL
    if command -v curl &> /dev/null; then
        if ! curl -fsSL "$IMPORT_URL" -o "$WORKSPACE_PATH/WORKSPACE.md"; then
            print_error "Failed to fetch configuration from URL"
            rm -rf "$WORKSPACE_PATH"
            exit 1
        fi
    elif command -v wget &> /dev/null; then
        if ! wget -q "$IMPORT_URL" -O "$WORKSPACE_PATH/WORKSPACE.md"; then
            print_error "Failed to fetch configuration from URL"
            rm -rf "$WORKSPACE_PATH"
            exit 1
        fi
    else
        print_error "Neither curl nor wget is available"
        rm -rf "$WORKSPACE_PATH"
        exit 1
    fi

    print_success "Workspace '$WORKSPACE_NAME' imported successfully"
    echo ""
    echo "Location: $WORKSPACE_PATH"
    exit 0
fi

# Create empty WORKSPACE.md template
cat > "$WORKSPACE_PATH/WORKSPACE.md" << 'EOF'
# Workspace: {WORKSPACE_DISPLAY_NAME}

## Company
name: {WORKSPACE_DISPLAY_NAME}
description: {DESCRIPTION}

## Projects

| name | repo | path | stack | port |
|------|------|------|-------|------|

## Relationships

## Conventions
- All repos use conventional commits
- Branch naming: feature/<ticket>-<description>

## Documentation

## Commands

## Prerequisites

## Setup Scripts

## Health Checks
EOF

print_success "Workspace '$WORKSPACE_NAME' initialized"
echo ""
echo "Location: $WORKSPACE_PATH"
echo "Config:   $WORKSPACE_PATH/WORKSPACE.md"
echo ""
print_info "Edit WORKSPACE.md to add your projects and configuration"