The framework for building agent plugins
Like Next.js for agent plugins. Build portable plugins with one folder.
npx soubi@latest init my-pluginYour plugin/ is a directory
An AGENTS.md file is all you need to begin. Skills, commands, agents, hooks, and tools are optional building blocks you add as the plugin grows.
An AGENTS.md file is a complete plugin. Write the instructions in Markdown, then build with Soubi.
# Plugin instructions
Review every change for correctness,
security, and maintainability.Add plugin.config.ts when you want typed identity, defaults, or harness-specific configuration.
import { defineConfig } from "soubi";
export default defineConfig({
id: "my-plugin",
version: "1.0.0",
});Skills are focused Markdown playbooks that stay beside their references, scripts, and supporting files.
---
name: review
description: Review a patch
---
Inspect the diff, run focused checks,
and report findings by severity.Typed commands become native prompts, workflows, or slash commands in each target harness.
import { defineCommand } from "soubi";
export default defineCommand({
name: "commit",
description: "Prepare a clean commit",
instructions: "Review $ARGUMENTS",
});Specialist agents compile to native subagent formats wherever the harness supports them.
import { defineAgent } from "soubi";
export default defineAgent({
name: "reviewer",
description: "Review pull requests",
instructions: "Find real defects.",
});Lifecycle hooks become declarative configuration, callbacks, extensions, or explicit fallbacks.
import { defineHook } from "soubi";
export default defineHook({
event: "PreToolUse",
handler: {
type: "command",
command: "./scripts/check.sh",
},
});Executable tools become native extensions or dependency-light MCP servers.
import { defineTools } from "soubi";
export default defineTools([{
name: "inspect_diff",
description: "Read the current diff",
inputSchema: { type: "object" },
execute: () => "ready",
}]);Native artifacts, yours to inspect.
Soubi compiles your source into every target’s own files. There is no compatibility runtime between the harness and your plugin.
import { defineConfig } from "soubi";
export default defineConfig({
id: "my-plugin",
version: "1.0.0",
});claude/.claude-plugin/
codex/.codex-plugin/
gemini/gemini-extension.json
opencode/opencode.json
cursor/.cursor/
copilot/.github/
windsurf/.windsurf/
pi/extension.ts
kiro/.kiro/
amp/.amp/plugins/
droid/.factory-plugin/Everything you need for production agent plugins.
Start with one instruction file, then add capabilities only when your plugin needs them.
- Skills
Markdown playbooks stay focused, portable, and close to their supporting files.
- Native output
Every target receives the manifests, directories, and configuration it loads directly.
- Commands & agents
Commands and specialist agents map to each harness’s first-class interaction model.
- Hooks & tools
Hooks and tools become native configuration, callbacks, extensions, or MCP servers.
- Companion assets
References, scripts, and configuration files travel with the features that use them.
- Honest fallbacks
Explicit fallback tiers reveal every lossy mapping and isolate incompatible targets.