Documentation Index
Fetch the complete documentation index at: https://docs.ixo.world/llms.txt
Use this file to discover all available pages before exploring further.
The one-sentence difference
A plugin is code your oracle ships with. A skill is a capsule your oracle fetches and runs in a sandbox.Both let an agent do things it otherwise couldn’t. But the mechanism, lifecycle, and author are usually different.
Side by side
| Plugin | Skill | |
|---|---|---|
| Format | TypeScript class extending OraclePlugin | Folder with SKILL.md + scripts (Python, shell, etc.) |
| Lives where | Inside your oracle’s npm bundle | IXO skills registry (ai-skills repo) |
| Lifecycle | Loaded at boot | Discovered + executed per request |
| Who authors | Oracle developer | Anyone — community-contributable |
| How agent uses | Tools bound directly to the LLM | Agent calls search_skills → sandbox_run |
| Execution | In-process Node.js | Per-user Linux sandbox |
| Side effects | Full host access (DB, FS, network, Nest DI) | Sandbox-scoped |
| Update | Redeploy the oracle | Publish a new version — no oracle restart |
Both in the same turn
The cleanest way to see the distinction is to watch them work together:skills and sandbox are plugins — compiled into the oracle, exposing tools the LLM calls. invoice-generator is a skill — a folder in the registry the oracle never imported, fetched and executed at request time.
When to write which
| Write a plugin when… | Write a skill when… |
|---|---|
| You need type safety + full DI (DB, Nest services, Matrix client) | The capability is a self-contained scripted workflow |
| The capability needs an HTTP route (webhook, OAuth callback) | It should be community-discoverable |
| You need to inject behaviour into every turn (middleware) | You want to update it without redeploying |
| The capability is proprietary or oracle-specific | Sandbox isolation is acceptable |
| You need tight integration with the agent (a sub-agent) | The implementation is Python / shell / a binary |
Can a plugin call a skill?
Yes. Theskills and sandbox plugins expose normal tools (search_skills, sandbox_run, …). Your custom plugin can call them directly if you have a deterministic flow. Usually the agent orchestrates instead.
Can a skill use plugin features?
Not directly. Skills run in a sandbox; they don’t see plugins or Nest DI. They get user secrets asx-os-* env vars, an optional skills_invocation UCAN, network (per sandbox policy), and a read-only mount of their own folder. If a skill needs plugin data, the agent passes it in as an argument to sandbox_run.
Read next
Write a plugin
The recipe.
Plugin catalog
The 15 bundled plugins — including
skills and sandbox.packages/oracle-runtime/src/plugins/skills/ and packages/oracle-runtime/src/plugins/sandbox/.