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

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 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, installable package configuration in 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. 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 — Metadata and host request declarations
• pyproject.toml — Python package configuration
• src/<skill_name>/ — Python source files

Declare Skill Metadata in SKILL.md

The 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.

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 and module files containing your handlers. Each host request handler must be an async function accepting exactly two arguments: payload: dict and context: dict.

# 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:

[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 and locate the HostRequestMap interface. Add your new request type with strict payload and response definitions:

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:

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

pyproject.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:

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):

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

Invocation from Agent:

After starting Prime Agent (./prime-agent.sh), trigger the skill with /skill:demo-skill, then execute:

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 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, 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.
• 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. 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 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, the agent executes pip install -e . into the shared virtual environment. The metadata in 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, restart Prime Agent to reload the skill package and re-parse the metadata definitions.

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