workflow-migration

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name NOTION_TOKEN`

## How It Works

### Step 1: Identify the Local Skill to Migrate

**Ask the user**:
- Which skill do they want to migrate?
- Where is the skill located? (usually `~/.claude/skills/{skill-name}/`)

**Discover local skills**:
```bash
# List all local Claude Code skills
ls -la ~/.claude/skills/

# Show available skills
find ~/.claude/skills -name "SKILL.md" -type f
```

**Read the skill definition**:
```bash
# Read the skill's SKILL.md file
cat ~/.claude/skills/{skill-name}/SKILL.md
```

**IMPORTANT**: Claude Code skills are defined in `SKILL.md` files with natural language descriptions, not YAML config files.

### Step 2: Analyze the Skill

For the skill found, understand:
1. **Purpose**: What does this skill do?
2. **Commands**: What scripts/commands does it run?
3. **Dependencies**: What tools/languages does it need?
4. **Environment**: What env vars/secrets does it use?
5. **Triggers**: When/how is it invoked?

**Read skill files**:
```bash
# Read the main skill definition
cat ~/.claude/skills/{skill-name}/SKILL.md

# Check for local .env file
cat ~/.claude/skills/{skill-name}/.env 2>/dev/null

# Check for dependencies
ls ~/.claude/skills/{skill-name}/requirements.txt 2>/dev/null
ls ~/.claude/skills/{skill-name}/package.json 2>/dev/null

# Check for helper scripts
ls -la ~/.claude/skills/{skill-name}/scripts/ 2>/dev/null
```

**Extract environment variables from SKILL.md**:
- Look for mentions of environment variables (e.g., `NOTION_TOKEN`, `DATABASE_ID`)
- Find patterns like `$VARIABLE_NAME` or `env.VARIABLE_NAME`
- Note which variables are required vs optional

### Step 3: Detect and Confirm Environment Variables

**Auto-detect environment variables**:

1. **Extract from local skill's .env file**:
```bash
# If skill has a .env file, read it
if [ -f ~/.claude/skills/{skill-name}/.env ]; then
  cat ~/.claude/skills/{skill-name}/.env
fi
```

2. **Parse SKILL.md for environment variable references**:
```bash
# Look for patterns like $VAR_NAME, ${VAR_NAME}, or mentions of env vars
grep -E '\$\{?[A-Z_]+\}?|NOTION_|DATABASE_|API_|TOKEN|SECRET' ~/.claude/skills/{skill-name}/SKILL.md
```

3. **Read current environment values**:
```bash
# For each detected variable, get its current value
echo $NOTION_TOKEN
echo $DATABASE_ID
# etc.
```

**Present to user for confirmation**:
```
I detected the following environment variables from your local skill:

✓ CLAUDE_CODE_OAUTH_TOKEN: sk-ant-oat01-... (found in environment)
✓ NOTION_TOKEN: ntn_F391... (found in ~/.claude/skills/world-news-summary/.env)
✓ NOTION_TOKEN: ntn_F391... (found in ~/.claude/skills/world-news-summary/.env)
✓ DATABASE_ID: 2e80e96f... (found in ~/.claude/skills/world-news-summary/.env)
✓ NEWS_CATEGORIES: ai_agents,international,business (found in .env)

Should I use these values for the VM0 agent? (y/n)
If no, I'll ask you to provide the values manually.
```

**If user confirms**, proceed with these values.
**If user declines**, ask for each variable individually.

### Step 4: Create VM0 Agent Configuration

**Ask the user**:
- Where to create the VM0 project? (default: `~/Desktop/{skill-name}/`)

Generate `vm0.yaml` (NOT `.vm0/vm0.yaml`) with detected environment variables:

```yaml
version: "1.0"

agents:
  {skill-name}:
    provider: claude-code
    instructions: AGENTS.md

    # Include VM0 skills based on what the local skill uses
    skills:
      - https://github.com/vm0-ai/vm0-skills/tree/main/notion    # if uses Notion
      - https://github.com/vm0-ai/vm0-skills/tree/main/github    # if uses GitHub
      - https://github.com/vm0-ai/vm0-skills/tree/main/slack     # if uses Slack

    environment:
      # Claude Code OAuth token (if needed)
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

      # Map all environment variables from local skill
      API_KEY: ${{ secrets.API_KEY }}
      DATABASE_ID: ${{ secrets.DATABASE_ID }}
      # Add more as needed
