#9925: docs: warn about Python venv placement in skill directories
docs
stale
Cluster:
Skill Enhancements and Fixes
## 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
#9595: fix(skills): ignore .venv, __pycache__, and .openclaw to prevent FD...
by amoghacloud · 2026-02-05
82.0%
#8873: fix: document skill loading locations in system prompt
by ytfh44 · 2026-02-04
82.0%
#3933: fix(skills): Make skill scripts executable
by jaysonsantos · 2026-01-29
79.9%
#8291: Fix: Add Python virtual environment ignore patterns to skills watcher
by vishaltandale00 · 2026-02-03
79.3%
#12076: fix(skills): recursive directory filtering to actually exclude venv...
by xiaoyaner0201 · 2026-02-08
79.0%
#19664: fix(skills): log skill YAML parsing diagnostics with skill name
by orchidsun · 2026-02-18
78.7%
#10016: fix: prevent FD exhaustion from skill watcher scanning artifact trees
by oldeucryptoboi · 2026-02-06
78.6%
#6777: fix(skills): ignore Python venvs and caches in skills watcher
by kirkluokun · 2026-02-02
77.8%
#22306: Warn on malformed skill parsing failures in load path
by AIflow-Labs · 2026-02-21
77.1%
#14023: fix: filter skills watcher to relevant file types to prevent FD exh...
by funmerlin · 2026-02-11
76.9%