ARCANA
Back to Blog

Guide

Plugins: Extending Arcana Beyond Tools and Skills

May 20, 2026 Guide

Skills teach the agent new behaviors. Plugins modify Arcana itself. Where skills are about what the agent knows, plugins are about how the agent works.

The distinction is architectural, not just semantic. Skills are data: Markdown files that the agent reads and follows. They are interpreted at runtime, loaded on demand, and garbage-collected when no longer needed. Plugins are code: JavaScript modules that execute in Arcana's runtime. They are loaded at startup, persist for the session, and can modify any part of the system.

This means skills are safe, portable, and easy to share. Plugins are powerful, system-level, and require more care. The right tool depends on what you are trying to do.

Skills vs. Plugins

The distinction matters:

  • Skills are Markdown instruction files. They load on demand and teach the agent a specific behavior. They are lightweight, portable, and easy to write.
  • Plugins are code. They modify Arcana's runtime: adding new providers, changing how the TUI renders, hooking into the session lifecycle, or adding new slash commands.

Plugin Architecture

Plugins are loaded at startup. Each plugin can:

  • Register new slash commands
  • Add custom providers
  • Modify the TUI layout
  • Hook into session lifecycle events (start, end, compaction)
  • Add new tool types
  • Modify the permission system

Writing a Plugin

Arcana plugins are Node.js modules. They work identically on Linux, macOS, and Windows. The plugin API is documented and includes TypeScript types:

Plugin files are stored in your Arcana home directory:

  • Linux / macOS: ~/.arcana/plugins/
  • Windows: %USERPROFILE%\.arcana\plugins\
// my-plugin/index.js
module.exports = {
  name: 'my-plugin',
  version: '1.0.0',
  
  register(arcana) {
    // Add a slash command
    arcana.command('greet', (args) => {
      return 'Hello, ' + (args.name || 'world');
    });
    
    // Hook into session start
    arcana.on('session:start', (session) => {
      console.log('Session started:', session.id);
    });
  }
};

Plugin Guide

Arcana includes a comprehensive plugin guide that walks through:

  • Plugin lifecycle and loading order
  • API reference for all hook points
  • Examples: custom providers, TUI modifications, workflow integrations
  • Testing plugins in isolation
  • Distributing plugins via npm or git

When to Use Plugins

Most users never need plugins. Skills and configuration handle the vast majority of customization. Plugins are for when you need to change Arcana's behavior at a level that skills cannot reach: custom providers, deep TUI customization, or integration with internal systems.

Here is a decision framework:

  • Use skills when you want to teach the agent a new behavior, change its output format, or add domain-specific knowledge.
  • Use configuration when you want to change defaults, add API keys, or adjust runtime parameters.
  • Use MCP servers when you want to add new tools that the agent can call.
  • Use plugins when you want to modify Arcana's internal behavior: add a new provider, change how the TUI renders, hook into session lifecycle, or integrate with internal systems that require deep runtime access.

The progression from skills to plugins is a progression from simple to complex. Start with skills. Graduate to plugins only when you have a clear need that skills cannot address.

Related Reading