| name | the-tether |
| description | How to install this Book of Spells into a conduit so its gathered skills become usable — by symlink, not by copy. Use whenever the user wants to install, set up, enable, add, or "load" the Book's spells into their agent; asks where skills go or how a conduit finds them; or asks how to keep the spells up to date. The companion to the-grimoire (which *finds* spells once they are installed): this one *shelves the Book* so the grimoire has something to find. |
🔗 The Tethering of the Book — Installing the Spells
You do not install the spells one by one. The Book holds hundreds, and no
conduit could carry them all in its head at once. Instead you install the single
keystone — the-grimoire — and tether it to the living Book. From that one
thread, the grimoire discovers and summons every other spell on demand
(progressive disclosure). Tether the index; the index reaches the rest.
A tether is a symlink, not a copy. This matters:
- The Book stays live.
git pull in the repo updates every spell at once —
no re-installing.
- The paths still resolve. The grimoire reads its catalogue at
../skills/,
relative to its real home in the repo. A symlink keeps that thread intact; a
loose copy would sever it.
The Rite of Tethering
-
House the Book. Clone (or keep) this repository somewhere permanent — the
tether will point here forever, so don't put it in /tmp.
git clone https://github.com/Pyfagorass/bookofspells.git ~/grimoires/bookofspells
-
Find your conduit's skills-shelf. Each harness keeps its spells in a known
directory:
- Claude Code —
~/.claude/skills/ (personal) or <project>/.claude/skills/
(one project only).
- The open standard (agentskills.io)
—
~/.agents/skills/ (user) or <repo>/.agents/skills/ (project). Codex,
Gemini, OpenCode and other honouring conduits read this universal shelf.
If unsure, consult that conduit's own docs; the tether mechanism is the same
wherever the shelf lives. The standard guarantees what we rely on: symlinked
folders are followed, and two spells of the same name are never merged
— which is why the Book gives each spell a house-prefixed true name.
-
Cast the tether. Symlink the keystone folder onto the shelf. Use an
absolute path to the repo so the link never goes stale:
BOOK=~/grimoires/bookofspells
SHELF="$HOME/.agents/skills"
mkdir -p "$SHELF"
ln -s "$BOOK/the-grimoire" "$SHELF/the-grimoire"
Tether only the-grimoire — it is the single entry point, and routes
through its catalogue to every other keystone (the-spellwright to forge,
the-emissary to summon an MCP server, the-tether itself) and to all the
gathered spells. You need not — and should not — symlink the whole skills/
shelf, nor the other keystones; the grimoire reaches them for you. (If you
want one of them to trigger on its own description, you may symlink it
directly too — but it is not required.)
-
Confirm the binding. Start your conduit and bid it cast a spell the Book
holds — "is there a spell for Figma?" If the grimoire stirs and greps
../skills/_index/ back inside the repo, the tether holds.
Wards
- Don't move the Book after tethering. The symlink remembers an absolute
path; relocate the repo and the thread snaps. Move it, then re-cast the tether.
- One thread, not eight hundred. Tether only the keystone(s). The whole point
of
the-grimoire is that you carry the index, not the library.
- A copy is a corpse. If you copy
the-grimoire/SKILL.md instead of linking
it, its ../skills/ paths point at nothing and the spell finds an empty Book.
Always symlink.
One thread to the living Book, and every spell is within reach. 🕯️
