# How to Create Custom Python-Backed Skills with Typed Host Requests for Prime Agent

> Learn to build custom Python skills for Prime Agent using typed host requests. Enable type-safe communication between your skills and the agent by defining metadata, implementing handlers, and mapping requests.

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

---

**Define a skill folder with SKILL.md metadata, implement async Python handlers accepting `payload` and `context` dictionaries, and register the request/response types in the `HostRequestMap` interface located in [`packages/coding-agent/src/core/tools/ipython.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/tools/ipython.ts) to enable type-safe communication between the IPython kernel and the Prime Agent host.**

Prime Agent from PrimeIntellect-ai/prime-agent extends conversational AI with executable **skills**—reusable Python packages that expose command-line-style tools through slash commands. When these skills need to manipulate the agent's internal state, trigger background tasks, or query the goal tree, they communicate via **typed host requests**, a JSON-RPC mechanism that bridges the IPython kernel and the TypeScript host with compile-time type safety. This guide demonstrates how to author, register, and invoke custom Python-backed skills using the architecture found in the Prime Agent source code.

## What Are Prime Agent Skills and Typed Host Requests?

A **skill** in Prime Agent is a self-contained Python package residing in `packages/coding-agent/skills/<skill-name>/`. Each skill contains declarative metadata in [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md), installable package configuration in [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml), and executable logic in the `src/` directory. The agent auto-discovers these skills at startup and exposes them as slash commands (e.g., `/skill:websearch`).

**Typed host requests** enable bidirectional communication between the Python kernel and the Node.js host. When Python code calls `await host_request("type", {...})`, the kernel serializes the payload to the `IPythonTool` class in [`packages/coding-agent/src/core/tools/ipython.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/tools/ipython.ts). The `HostRequestMap` interface validates request shapes at compile time, while the generic dispatcher (`this.hostRequests.dispatch`) routes messages to the appropriate Python handler and returns validated responses.

## Step-by-Step Implementation Guide

### Initialize the Skill Structure

Create a new directory under `packages/coding-agent/skills/`. Bootstrap this by copying an existing skill like `websearch` or using the built-in `skill-creator` template. The directory must contain:

- [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) — Metadata and host request declarations
- [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) — Python package configuration
- `src/<skill_name>/` — Python source files

### Declare Skill Metadata in SKILL.md

The [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) file acts as the skill's manifest. Define the skill's name, description, and explicitly list any host request types it consumes under a `host-requests:` section.

```markdown
name: demo-skill
description: Demonstrates typed host request handling.
host-requests:
  - demo.echo

```

The agent parses this file to register the slash command `/skill:demo-skill` and to generate help documentation.

### Implement Python Logic

Inside `src/demo_skill/`, create an [`__init__.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/__init__.py) and module files containing your handlers. Each host request handler must be an **async function** accepting exactly two arguments: `payload: dict` and `context: dict`.

```python

# src/demo_skill/echo.py

async def echo(payload: dict, context: dict) -> dict:
    """
    Handler for the demo.echo host request.
    
    Args:
        payload: Dictionary containing request-specific data.
        context: Execution context with metadata about the session.
    
    Returns:
        Dictionary matching the TypeScript response type.
    """
    message = payload.get("message", "")
    return {"status": "ok", "echo": message}

```

Import heavy dependencies inside the handler functions rather than at module level to minimize kernel startup time, since skills are pre-imported when the IPython kernel initializes.

### Configure pyproject.toml for Installation

Create a minimal Poetry configuration to enable the agent to install your skill into the shared virtual environment:

```toml
[tool.poetry]
name = "demo-skill"
version = "0.1.0"
description = "Demo skill for Prime Agent"
authors = ["Your Name <you@example.com>"]

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

```

The agent automatically runs `pip install -e .` on skill directories at startup.

### Register Typed Host Requests in TypeScript

Open [`packages/coding-agent/src/core/tools/ipython.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/tools/ipython.ts) and locate the `HostRequestMap` interface. Add your new request type with strict payload and response definitions:

