Plugins

A plugin bundles slash commands, agent profiles, skills, hooks and custom tools so they can be shared as one package. If you only need one of those, use a skill, an agent, a hook or an MCP server instead.

Layout#

my-plugin/
├── plugin.json          required
├── commands/review.md   → /my-plugin:review
├── agents/explorer.md   → plugin:my-plugin:explorer
├── skills/review/SKILL.md
├── hooks/hooks.json
└── runtime.mjs          only for custom tools or RPC hooks

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Review helpers.",
  "author": "Example Team"
}

Unknown keys in plugin.json invalidate the plugin. Commands are Markdown prompts with the same frontmatter and $ARGUMENTS placeholders as skills; nested folders become : segments (commands/security/deps.md → /my-plugin:security:deps). Custom tools are served by the runtime over JSON-RPC and appear as plugin__<plugin>__<tool>.

Load and install#

• Local development: faelith --plugin-dir ./my-plugin (repeatable). Loading an unsigned folder is an explicit trust decision.
• Marketplace: /plugin install @scope/plugin@1.0.0. Bundles must be signed (Ed25519) and are verified before extraction; unsigned or unknown-key bundles are rejected. Installed plugins live in ~/.faelith/plugins/cache.

Commands#

/plugin list        installed plugins, versions and sources
/plugin diagnose    manifest, command and agent errors
/plugin trust       trusted signing keys
/reload-plugins     reload plugins and skills

Plugin tools and hooks run through the same permission engine, secret scan and sandbox as everything else; a plugin can never grant itself permissions.