Plugin System
Relevant source files
The following files were used as context for generating this wiki page:
The Plugin System is a core architectural component of SkillKit designed to extend the platform's capabilities through modular extensions. It allows developers to integrate custom translators for AI agent formats, new git provider adapters, custom CLI commands, and event-driven lifecycle hooks. By decoupling these features from the core engine, the system enables a portable and highly customizable ecosystem for AI agent skills.
Sources: packages/core/README.md:20-30, packages/core/src/plugins/types.ts:105-117
Architecture Overview
The system is built on three primary pillars: discovery and loading, management and registration, and extension types.
Plugin Management Workflow
This diagram illustrates the lifecycle of a plugin from discovery on disk or npm to registration within the SkillKit engine.
Key Components
PluginLoader
The PluginLoader class is responsible for resolving plugin sources from local file systems (JS/MJS or JSON), npm packages, or directory scans. It ensures that plugins adhere to the required metadata structure and versioning before they are passed to the manager.
loadFromFile(filePath): Dynamically imports ES modules and validates the default or named export.loadFromPackage(packageName): Imports plugins directly from installed npm packages.scanDirectory(dirPath): Recursively searches forpackage.jsonorplugin.jsonmarkers in a given directory.
Sources: packages/core/src/plugins/loader.ts:18-112
PluginManager
The PluginManager acts as the central registry. It maintains maps of all active extensions and coordinates lifecycle events. It also persists the enabled/disabled state of plugins in a local plugins.json file.
| Feature | Description |
|---|---|
| Registry | Maps for plugins, translators, providers, commands, and hooks. |
| State Management | Tracks enabled status and configuration in .skillkit/plugins/plugins.json. |
| Lifecycle Control | Handles register, unregister, enable, and disable actions. |
| Hook Execution | Orchestrates the serial execution of asynchronous lifecycle hooks across all plugins. |
Sources: packages/core/src/plugins/manager.ts:25-50, packages/core/src/plugins/manager.ts:250-268
Extension Types
Plugins can provide one or more of the following extensions to the SkillKit environment:
1. Translator Extensions
Allows adding support for new AI coding agent formats by providing a FormatTranslator.
Sources: packages/core/src/plugins/types.ts:57-63
2. Provider Extensions
Enables new skill sources, such as Bitbucket or S3, by implementing the GitProviderAdapter.
Sources: packages/core/src/plugins/types.ts:68-74
3. Command Extensions
Integrates new subcommands into the SkillKit CLI, including support for custom aliases and options.
Sources: packages/core/src/plugins/types.ts:79-96
4. Lifecycle Hooks
Allows plugins to react to system events or transform data during the translation process.
Plugin Metadata and Validation
Every plugin must provide a metadata object. The system enforces strict validation on these fields to prevent path traversal and ensure compatibility.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique ID (lowercase alphanumeric with hyphens, allows scoped npm names). |
version | string | Yes | Semantic version (e.g., 1.0.0). |
dependencies | string[] | No | List of other plugin names required for this plugin to load. |
skillkitVersion | string | No | Semantic version range of SkillKit supported. |
Sources: packages/core/src/plugins/types.ts:13-33, packages/core/src/plugins/loader.ts:153-170
CLI Usage
The PluginCommand provides a user interface for managing the system from the terminal.
// Example: Registering a plugin via CLI
// From packages/cli/src/commands/plugin.ts:150-180
const plugin = await loadPlugin(resolvedSource);
await pluginManager.register(plugin);
Available Actions
list: Displays installed plugins, their versions, and enabled status.install --source <path|npm>: Copies local files to the internal plugin directory or registers an npm package.uninstall --name <name>: Removes plugin files and unregisters extensions.enable/disable --name <name>: Toggles plugin execution without removing files.
Sources: packages/cli/src/commands/plugin.ts:47-65, e2e/plugin-system.e2e.test.ts:28-115
Conclusion
The SkillKit Plugin System provides a robust framework for extensibility. By offering standardized interfaces for translators, providers, and CLI commands, it ensures that the platform can adapt to new AI agents and development workflows while maintaining a consistent core. The inclusion of event-driven hooks further allows for deep integration with automated processes like skill synchronization and project-wide transformations.
Sources: packages/core/README.md:95-103, packages/core/src/plugins/manager.ts:271-285