Plugin author guide
About 522 wordsAbout 2 min
End-to-end guide for writing a Spora plugin — a Composer package that ships tools, migrations, an optional admin UI, skills, and reusable Agent templates to a Spora deployment.
The complete plugin system reference (load order, manifest validation, boot-time stamp cache, security model) lives in Concepts → Plugin system. The operator-facing install/uninstall flow (bin/spora plugin:install, HTTP endpoints) is documented in Install API. This guide is focused on how to author a plugin from scratch.
For the local development workflow (Composer path repos, 3-terminal HMR walkthrough for plugins with a Vue frontend), see Local plugin development.
Reading order
New to plugin authoring? Read in this order:
- Foundations — what a plugin is, the
plugin.jsonmanifest, the entry-point class. - Tools — add the first callable surface.
- Admin UI — only if your plugin ships a frontend.
Skip Migrations, Skills, and Agent templates on first read — they are independent and can be picked up when needed. Distribution is for after you have working code on main and want to ship it.
Chapter index
| Chapter | What it covers |
|---|---|
| Foundations | The package shape, the plugin.json manifest, the entry-point class, the ten hooks on SporaExtensionInterface, and a worked ⌘K search provider. |
| Tools | Adding a tool — the canonical callable surface. The #[Tool] / #[ToolParameter] attribute surface. |
| Migrations | Schema versions, filename prefixes, the up() / down() convention. |
| Admin UI | The two-package Vue IIFE pattern, the apps() hook, the auto-require convention, publishing sequencing. |
| Agent templates | Ship curated Agent templates with your plugin. Operator gallery, auto-install policy, warning codes. |
| Skills | Ship skills with your plugin — a directory via skillPaths(), or a provider via skillProviders(). |
| Speech providers | Contribute a SpeechToTextProviderInterface — only when the vendor’s wire shape is not OpenAI-multipart. |
| Distribution | The spora-plugin keyword, the PSR-4 entry-point quirk, testing, SemVer, the release checklist. |
Looking for an older link?
This page used to be a single 564-line document. The chapter split happened in Phase 11 (July 2026). If you followed an old in-page anchor, the content moved to one of the chapter URLs above — these are hand-maintained pointers, not configured redirects, so nothing rewrites an inbound link for you:
#what-a-spora-plugin-is,#pluginjson-manifest,#entry-point-class→ Foundations#adding-a-tool→ Tools#adding-an-llm-driver→ LLM drivers — thedrivers()hook was removed in 1.0, so that page is now a tombstone pointing at what replaced it#adding-migrations→ Migrations#adding-an-admin-ui→ Admin UI#recipes-wip--not-yet-shipped→ Agent templates#the-spora-plugin-keyword,#psr-4-entry-point-quirk,#testing,#versioning,#reference-implementations→ Distribution