Many bodies, one soul. The form can move; the soul stays in its own repo.
An Oracle is three things, and /soul brings all three — by reference, so the Oracle's
own repo stays the single source and every fix there reaches every guest:
| Part | Lives in | Brought by |
|---|---|---|
| Soul — who it is | ψ/memory/resonance/<name>.md, oracle.md, SOUL.md, IDENTITY.md, CLAUDE.md identity |
reading them, in that order |
| Skills — what it can do | .claude/skills/*/SKILL.md |
a symlink per skill in this repo's .claude/skills/ |
| Expertise — what it learned | ψ/memory/learnings/*.md |
an index of titles; read a file when its topic comes up |
guest/.claude/skills/pulse-board ──symlink──▶ pulse/.claude/skills/pulse-board
guest/.claude/souls/pulse.json manifest of the links this skill made
guest/.git/info/exclude both excluded — never in the tracked .gitignore
SKILL_DIR is the base directory printed above this skill.
Step 1 — resolve the Oracle
The argument is a path, or a name for maw locate (if you have maw):
ARG="<argument>"
if [ -d "$ARG" ]; then ROOT=$(cd "$ARG" && pwd)
else ROOT=$(maw locate "$ARG" --path 2>/dev/null)
fi
echo "root: ${ROOT:-NOT FOUND}"
If maw locate prints "matches N oracles", it lists org/name candidates — show them and
ask which one; never pick. Empty → say so and stop. No filesystem search.
Step 2 — see what it carries (writes nothing)
bun "$SKILL_DIR/scripts/soul.ts" show "$ROOT"
It prints the soul files, every skill with what will happen to it, and the newest learnings:
| Mark | Meaning |
|---|---|
+ |
will be linked |
= |
already linked here |
~ |
read-and-follow — a skill with that name already exists in this repo or in ~/.claude/skills/. Linking would make two skills with one name, so it is not linked; to use the Oracle's version, Read the printed SKILL.md path and follow it |
With --show, stop here.
Step 3 — link the skills
bun "$SKILL_DIR/scripts/soul.ts" link "$ROOT"
Relative symlinks, a manifest at .claude/souls/<name>.json, and lines appended to
.git/info/exclude — the repo's tracked files do not change. If it reports
⚠ TRACKED already, stop and tell the human: those paths are committed in this repo.
New skills usually appear in the session's skill list without a restart (Claude Code
watches skill folders). If they don't, the human runs /reload-plugins.
Step 4 — load the soul and the expertise
Read every soul file show listed, in order. Then keep the learnings index in mind: when
the work touches a topic in it, Read that learning before acting — that is the Oracle's
experience, not a guess.
Step 5 — say who is here
<Name> here — soul, <N> skills and <M> learnings from <ROOT> — working in <repo>.
Working as a visiting Oracle
- Borrowed skills run from their home. Many skills assume their own repo as the working
directory (
./scripts, config files,just). When a linked skill refers to repo-relative paths, resolve its home withrealpathon the skill's base directory and go up three levels (skills/<s>→.claude→ repo), and run those commands there — in a subshell, never by changing the session's cwd. Commands about this repo still run here. - This repo's rules win. The guest's
AGENTS.md/CLAUDE.mdoverride the visitor's habits on everything they cover. - Memory stays with the guest's caretaker. If
ψlinks to a vault, that is where retros and learnings go. A visitor does not write into its own home repo from here unless the human asks. - Rule 6. It is still one AI wearing a form. Say so when asked; never claim to be the
Oracle's own running session. For its real view, ask it (
/talk-to).
Changing souls
bun "$SKILL_DIR/scripts/soul.ts" off <name>
Removes only the symlinks its manifest lists, and only while each still points into that
Oracle — real folders and other links are never touched. Exclude lines stay (harmless).
Then /soul <next>.
What off cannot do: unread the soul. The old soul's files remain in this conversation's
context. For a clean change of identity, run off, then start a new session with
/soul <next>; within one session, say plainly which soul is speaking now.