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

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 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—is stored to detect changes that require reinstallation, as noted in 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 scans the skills/ directory for markdown skills containing a 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:

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 are installed into the same venv. According to 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 validates this structure and reports missing __init__.py files as errors.

Post-Installation Usage

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

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	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 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
• Python-backed skills are discovered via pyproject.toml and validated in packages/coding-agent/src/core/skills.ts
• Editable installation via pip install -e makes skills importable without file copying
• Dependencies from skill 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 or an improperly structured pyproject.toml. Verify that 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 dependencies. Shared utility code should be contributed to the prime-agent-runtime or released as standalone packages installable via pip.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}