# How to Extend PrimeAgent's Functionality: 3 Ways to Customize the AI Agent Platform

> Learn how to extend PrimeAgent functionality with new model providers, custom skills, or core architecture modifications. Unlock advanced AI capabilities.

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

---

**You can extend PrimeAgent by adding new model providers, creating custom skills, or modifying core architecture components—each following a consistent registration pattern of implementing the interface, registering lazily, and updating type definitions.**

PrimeAgent is designed as a **modular, extensible platform** that cleanly separates the terminal UI, daemon-supervisor, session worker, and model-provider layer. Whether you need to integrate a new LLM, add domain-specific capabilities, or customize the runtime behavior, the codebase provides well-defined extension points. This guide walks through the three primary ways to extend PrimeAgent functionality based on the official source code.

## Add a New Model Provider

PrimeAgent's provider system lets you integrate any OpenAI-compatible or custom API by implementing a standard streaming interface.

### Implement the Provider Module

Create a new file in `packages/ai/src/providers/` that exports a `stream<Provider>()` function returning an `AssistantMessageEventStream`. The cleanest approach is to reuse existing helpers from [`packages/ai/src/providers/openai-completions.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/openai-completions.ts) if your API follows the OpenAI specification:

```typescript
// packages/ai/src/providers/myprovider.ts
import { AssistantMessageEventStream } from '../types';
import { streamOpenAI } from './openai-completions';

export interface MyProviderOptions {
  model: string;
  apiKey: string;
  // Add provider-specific options
}

export async function streamMyProvider(
  opts: MyProviderOptions,
): Promise<AssistantMessageEventStream> {
  // Re-use OpenAI streaming logic with custom endpoint
  return streamOpenAI({
    ...opts,
    baseUrl: 'https://api.myprovider.com/v1',
  });
}

```

### Register and Type the Provider

Update [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts) to lazy-load your provider:

```typescript
import { lazyProvider } from '../utils';

lazyProvider('my-provider', () => import('./myprovider'));

```

Then extend the type system in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts):

- Add your options type to `ApiOptionsMap`
- Add `'my-provider'` to the `KnownProvider` union

### Configure Credential Detection

Add automatic API key detection in [`packages/ai/src/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/env-api-keys.ts) following the Anthropic pattern:

```typescript
// Add to the provider registry
{
  provider: 'my-provider',
  envVar: 'MY_PROVIDER_API_KEY',
  // Optional: path to auth file
}

```

### Regenerate the Model Catalog

Run the generator script to populate your models in the provider matrix:

```bash
npx tsx packages/ai/scripts/generate-models.ts

```

## Create a New Skill

Skills are **discoverable plugins** that expose markdown instructions or Python-backed functionality to the agent.

### Set Up the Skill Directory

Create a directory in any skill location (e.g., `~/.prime/agent/skills/my-skill/` or inside the repo). The reference format is documented in [`packages/coding-agent/docs/skills.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/skills.md).

### Write the SKILL.md

Every skill requires a [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) with YAML front-matter:

```markdown
---
name: data-processor
description: Clean and transform CSV datasets
version: 1.0.0
---

## Usage

This skill provides data cleaning utilities...

### Available Commands

- `clean_csv(path)` - Remove null rows and standardize columns

```

### Build Python-Backed Skills

For executable functionality, add [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) and a Python module:

```

my-skill/
├── SKILL.md
├── pyproject.toml          # Marks as Python-backed

└── src/
    └── data_processor/
        └── __init__.py     # Exports async run() function

```

The runtime installs your package into the kernel virtual environment. Access it via:

```python

# Direct IPython kernel usage

await data_processor.clean_csv("/path/to/file.csv")

# Shell shortcut

!data_processor "/path/to/file.csv"

```

### Invoke Skills

Skills are discovered automatically at startup. Use them via:

- `/skill:data-processor` in the TUI
- Direct function calls from IPython
- The `!skill_name` shell syntax

## Modify Core Architecture

For deeper customization—altering the **daemon**, **scheduler**, or **RLM runtime**—work with the core TypeScript components.

### Understand the Data Flow

Per [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md), requests flow through:

**Interactive TUI** → `AgentConnection` → **Supervisor** → **Worker** → **AgentSessionRuntime** → **IPython Kernel**

### Key Extension Points

| Component | File Path | Purpose |
|-----------|-----------|---------|
| Model resolution | [`packages/agent/src/core/model-resolver.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/core/model-resolver.ts) | Default model selection logic |
| Provider labeling | [`packages/agent/src/core/provider-display-names.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/core/provider-display-names.ts) | UI display names |
| Protocol definitions | [`packages/ai/src/api-registry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/api-registry.ts) | Client-daemon message types |
| Protocol version | `DAEMON_PROTOCOL_VERSION` constant | Bump for breaking changes |

### Add New Commands or Events

When extending the daemon protocol:

1. Define messages in [`packages/ai/src/api-registry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/api-registry.ts)
2. Implement handlers in the supervisor/worker layer
3. **Bump `DAEMON_PROTOCOL_VERSION`** if the change is incompatible (documented in the "Daemon Protocol Changes" section of the development rules)

## Registration Pattern for All Extensions

Every extension type follows the same four-step flow:

1. **Define** — Implement the interface (provider stream, skill structure, or protocol message)
2. **Register** — Expose via lazy loader or auto-discovery
3. **Type** — Update `ApiOptionsMap`, `KnownProvider`, or protocol unions
4. **Document/Test** — Add usage examples and verify integration

This modular design ensures you can extend PrimeAgent functionality without touching unrelated subsystems.

## Summary

- **Model providers** require a `stream<Provider>()` function, lazy registration in [`register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/register-builtins.ts), type updates, credential detection, and catalog regeneration
- **Skills** need a [`SKILL.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/SKILL.md) with front-matter, optional Python packaging, and automatically integrate with the IPython kernel
- **Core architecture** modifications follow the TUI→Supervisor→Worker→Runtime→Kernel pipeline, with protocol versioning for breaking changes
- All extensions use consistent patterns: implement, register, type, and document

## Frequently Asked Questions

### Can I use a non-OpenAI API format for my provider?

Yes. While [`packages/ai/src/providers/openai-completions.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/openai-completions.ts) provides reusable helpers for OpenAI-compatible APIs, you can implement a fully custom `streamMyProvider()` that constructs the `AssistantMessageEventStream` directly. The only requirement is matching the return type defined in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts).

### Where should I place custom skills for development versus production?

During development, place skills in `~/.prime/agent/skills/` for automatic discovery without modifying the repository. For distribution, package skills within `packages/coding-agent/skills/` or publish as standalone repositories that users can clone into their skill directories.

### What happens if I forget to bump `DAEMON_PROTOCOL_VERSION`?

The daemon and client may enter a mismatched state where messages are silently dropped or parsed incorrectly. The development rules explicitly require version bumps for incompatible protocol changes to prevent subtle runtime failures. Version mismatches are detected at connection time with a clear error message.

### How do I debug a Python-backed skill installation?

Check the kernel logs for pip installation output. The runtime installs Python skills into an isolated venv, so import errors typically indicate missing dependencies in your [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml) or incorrect package structure. You can test installation manually by activating the kernel environment at `~/.prime/kernel/venv/` and running `pip install -e /path/to/your/skill`.