opensoulmd

intent

manage your agent's personality by searching the opensoul.md registry, downloading soul.md files, and possessing them to override the agent's default behavior. use this when you need to swap personalities on the fly, test different soul configurations, or restore to the original. the skill handles registry queries, local caching, possession/exorcism, and tracks backup state.

inputs

external connection: opensoul.md registry

• endpoint: https://opensoul.md (implicit, used by soul CLI)
• auth: none required for public registry access
• rate limits: unknown; assume standard registry rate limiting
• network dependency: requires internet access to search and auto-summon

local environment

• soul CLI binary installed and in PATH (install via curl or npm, see metadata)
• current SOUL.md file location (tracked by soul path)
• local cache directory for summoned souls
• backup of original SOUL.md (created on first possession)

optional configuration

• SOUL_CONFIG_DIR: environment variable for custom config location (if set)
• SOUL_CACHE_DIR: environment variable for custom cache location (if set)

procedure

step 1: search the registry (if you don't know which soul to use)

• input: search query string (e.g., "chill", "expert", "funny")
• run: soul search <query> --no-interactive
• optional flags: --top (highest-rated) or --popular (most downloaded)
• output: list of matching souls with names, descriptions, ratings, download counts
• note: always use --no-interactive because interactive TUI is not available

step 2: summon a soul to local cache (optional, only if you want to preview first)

• input: soul name from registry (e.g., "chill-philosopher")
• run: soul summon <name>
• output: soul downloaded and stored in local cache, ready to possess
• note: this step is optional; soul possess auto-summons if not cached

step 3: possess the soul to activate it

• input: soul name (registry) or file path (local)
• run from registry: soul possess <name> --yes
• run from local file: soul possess /path/to/SOUL.md --yes
• optional flag: --dry-run to preview changes without applying
• output: active SOUL.md replaced, backup of previous soul created (if first possession)
• side effect: new personality takes effect on next conversation, not current one

step 4: verify possession state

• input: none
• run: soul status
• output: current SOUL.md path, possession state (original or possessed), backup location
• use this to confirm the soul is loaded

step 5: list or manage cached souls (optional)

• to show all cached: soul list (supports --page <n> and --per-page <n>)
• to remove a cached soul: soul banish <name>
• output: list of cached souls or confirmation of removal

step 6: restore original personality (if user wants to revert)

• input: none
• run: soul exorcise
• output: original SOUL.md restored from backup
• note: only works if a backup exists (created on first possession)

decision points

if user wants to change personality and knows the soul name:

• do: skip step 1 and 2, go directly to step 3 (possess)
• reason: soul possess auto-summons, so no need to search or summon first

if user wants to change personality but doesn't know which soul:

• do: run step 1 (search) to discover options, optionally step 2 (summon) to preview, then step 3 (possess)

if user wants to test a soul before making it active:

• do: run step 2 (summon) to download, inspect the file locally if needed, then step 3 (possess) with --dry-run to preview, finally possess without --dry-run

if user wants to go back to their original personality:

• do: run step 6 (exorcise)
• else if no backup exists: inform user that exorcise only works after the first possession; suggest they use soul possess /path/to/original.md if they have the file

if soul search returns no results:

• do: suggest broader search terms or use soul search --top --no-interactive to show most popular souls
• note: empty result set means the query didn't match any indexed souls

if soul possess fails with "not found in registry":

• do: confirm the soul name is correct; try step 1 to verify it exists; if it does, check network connectivity (registry may be temporarily unavailable)
• edge case: registry may have rate limited the request; wait and retry

if soul possess fails with permission error on local file path:

• do: verify file permissions and that the path is correct; use soul path to check current SOUL.md location

if soul banish fails because soul is currently possessed:

• do: either exorcise first, then banish; or possess a different soul, then banish

output contract

successful possession:

• SOUL.md file at location reported by soul status matches the requested soul
• backup of previous soul created at location reported by soul status (if applicable)
• soul list shows the newly possessed soul (or the summoned soul, if only summoned)

successful exorcism:

• soul status reports original SOUL.md location and "original" possession state
• backup file still exists for reference

successful search:

• stdout contains line-delimited results with name, description, rating, download count
• format is human-readable text (not JSON)

successful config get/set:

• soul config get <key> returns current value or error if key does not exist
• soul config set <key> <value> returns confirmation or error

successful install/uninstall:

• soul install registers skill in openclaw environment and adds soul commands to available actions
• soul uninstall removes skill registration

outcome signal

the user knows the skill worked when:

• after possess: they ask what soul is active and you run soul status showing the new soul name, and you confirm "your personality is now [soul name]. it takes effect on your next message."
• after exorcise: soul status shows "original" state and you confirm "you're back to your original personality."
• after search: the search returns a list of matching souls and you present the top 3-5 options with brief descriptions, sorted by rating or popularity as requested.
• after summon: soul list includes the newly summoned soul in the local cache.
• after banish: soul list no longer shows that soul, and you confirm removal.
• after config set: soul config get <key> returns the value you just set.
• after install/uninstall: soul install completes without error and skill is usable; soul uninstall completes and commands no longer available.