Soubi

Soubi is a filesystem-first framework for portable coding-agent plugins. Author one inspectable directory of instructions, skills, commands, agents, hooks, tools, and companion files; Soubi compiles it into the native artifact each supported harness expects.

The filesystem is the authoring interface

A Soubi plugin can be as small as one AGENTS.md file and grows through conventional directories:

my-plugin/
├── AGENTS.md               # Always-on plugin instructions
├── plugin.config.ts        # Optional identity and target configuration
├── skills/                 # Reusable procedures loaded on demand
│   └── review/
│       └── SKILL.md
├── commands/               # User-invoked workflows
│   └── commit.ts
├── agents/                 # Specialist agent definitions
│   └── reviewer.ts
├── hooks/                  # Lifecycle behavior
│   └── pre-tool-use.ts
├── tools.ts                # Executable tools
├── assets/                 # Companion files
└── scripts/                # Supporting programs

Read the documentation for the full project layout, harness matrix, and guides.

Quick start

npx soubi@latest init my-plugin

This creates a new my-plugin directory, installs its dependencies, and initializes Git when appropriate.

To add Soubi to an existing project, pass its path:

cd my-project
npx soubi@latest init .

Soubi preserves existing project files and scripts. Its commands remain available as soubi:check, soubi:build, and soubi:dev.

A minimal example

Replace the generated AGENTS.md with:

# Plugin instructions

Review every change for correctness, security, and maintainability.

Add an optional skill at skills/review/SKILL.md:

---
name: review
description: Review a change for correctness and maintainability
---

Inspect the relevant changes and report concrete findings with file references.

Then validate and build the plugin:

npm run check
npm run build

Soubi writes ordinary manifests, Markdown, configuration, scripts, and extensions to .soubi-out/<harness>/. There is no compatibility runtime between the harness and the generated plugin.

Build only the targets you are testing:

npx soubi build . --harness claude,codex,opencode

That is a portable plugin. Add commands, specialist agents, hooks, MCP servers, executable tools, and companion assets as needed. Follow the quickstart for a complete walkthrough.

Supported harnesses

Soubi currently compiles native artifacts for twenty-two coding-agent harnesses:

Harness	Target	Native output
Claude Code	claude	Plugin manifest, skills, agents, commands, hooks, and MCP
Codex CLI	codex	Plugin metadata, Agent Skills, TOML agents, prompts, and hooks
Gemini CLI	gemini	Gemini extension with commands, agents, hooks, and MCP servers
OpenCode	opencode	Native Markdown surfaces and a generated TypeScript plugin
Cursor	cursor	Marketplace manifest, rules, skills, commands, subagents, hooks, and MCP
GitHub Copilot	copilot	Skills, prompts, custom agents, hooks, and VS Code MCP config
Windsurf	windsurf	AGENTS.md, Agent Skills, workflows, and global MCP config
Pi	pi	Pi package with prompt templates and a generated extension
Hermes Agent	hermes	Python plugin with bundled skills, commands, hooks, and tools
Kiro CLI	kiro	Steering, skills, prompts, agents, v1 hooks, and MCP settings
Amp	amp	Agent Skills and a generated Amp TypeScript plugin
Factory Droid	droid	Factory plugin bundle with skills, commands, droids, and hooks
OMP	omp	OMP package with prompts, skills, tools, and lifecycle callbacks
Devin CLI	devin	Devin plugin with agents, skills, hooks, and MCP
Kimi Code CLI	kimi	Plugin manifest containing commands, hooks, MCP, and skill instructions
Qoder CLI	qoder	Project instructions, skills, commands, agents, hooks, and MCP
Kilo Code CLI	kilo	Kilo-native paths backed by its OpenCode-compatible plugin contract
MastraCode	mastracode	Project skills, commands, hooks, MCP, and specialist-agent fallbacks
Grok CLI	grok	Grok plugin with skills, agents, hooks, and MCP
Antigravity CLI	antigravity	Plugin rules, skills, hooks, MCP, and workspace agents
Maki	maki	Generated Lua plugin and native Maki MCP configuration
Herdr	herdr	Multiplexer actions for readable plugin content with explicit runtime drops

See Harness support for native paths and the feature-by-feature support matrix.

Community

The Soubi community lives on GitHub, where you can report bugs, request features, and share ideas.

Contributing

Contributions are welcome. See DEVELOPMENT.md to run the repository locally and CONTRIBUTING.md for the contribution workflow. By participating, you agree to the Code of Conduct.

Security

Please do not open public issues for security vulnerabilities. Follow SECURITY.md and report them privately through GitHub Security Advisories.

License

Soubi is available under the Apache License 2.0.