```typescript
export interface HostRequestMap {
  // Existing entries...
  "demo.echo": {
    payload: { message: string };
    response: { status: "ok" | "error"; echo?: string };
  };
}

```

The `IPythonTool` class uses this interface to validate requests. Once defined, the generic dispatcher automatically routes matching requests to your Python handler without additional bridge code.

## Complete Working Example

Here is a minimal but complete implementation of a `demo-skill` that echoes messages back through a typed host request.

**Directory Structure:**

```

packages/coding-agent/skills/demo-skill/
├── SKILL.md
├── pyproject.toml
└── src/
    └── demo_skill/
        ├── __init__.py
        └── echo.py

```

**SKILL.md:**

```markdown
name: demo-skill
description: Echoes messages via typed host request.
host-requests:
  - demo.echo

```

**pyproject.toml:**

```toml
[tool.poetry]
name = "demo-skill"
version = "0.1.0"
description = "Demo skill for Prime Agent"
authors = ["Developer <dev@example.com>"]

```

**src/demo_skill/echo.py:**

```python
async def echo(payload: dict, context: dict) -> dict:
    """Handle demo.echo host request."""
    return {
        "status": "ok", 
        "echo": payload.get("message", "")
    }

```

**TypeScript Registration (in ipython.ts):**

```typescript
export interface HostRequestMap {
  "demo.echo": {
    payload: { message: string };
    response: { status: "ok" | "error"; echo?: string };
  };
}

```

**Invocation from Agent:**

After starting Prime Agent ([`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh)), trigger the skill with `/skill:demo-skill`, then execute:

```python
await host_request("demo.echo", {"message": "Hello from Prime Agent!"})

# Returns: {'status': 'ok', 'echo': 'Hello from Prime Agent!'}

```

## Testing Your Custom Skill

Create integration tests under `packages/coding-agent/test/suite/` using the provided `FakeKernel` utilities to avoid spawning real IPython kernels. Reference existing tests like [`agent-session-goal.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session-goal.test.ts) for patterns on mocking host requests and asserting response shapes. This validates that your TypeScript definitions align with your Python implementations before deployment.

## Summary

- **Skills** reside in `packages/coding-agent/skills/<name>/` and require [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md), [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml), and Python source files.
- **Typed host requests** provide type-safe communication between the IPython kernel and host via the `HostRequestMap` interface in [`ipython.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/ipython.ts).
- Python handlers must be **async functions** accepting `payload: dict` and `context: dict` parameters.
- Register new request types in the TypeScript `HostRequestMap` to enable compile-time validation and automatic dispatch via `this.hostRequests.dispatch`.
- Use the `FakeKernel` test utilities to validate skill behavior without full kernel initialization.

## Frequently Asked Questions

### What happens if the TypeScript and Python type definitions mismatch?

Prime Agent validates host request shapes at runtime according to the definitions in [`src/core/kernel/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/kernel/index.ts). If the Python function returns a dictionary missing required fields defined in the TypeScript `HostRequestMap` response type, the dispatcher will throw a validation error. Keep the TypeScript interface and Python return values synchronized to prevent runtime failures during skill execution.

### Can I use synchronous Python functions for host request handlers?

No. All host request handlers must be declared with the `async` keyword. The `IPythonTool` class in [`packages/coding-agent/src/core/tools/ipython.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/tools/ipython.ts) awaits these coroutines to prevent blocking the kernel's event loop during I/O operations or long-running computations.

### How does the agent discover and install new skills?

Prime Agent scans the `packages/coding-agent/skills/` directory at startup. For each skill containing a valid [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml), the agent executes `pip install -e .` into the shared virtual environment. The metadata in [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) is parsed to register slash commands and validate declared host request permissions.

### Do I need to restart the agent after modifying skill code?

Yes. While the agent hot-reloads some components, Python skill code is pre-imported into the IPython kernel at session start. After modifying Python source files or [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md), restart Prime Agent to reload the skill package and re-parse the metadata definitions.