Introduction
Soubi is a file-based framework for authoring an agent-harness plugin once and compiling it to every harness's native artifact format.
Soubi reads one file-based plugin and writes a native artifact tree for each selected harness. Plugin source is ordinary TypeScript, Markdown, and supporting files. Generated output does not require a Soubi runtime.
What the compiler handles
Harnesses disagree on directories, frontmatter, hook events, MCP configuration, and agent formats. Soubi keeps those differences in adapters and reports any translation that changes behavior.
The compiler preserves these guarantees:
File-based authoring
Drop a SKILL.md on disk and it's registered — no manual wiring. Inline
strings and file() references work too.
Ship assets, not just text
Reference docs, JSON configs, and scripts travel with your skills to every harness that supports skill-adjacent files.
Open frontmatter
Unknown frontmatter fields pass through, so harness-specific or newly-added fields aren't blocked by a lagging schema.
Explicit fallback tiers
Every feature × harness pair declares support, degrade, drop, or
unsupported-hard, with an explicit result for every target.
Safe installation
Preview changes, preserve existing files, detect ownership conflicts, and recover interrupted installs without silently replacing user content.
Twenty-two adapter targets
Inspect the native paths and translation rules for every built-in adapter.
Next steps
Quickstart
Follow the shortest path from an empty directory to native artifacts.
Project Structure
Learn which files Soubi discovers and what each path becomes.
Architecture
Follow the complete pipeline from source discovery to native artifacts.
Adapters
Open the emitted paths and translation details for one target.