Runtime helpers for agent skills, RAFA-original internals. The core tool is venv-manager.sh: one uv-managed virtualenv per skill.
Attribution: this repository is not a fork. It exists so Python-heavy skills under ~/.agents/skills/ do not share a fragile global interpreter.
Suite hub:opencode-methodology → Install from scratch.
- Install OpenCode and
uv(UV_BINoptional). - Clone and install the helper into the OpenCode config tree:
git clone https://github.com/openrafa/opencode-skill-runtime.git
mkdir -p ~/.config/opencode/.scripts
cp opencode-skill-runtime/bin/venv-manager.sh \
~/.config/opencode/.scripts/venv-manager.sh- Create / check / rewire a skill venv:
bash ~/.config/opencode/.scripts/venv-manager.sh create <skill-name><package>...
bash ~/.config/opencode/.scripts/venv-manager.sh doctor <skill-name>
bash ~/.config/opencode/.scripts/venv-manager.sh rewire <skill-name>- Use the skill in OpenCode as usual. Re-run
doctorif imports fail.
~/.config/opencode/
├── .scripts/
│ └── venv-manager.sh
└── .venvs/ # generated local state, gitignored by you
└── <skill-name>/
Defaults: VENV_ROOT=~/.config/opencode/.venvs, SKILL_ROOT=~/.agents/skills. Wiki workflows keep helper scripts in the vault's local .scripts/ directory — copy venv-manager.sh there as well if you use wiki skills. See docs/python-isolation.md (中文).
Global site-packages make skills conflict and failures hard to diagnose. One venv per skill + a generated wrapper keeps isolation reversible.
| Topic | English | 中文 |
|---|---|---|
| Python isolation | python-isolation.md | python-isolation.zh-CN.md |
| Author guidelines | skill-author-guidelines.md | skill-author-guidelines.zh-CN.md |
| Troubleshooting | troubleshooting.md | troubleshooting.zh-CN.md |
- Example of a Python-heavy skill name, not bundled:
examples/kami.md - Wiki skills that may need isolation: opencode-obsidian-wiki
MIT — Copyright (c) 2026 Cyame. See LICENSE.
This runtime helper is written for this suite.