opensoulmd

---

name: opensoulmd

description: Search, summon, and possess your agent with SOUL.md personality files from the OpenSOUL.md registry

metadata:

{

"openclaw": { "requires": { "bins": ["soul"] }, "primaryEnv": null },

"install":

[

{

"id": "curl",

"kind": "shell",

"command": "curl -fsSL https://opensoul.md/install.sh | sh",

"bins": ["soul"],

"label": "Install via curl (recommended)",

},

{

"id": "npm",

"kind": "node",

"package": "opensoul",

"bins": ["soul"],

"label": "Install via npm",

},

],

}

---

You can manage your agent's personality by possessing it with SOUL.md files from the OpenSOUL.md registry.

Available actions

Possess — change soul

When the user asks to change personality/soul:

1. Run `soul possess <name> --yes` — this auto-summons from the registry if the soul isn't cached locally.

You can also possess from a local file path: `soul possess /path/to/SOUL.md --yes`

Use `--dry-run` to preview what would happen without writing anything.

Exorcise — restore original

If the user wants to go back to their original personality: `soul exorcise`

This restores the backed-up SOUL.md from before the first possession.

Search souls

To search the registry: `soul search <query> --no-interactive`

Sorting options:

To show all available souls: `soul search --top --no-interactive`

Summon — download without possessing

To download a soul to local cache without activating it: `soul summon <label>`

The user can activate it later with `soul possess <name>`.

List cached souls

To show locally cached souls: `soul list`

Supports pagination with `--page <n>` and `--per-page <n>`.

Banish — remove from cache

To remove a soul from the local cache: `soul banish <name>`

Status

To check what soul is currently loaded: `soul status`

Shows the SOUL.md path, possession state (original or possessed), and backup status.

Path — show or set SOUL.md location

To show the current SOUL.md path: `soul path`

To set a new path: `soul path /path/to/SOUL.md`

To show or set the OpenClaw skills directory: `soul path --skills` or `soul path /path/to/skills --skills`

Config

To get or set CLI configuration values:

Install / Uninstall skill

To install the OpenSoul skill into OpenClaw: `soul install`

To remove it: `soul uninstall`

Important notes