What is manifest.json used for?

manifest.json provides plugin metadata (name, version) and the entry point (main) that the loader imports to instantiate the plugin.

How does the loader know which plugins to load?

The loader scans configured pluginDirs for subdirectories containing manifest.json, validating required fields before loading.

What happens if a plugin fails to load?

Loading errors can be caught and handled to prevent the host from crashing; validate fields before import and consider isolating plugin loads.

plugin-loader-generator

npx machina-cli add skill a5c-ai/babysitter/plugin-loader-generator --openclaw

Files (1)

SKILL.md

1.8 KB

Plugin Loader Generator

Generate dynamic plugin loading system.

Generated Patterns

import fs from 'fs';
import path from 'path';

interface Plugin {
  name: string;
  version: string;
  init: () => Promise<void>;
  destroy?: () => Promise<void>;
}

export class PluginLoader {
  private plugins = new Map<string, Plugin>();
  private pluginDirs: string[];

  constructor(pluginDirs: string[]) {
    this.pluginDirs = pluginDirs;
  }

  async discover(): Promise<string[]> {
    const found: string[] = [];
    for (const dir of this.pluginDirs) {
      if (!fs.existsSync(dir)) continue;
      const entries = fs.readdirSync(dir, { withFileTypes: true });
      for (const entry of entries) {
        if (entry.isDirectory()) {
          const manifestPath = path.join(dir, entry.name, 'manifest.json');
          if (fs.existsSync(manifestPath)) {
            found.push(path.join(dir, entry.name));
          }
        }
      }
    }
    return found;
  }

  async load(pluginPath: string): Promise<Plugin> {
    const manifest = JSON.parse(fs.readFileSync(path.join(pluginPath, 'manifest.json'), 'utf-8'));
    const module = await import(path.join(pluginPath, manifest.main));
    const plugin: Plugin = { name: manifest.name, version: manifest.version, ...module };
    await plugin.init();
    this.plugins.set(plugin.name, plugin);
    return plugin;
  }

  async unload(name: string): Promise<void> {
    const plugin = this.plugins.get(name);
    if (plugin?.destroy) await plugin.destroy();
    this.plugins.delete(name);
  }
}

Target Processes

plugin-architecture-implementation
cli-application-bootstrap

Source

git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/cli-mcp-development/skills/plugin-loader-generator/SKILL.md

View on GitHub

Overview

Generates a TypeScript-based plugin loader. It automatically discovers plugins in configured directories using manifest.json, validates essential metadata, loads them via dynamic import, and manages their lifecycle with init and an optional destroy.

How This Skill Works

The loader scans pluginDirs for subfolders containing manifest.json, validates required fields, then imports the plugin's main module as declared in the manifest, constructs a Plugin instance, calls init, and stores it for lifecycle management. It can unload a plugin by invoking destroy if present and removing it from its internal map.

When to Use It

Build a CLI or service that supports third-party plugins discovered from one or more directories.
Support auto-discovery of plugins deployed as separate packages with their own manifest.json.
Need to initialize plugins on startup and cleanly shut them down on exit.
Require a predictable Plugin interface (name, version, init, optional destroy) across plugins.
Isolate plugin loading to avoid cascading failures by loading individually and validating manifest before import.

Quick Start

Step 1: Create a PluginLoader with your plugin directories, e.g., new PluginLoader(['plugins']);
Step 2: Call discover() to find plugin paths, then for each path call load(path) to initialize plugins.
Step 3: On shutdown or reload, call unload(name) for each plugin you want to stop.

Best Practices

Publish a manifest.json with required fields: name, version, and main entry to guide discovery and loading.
Validate manifest fields and ensure the plugin module exports align with the Plugin interface before calling init.
Wrap load/unload in try/catch and isolate plugin failures to avoid crashing the host.
Keep pluginDirs configurable and restrict loading to trusted paths to prevent tampering.
Provide a clear destroy path so plugins can release resources during unload.

Example Use Cases

A CLI tool that adds new subcommands by placing each command as a plugin directory with its own manifest.json.
A data processing app that loads parsers or transformers as plugins from a plugins directory.
A task runner that discovers plugins implementing additional tasks via a manifest-backed main module.
A microservice that loads protocol handlers or adapters as plugins scanned from a well-known plugins folder.
An extensible tooling platform where plugins can be added or removed without rebuilding the host.

Frequently Asked Questions

Add this skill to your agents