```

**IMPORTANT**:
- Use `vm0.yaml` at project root, NOT `.vm0/vm0.yaml`
- Use `agents:` structure with skill name as key
- Use `instructions: AGENTS.md` (relative path)

**Also generate `.env` file for local testing** (using detected values):
```bash
# Auto-generate .env file with detected values
cat > .env << EOF
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
NOTION_TOKEN=ntn_F391...
NOTION_TOKEN=ntn_F391...
DATABASE_ID=2e80e96f...
NEWS_CATEGORIES=ai_agents,international,business
EOF
```

**Security note**: Remind user that `.env` is for local testing only. For production, use VM0 secrets.

### Step 5: Convert SKILL.md to AGENTS.md

Create `AGENTS.md` at project root that translates the local skill's logic into agent instructions.

**Key Principle**: Translate the skill's natural language description into agent instructions that accomplish the same tasks.

**Conversion approach**:
1. Read the local `SKILL.md` carefully
2. Understand the workflow steps and logic
3. Preserve the same structure and steps
4. Add VM0-specific guidance (e.g., using VM0 skills instead of raw API calls)
5. Include error handling and verification steps

**Template**:
```markdown
# {Project Name} Agent

You are an automation agent that performs the same tasks as the local Claude Code workflow.

## Your Mission

{High-level description of what the local workflow accomplishes}

## Available Skills (from local setup)

### Skill 1: {Skill Name}
**Purpose**: {What this skill does}

**How to use**:
{Step-by-step instructions in natural language}

**Commands**:
{Actual commands/scripts to run}

**Verification**:
{How to verify success}

### Skill 2: {Skill Name}
...

## Common Workflows

### Workflow 1: {Workflow Name}
When asked to {task description}, execute:
1. {Step 1}
2. {Step 2}
...

### Workflow 2: {Workflow Name}
...

## Environment Variables

{List all env vars needed}

## Error Handling

{How to handle errors}
```

### Step 6: Create Dockerfile with Dependencies

Generate `Dockerfile` at project root with all tools/dependencies:

**Choose base image based on skill's language**:
- Python skills → `python:3.11-slim`
- Node.js skills → `node:20-slim`
- Shell scripts → `ubuntu:22.04`
- Multi-language → `ubuntu:22.04` with multiple runtimes

```dockerfile
FROM {base-image}

WORKDIR /workspace

# Install system dependencies
RUN apt-get update && apt-get install -y \
    bash curl jq git \
    {additional-tools} \
    && rm -rf /var/lib/apt/lists/*

# Install language-specific dependencies
COPY requirements.txt* ./
RUN pip install --no-cache-dir -r requirements.txt

# Copy scripts and helper files (if any)
COPY scripts/ ./scripts/ 2>/dev/null || true
COPY SKILL.md ./

# Create any necessary directories
RUN mkdir -p ~/reports

CMD ["/bin/bash"]
```

**Also create `.dockerignore`**:
```
.git
.gitignore
*.md
README.md
.env*
vm0.yaml
__pycache__
*.pyc
.pytest_cache
*.log
.DS_Store
reports/
```

## Complete Real Example: world-news-summary

This is a real migration case showing exactly how to convert a local Claude Code skill to VM0.

### Original Local Skill

**Location**: `~/.claude/skills/world-news-summary/SKILL.md`

**What it does**: Generates daily world news summaries with bilingual content and publishes to Notion automatically.

**Key features**:
- Searches web for latest news (AI/Agent products, international affairs, business)
- Fetches full article content
- Generates bilingual summaries
- Publishes structured reports to Notion database

**Required environment variables**:
- `CLAUDE_CODE_OAUTH_TOKEN`
- `NOTION_TOKEN` / `NOTION_TOKEN`
- `DATABASE_ID`

### Generated VM0 Configuration

**Project structure**:
```
~/Desktop/world-news-summary/
├── vm0.yaml              # VM0 configuration
├── AGENTS.md             # Agent instructions (converted from SKILL.md)
├── Dockerfile            # Container definition
├── .dockerignore         # Docker build exclusions
├── .env                  # Local environment variables (for testing)
└── README.md            #