agent-team/skills/web-search/DEPLOYMENT.md

Web Search Skill Deployment Guide

Problem Statement

When using the web-search skill in Cowork sessions, Claude needs to call bash scripts like:

bash SKILLs/web-search/scripts/search.sh "query" 10

However, this relative path approach has two critical issues:

1. Development Mode: Works fine when working directory is project root
2. Production Mode: After packaging, the SKILLs directory is bundled, and user's working directory is not the app installation directory

Solution: Environment Variable Injection

Overview

We inject a SKILLS_ROOT environment variable that points to the correct SKILLs directory in both development and production modes.

Implementation

1. Modified electron/libs/coworkUtil.ts

Added a getSkillsRoot() function that returns the correct path:

function getSkillsRoot(): string {
  const appPath = app.getAppPath();

  // In development
  if (appPath.includes('node_modules') || !app.isPackaged) {
    const projectRoot = join(appPath, '../..');
    return join(projectRoot, 'SKILLs');
  }

  // In production, SKILLs are copied to userData
  return join(app.getPath('userData'), 'SKILLs');
}

And inject it into the environment:

export async function getEnhancedEnv(): Promise<Record<string, string | undefined>> {
  // ... existing code ...

  // Inject SKILLs directory path for skill scripts
  const skillsRoot = getSkillsRoot();
  env.SKILLS_ROOT = skillsRoot;
  env.LOBSTERAI_SKILLS_ROOT = skillsRoot; // Alternative name for clarity

  // ... rest of code ...
}

2. Updated SKILLs/web-search/SKILL.md

Changed all script invocations from:

bash SKILLs/web-search/scripts/search.sh "query" 10

To:

bash "$SKILLS_ROOT/web-search/scripts/search.sh" "query" 10

How It Works

1. Development Mode:

   • SKILLS_ROOT → /path/to/project/SKILLs
   • Scripts execute from project directory
   • All relative paths work correctly

2. Production Mode:

   • SKILLS_ROOT → ~/Library/Application Support/lobsterai/SKILLs (macOS)
   • Skills are copied to userData during first launch
   • Scripts execute from packaged location

3. User Working Directory:

   • Can be any directory user chooses
   • No longer needs to be project root
   • Skills always accessible via $SKILLS_ROOT

Testing

# Set environment variable manually for testing
export SKILLS_ROOT="/xxx/SKILLs"

# Test search
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "test query" 5

Packaging Considerations

When packaging the application:

1. Copy SKILLs to Resources: Ensure SKILLs directory is copied to extraResources or userData
2. Verify Paths: Test that getSkillsRoot() returns correct path in packaged app
3. Script Permissions: Ensure bash scripts have execute permissions after copying

Benefits

✅ Cross-platform: Works on macOS, Windows, Linux ✅ Development-friendly: No changes needed for local development ✅ Production-ready: Handles packaged app correctly ✅ User-friendly: Users can set any working directory ✅ Maintainable: Single source of truth for SKILLs location

Migration Guide for Other Skills

If you create new skills that need to call scripts, always use:

bash "$SKILLS_ROOT/your-skill/scripts/your-script.sh"

Never use:

bash SKILLs/your-skill/scripts/your-script.sh  # ❌ Won't work in production

Troubleshooting

Problem: SKILLS_ROOT not found

Solution: Ensure Electron app is recompiled after changes to coworkUtil.ts

npm run build
npm run electron:dev

Problem: Scripts not found in production

Solution: Verify SKILLs are included in packaging:

• Check electron-builder.yml or packaging config
• Ensure extraResources includes SKILLs/**/*
• Verify file permissions for bash scripts

Problem: Permission denied when running scripts

Solution: Set execute permissions:

chmod +x "$SKILLS_ROOT/web-search/scripts/*.sh"

Related Files

• electron/libs/coworkUtil.ts - Environment variable injection
• electron/libs/coworkRunner.ts - Cowork execution engine
• SKILLs/web-search/SKILL.md - Updated skill documentation
• electron/skillManager.ts - Skill directory management
• electron/skillServices.ts - Background service management

Future Improvements

1. Auto-copy on First Launch: Automatically copy bundled SKILLs to userData on first app launch
2. Version Management: Track skill versions and auto-update mechanism
3. Skill Registry: Central registry for installed skills with metadata
4. Path Validation: Add startup checks to verify SKILLS_ROOT is accessible

---

Last Updated: 2026-02-08