# How Python-Backed Skills Are Installed into Prime Agent's Kernel Venv: A Complete Technical Guide

> Learn how Python-backed skills install into Prime Agent's kernel venv using pip install -e. This technical guide explains the process for direct module import without subprocesses.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Prime Agent installs Python-backed skills as editable packages into a dedicated kernel virtual environment using `pip install -e`, making them directly importable as Python modules without spawning subprocesses.**

Prime Agent is an open-source coding agent framework that supports **Python-backed skills**—markdown-based skills that bundle a full Python package. Understanding how these skills integrate into the kernel's isolated environment is essential for contributors building custom capabilities or debugging dependency issues. This article examines the exact installation mechanism, key source files, and runtime behavior based on the PrimeIntellect-ai/prime-agent codebase.

## What Is the Kernel Venv?

The **kernel venv** is a dedicated Python virtual environment created and managed by Prime Agent's bootstrap system. By default, it resides at `~/.prime/agent/kernel-venv`, though this path is configurable via the `PRIME_AGENT_KERNEL_VENV` environment variable.

This isolation serves two purposes: it prevents skill dependencies from polluting the host Python environment, and it ensures reproducible, version-locked execution for agent operations.

## Kernel Venv Creation and Bootstrap Sequence

The bootstrap sequence in [`packages/coding-agent/src/core/kernel/bootstrap.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/kernel/bootstrap.ts) orchestrates the entire setup. The process unfolds in five distinct phases.

### 1. Venv Initialization

When the kernel starts, the bootstrap code creates the venv directory if absent or rebuilds it when stale. A content hash of the runtime source—including its own [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml)—is stored to detect changes that require reinstallation, as noted in [`packages/coding-agent/CHANGELOG.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/CHANGELOG.md).

### 2. Runtime Wheel Installation

The bundled `prime-agent-runtime` wheel is installed into the fresh venv first. This provides core infrastructure that skills depend upon without requiring them to declare it.

### 3. Skill Discovery

The skill loader in [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts) scans the `skills/` directory for markdown skills containing a [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) file. This marker distinguishes Python-backed skills from pure markdown or shell-based skills.

### 4. Editable Installation via `installPythonSkill`

For each discovered Python-backed skill, the bootstrap code executes an **editable install** using the `installPythonSkill` routine:

```python
import subprocess
import os
from pathlib import Path

kernel_venv = Path(
    os.getenv("PRIME_AGENT_KERNEL_VENV", "~/.prime/agent/kernel-venv")
).expanduser()

# Editable install of the skill package

skill_dir = Path("skills/my_skill")
subprocess.run(
    [kernel_venv / "bin" / "pip", "install", "-e", str(skill_dir)],
    check=True,
)

```

The `-e` (editable) flag creates a `.pth` file in the venv's `site-packages` rather than copying files, allowing live code edits without reinstallation.

### 5. Dependency Resolution

Dependencies listed in the skill's [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) are installed into the same venv. According to [`packages/coding-agent/skills/skill-creator/references/python-skills.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/skill-creator/references/python-skills.md), core runtime packages such as `rlm` and `tyro` are **pre-installed** and should not be listed as skill dependencies.

## Skill Package Structure Requirements

A valid Python-backed skill must follow this layout:

```

my_skill/
├── __init__.py          # Required: exposes `run()` function

├── pyproject.toml       # Required: package metadata and dependencies

└── README.md            # Optional: documentation

```

The skill loader in [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts) validates this structure and reports missing [`__init__.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/__init__.py) files as errors.

## Post-Installation Usage

After editable installation, the agent imports and invokes skills directly:

```python
import my_skill

# The skill is now a first-class Python module

result = my_skill.run(context, **arguments)

```

This direct import eliminates subprocess spawning overhead and enables tight integration with the agent's Python runtime.

## Dependency Isolation Strategy

Prime Agent employs a **layered dependency model**:

| Layer | Contents | Management |
|-------|----------|------------|
| Host Python | Prime Agent CLI, core orchestration | User's environment |
| Kernel venv | `prime-agent-runtime`, skill packages | Bootstrap installer |
| Per-skill deps | Third-party libraries from [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) | `pip` during skill install |

This design minimizes version conflicts while allowing skills to specify precise dependency ranges.

## Staleness Detection and Rebuilds

The bootstrap system tracks a **content hash** of the runtime source. When [`packages/coding-agent/src/core/kernel/bootstrap.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/kernel/bootstrap.ts) detects a mismatch—indicating runtime code or dependency changes—it automatically destroys and recreates the venv. This ensures skills always execute against compatible runtime versions.

## Summary

- **Kernel venv** is created at `~/.prime/agent/kernel-venv` by [`packages/coding-agent/src/core/kernel/bootstrap.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/kernel/bootstrap.ts)
- **Python-backed skills** are discovered via [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) and validated in [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts)
- **Editable installation** via `pip install -e` makes skills importable without file copying
- **Dependencies** from skill [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) are installed automatically; core runtime packages are pre-provided
- **Staleness detection** triggers venv rebuilds when runtime code changes

## Frequently Asked Questions

### Can I use a custom Python version for the kernel venv?

Prime Agent uses the same Python interpreter that runs the CLI to create the venv. The runtime wheel and skill packages must be compatible with this version. There is currently no mechanism to specify an alternative Python binary.

### Why does my skill fail with "No module named" errors after installation?

This typically indicates a missing [`__init__.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/__init__.py) or an improperly structured [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml). Verify that [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts) can locate your package and that editable installation completed without pip errors in the bootstrap logs.

### How do I force a rebuild of the kernel venv?

Delete the venv directory at `~/.prime/agent/kernel-venv` (or your custom `PRIME_AGENT_KERNEL_VENV` path) and restart the agent. The bootstrap sequence will detect the absence and recreate it, reinstalling all skills freshly.

### Can skills depend on each other?

Cross-skill dependencies are not officially supported. Each skill should be self-contained with its own [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) dependencies. Shared utility code should be contributed to the `prime-agent-runtime` or released as standalone packages installable via pip.