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

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 if your API follows the OpenAI specification:

// 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 to lazy-load your provider:

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

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

Then extend the type system in 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 following the Anthropic pattern:

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

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.

Write the SKILL.md

Every skill requires a SKILL.md with YAML front-matter:

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

# 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, 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	Default model selection logic
Provider labeling	packages/agent/src/core/provider-display-names.ts	UI display names
Protocol definitions	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
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, type updates, credential detection, and catalog regeneration
• Skills need a 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 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.

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

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