# Plugin Sdk

> Unified Plugin SDK for Claude Flow v3 with Worker, Hook, Provider, and MCP tool development

- Skill: `jrennie99-glitch/plugin-sdk` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jrennie99-glitch/plugin-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jrennie99-glitch/plugin-sdk/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jrennie99-glitch (https://skillmd.com/u/jrennie99-glitch)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/jrennie99-glitch/plugin-sdk

---


# Plugin SDK — Unified Plugin Development Framework

## Purpose

The `@claude-flow/plugins` module provides the unified Plugin SDK for Claude Flow v3, covering the full plugin development lifecycle including plugin registration, lifecycle management, Worker capabilities, Hook system, LLM provider integration, MCP tool development, security utilities, and RuVector integration for vector search and graph neural networks.

## Core Components

### Plugin Interface

Every plugin implements the `IPlugin` interface:

```typescript
interface IPlugin extends EventEmitter {
  readonly metadata: PluginMetadata;
  state: PluginLifecycleState;
  initialize(context: PluginContext): Promise<void>;
  shutdown(): Promise<void>;
  healthCheck(): Promise<HealthCheckResult>;

  // Optional extension points
  registerAgentTypes?(): AgentTypeDefinition[];
  registerTaskTypes?(): TaskTypeDefinition[];
  registerMCPTools?(): MCPToolDefinition[];
  registerCLICommands?(): CLICommandDefinition[];
  registerMemoryBackends?(): MemoryBackendFactory[];
  registerHooks?(): HookDefinition[];
  registerWorkers?(): WorkerDefinition[];
  registerProviders?(): LLMProviderDefinition[];
}
```

### Plugin Lifecycle States

`uninitialized` -> `initializing` -> `initialized` -> `shutting-down` -> `shutdown`

Error state: `error` (can occur from `initializing` or `initialized`)

### BasePlugin (Abstract Base Class)

```typescript
import { BasePlugin } from '@claude-flow/plugins';

class MyPlugin extends BasePlugin {
  constructor() {
    super({
      name: 'my-plugin',
      version: '1.0.0',
      description: 'My custom plugin',
      dependencies: ['other-plugin'],
    });
  }

  protected async onInitialize(): Promise<void> {
    this.logger.info('Plugin initialized');
  }

  protected async onShutdown(): Promise<void> {
    this.logger.info('Plugin shutting down');
  }

  protected async onHealthCheck(): Promise<Record<string, { healthy: boolean }>> {
    return { database: { healthy: true } };
  }

  registerMCPTools(): MCPToolDefinition[] {
    return [{
      name: 'my-tool',
      description: 'My custom tool',
      inputSchema: { type: 'object', properties: {} },
      handler: async (input) => ({
        content: [{ type: 'text', text: 'Hello!' }]
      })
    }];
  }
}
```

### Simple Plugin (Functional API)

```typescript
import { createSimplePlugin } from '@claude-flow/plugins';

const plugin = createSimplePlugin({
  name: 'simple-plugin',
  version: '1.0.0',
  onInit: async (ctx) => { /* ... */ },
  onShutdown: async () => { /* ... */ },
  mcpTools: [/* ... */],
  hooks: [/* ... */],
});
```

## Plugin Registry

```typescript
import { getDefaultRegistry, PluginRegistry } from '@claude-flow/plugins';

const registry = getDefaultRegistry();

// Register a plugin
await registry.register(myPlugin);

// Get registry stats
const stats = registry.getStats();
// { totalPlugins, initialized, errored, ... }
```

## PluginBuilder (Fluent API)

```typescript
import { PluginBuilder } from '@claude-flow/plugins';

const myPlugin = new PluginBuilder('my-plugin', '1.0.0')
  .withDescription('My awesome plugin')
  .withMCPTools([/* tool definitions */])
  .withHooks([/* hook definitions */])
  .withWorkers([/* worker definitions */])
  .build();
```

## Extension Points

### MCP Tools

```typescript
interface MCPToolDefinition {
  name: string;
  description: string;
  inputSchema: object;
  handler: (input: unknown) => Promise<{ content: ContentBlock[] }>;
}
```

### Hooks

```typescript
interface HookDefinition {
  event: string;           // e.g., 'pre-command', 'post-edit'
  priority: number;        // Execution order (lower = earlier)
  handler: (context: HookContext) => Promise<HookResult>;
}
```

### Workers

```typescript
interface WorkerDefinition {
  name: string;
  capabilities: string[];
  handler: (task: WorkerTask) => Promise<WorkerResult>;
}
```

### LLM Providers

```typescript
interface LLMProviderDefinition {
  name: string;
  models: string[];
  factory: (config: ProviderConfig) => ILLMProvider;
}
```

## RuVector Integration

Vector search, graph neural networks, and advanced ML integrations:

### Vector Bridge

```typescript
import { RuVectorBridge } from '@claude-flow/plugins';
// Connects plugins to RuVector for HNSW-indexed vector search
```

### Quantization

```typescript
import { Quantization } from '@claude-flow/plugins';
// Supports vector quantization for memory-efficient storage
```

### Streaming

```typescript
import { Streaming } from '@claude-flow/plugins';
// Streaming large data through vector pipelines
```

### Self-Learning

```typescript
import { SelfLearning } from '@claude-flow/plugins';
// Plugins that learn from usage patterns
```

### Graph Neural Networks

```typescript
import { GNN } from '@claude-flow/plugins';
// Graph-based reasoning over plugin interactions
```

### Attention Executor

```typescript
import { AttentionExecutor, AttentionAdvanced } from '@claude-flow/plugins';
// Attention-based execution routing and advanced attention mechanisms
```

### Hyperbolic Embeddings

```typescript
import { Hyperbolic } from '@claude-flow/plugins';
// Hyperbolic space embeddings for hierarchical data
```

## Security

```typescript
import { Security } from '@claude-flow/plugins';
// Plugin sandboxing, permission validation, input sanitization
```

## Agentic Flow Integration

```typescript
import { AgenticFlowIntegration } from '@claude-flow/plugins';
// Connects plugins to the agentic-flow optimization layer
```

## Example: RuVector Plugin Development

```typescript
// Reasoning Bank plugin
import { ReasoningBankPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// SONA Learning plugin
import { SonaLearningPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// Semantic Code Search plugin
import { SemanticCodeSearchPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// Intent Router plugin
import { IntentRouterPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// Hook Pattern Library plugin
import { HookPatternLibraryPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// MCP Tool Optimizer plugin
import { MCPToolOptimizerPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';
```

## Plugin Validation

```typescript
import { validatePlugin, validatePluginMetadata } from '@claude-flow/plugins';

const errors = validatePlugin(myPlugin);
const metadataErrors = validatePluginMetadata(myPlugin.metadata);
```

## Plugin Events

- `PLUGIN_EVENTS.INITIALIZED` — Plugin successfully initialized
- `PLUGIN_EVENTS.SHUTDOWN` — Plugin shutdown complete
- `PLUGIN_EVENTS.ERROR` — Plugin encountered an error
- `stateChange` — Plugin lifecycle state changed