← Back to PRs

#9925: docs: warn about Python venv placement in skill directories

by kj9kj9qv4m-bit open 2026-02-05 21:57 View on GitHub →
docs stale
## Problem The skill scanner recursively opens all files in the skills directory. When Python virtual environments are placed inside skill folders, thousands of files get opened (pandas/numpy tests, bytecode cache, etc.), causing file descriptor exhaustion and exec tool failure. ## Solution This PR adds a clear warning to the skill creation documentation about: - ⚠️ Do NOT place venv/ directories inside skills - ✅ Store venvs in `~/.openclaw/venvs/` instead - Lists other directories to avoid: `.venv/`, `__pycache__/`, `.git/` ## Context Closes #9921 ### Background During debugging, we discovered that a fresh OpenClaw gateway was opening 14,472 file descriptors on startup because it was scanning Python venvs with pandas/numpy installed. Moving venvs outside the skills directory reduced FD count by 91% (14,472 → 1,247) and restored exec functionality. ### Long-term fix The underlying issue is in the `@mariozechner/pi-coding-agent` library's `loadSkillsFromDir` function, which already excludes `node_modules` but not Python venvs. That library should be updated to skip common development directories, but this documentation change helps users avoid the issue immediately. <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> Adds an “Important Gotchas” section to the skill creation docs warning users not to put Python virtual environments (and other large dev directories like `__pycache__` and `.git`) inside skill folders, and provides an example of creating venvs under `~/.openclaw/venvs/` to avoid file-descriptor exhaustion during skill scanning. <h3>Confidence Score: 4/5</h3> - Safe to merge; docs-only change with a minor docs-linking convention issue. - Change is confined to a single documentation file and does not affect runtime behavior. Only concern is adherence to the repo’s Mintlify/internal-linking guidelines for GitHub URLs. - docs/tools/creating-skills.md <!-- greptile_other_comments_section --> <sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub> **Context used:** - Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13)) <!-- /greptile_comment -->

Most Similar PRs