openhuman/.claude/skills-system-troubleshooting.md

Skills System Troubleshooting Guide

Overview

The Skills System is a Python-based plugin architecture that allows AI agents to have domain-specific knowledge, tools, and automated behaviors. Skills run as isolated Python subprocesses and communicate with the main Tauri application via JSON-RPC.

Common Issue: "Setup Failed" with Exit Code 1

Symptoms

• Skills modal shows "Setup Failed" with "Skill process exited with code: 1"
• Console shows ModuleNotFoundError: No module named 'pydantic'
• Error paths like /Users/cyrus/openhuman/skills/skills/telegram/
• Python import failures and subprocess stderr messages

Root Cause Analysis

Primary Issue: Missing Skills Git Submodule The main cause is that the skills Git submodule is not initialized. The system expects skills to be available in the skills/skills/ directory structure but finds an empty directory.

Secondary Issues:

1. Missing Python Virtual Environment: No .venv directory in the skills folder
2. Missing Python Dependencies: Core packages like pydantic, telethon, mcp not installed
3. Incorrect Python Paths: PYTHONPATH configuration issues

Skills System Architecture

skills/                          # Git submodule root
├── .venv/                       # Python virtual environment
├── requirements.txt             # Shared dependencies
├── skills/                      # Individual skill packages
│   ├── telegram/               # Telegram skill
│   │   ├── skill.py           # Main skill logic
│   │   ├── manifest.json      # Skill metadata
│   │   ├── requirements.txt   # Skill-specific dependencies
│   │   └── ...
│   ├── browser/               # Browser automation skill
│   ├── calendar/              # Calendar integration skill
│   └── ...                    # Other skills
└── ...

Solution Steps

1. Initialize Git Submodule

git submodule init
git submodule update

This downloads the skills repository from https://github.com/openhumanxyz/skills.

2. Create Python Virtual Environment

cd skills
python3 -m venv .venv
.venv/bin/pip install --upgrade pip

3. Install Dependencies

.venv/bin/pip install -r requirements.txt

This installs:

• Core Dependencies: mcp>=1.0.0, pydantic>=2.0, aiosqlite>=0.20.0
• Skill-Specific Dependencies: Each skill's requirements.txt (telegram, browser, etc.)

4. Verify Installation

# Test core imports
.venv/bin/python -c "import pydantic, mcp; print('✅ Core dependencies OK')"

# Test skill import
.venv/bin/python -c "import skills.telegram; print('✅ Telegram skill OK')"

How Skills System Works

Development vs Production Paths

• Development: Skills in git submodule at ./skills/skills/
• Production: Skills in ~/.openhuman/skills/
• Configuration: src/lib/skills/paths.ts handles path resolution

Skill Execution Process

1. Discovery: SkillProvider scans for skill manifests
2. Registration: Skills registered in Redux store
3. Startup: Python subprocess spawned with proper environment
4. Communication: JSON-RPC transport over stdin/stdout
5. Setup: Interactive setup flow if required

Environment Variables

The system automatically configures:

• PYTHONPATH: Includes skills directory and virtual environment
• Telegram API: TELEGRAM_API_ID, TELEGRAM_API_HASH
• Working Directory: Skills submodule root

Verification Commands

# Check submodule status
git submodule status

# Verify skills directory structure
ls -la skills/skills/telegram/

# Check virtual environment
ls -la skills/.venv/

# Test Python environment
cd skills && .venv/bin/python -c "import sys; print('\\n'.join(sys.path))"

Prevention

To prevent this issue in fresh checkouts:

1. Always initialize submodules:

   git clone --recurse-submodules <repo-url>
   # or after clone:
   git submodule update --init --recursive
   

2. Setup script: Consider adding to package.json:

   {
     "scripts": {
       "setup": "git submodule update --init && cd skills && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt"
     }
   }
   

Related Files

• Frontend: src/lib/skills/ - Skills management system
• Backend: src-tauri/src/commands/skills.rs - Rust skill commands
• Configuration: src/utils/config.ts - Environment variables
• Providers: src/providers/SkillProvider.tsx - Skills lifecycle

Expected Behavior After Fix

1. Skills modal should show "Connect Telegram" instead of error
2. No more Python import errors in console
3. Skill setup process should work correctly
4. Background GitHub sync should function properly

This fix resolves the fundamental infrastructure issue preventing skills from loading and running properly.