tomevault-io Create Skill
Architecture
Skills in this setup live in three places that must stay in sync:
- Repo (
~/git/pi-config/skills/<name>/SKILL.md) — the source of truth, tracked in git - Pi-managed clone (
~/.pi/agent/git/github.com/bruno-garcia/pi-config/skills/<name>/) — synced from GitHub - Symlink (
~/.pi/agent/skills/<name>) → points to the pi-managed clone (2)
Pi discovers skills from ~/.pi/agent/skills/. The symlinks there point to the pi-managed clone, which syncs from GitHub. So the flow is:
repo → git push → GitHub → pi sync → managed clone ← symlink ← pi discovery
Steps
1. Create the skill in the repo
mkdir -p ~/git/pi-config/skills/<name>
Write ~/git/pi-config/skills/<name>/SKILL.md with valid frontmatter:
---
name: <name>
description: <what it does and when to use it>
---
<instructions>
Name rules: lowercase, a-z, 0-9, hyphens only. Must match the directory name.
2. Copy to the pi-managed clone
The managed clone won't have the new skill until the next pi sync from GitHub. Copy it manually so the symlink works immediately:
cp -r ~/git/pi-config/skills/<name> ~/.pi/agent/git/github.com/bruno-garcia/pi-config/skills/<name>
3. Create the symlink
ln -s ~/.pi/agent/git/github.com/bruno-garcia/pi-config/skills/<name>/ ~/.pi/agent/skills/<name>
4. Verify
# Symlink resolves
cat ~/.pi/agent/skills/<name>/SKILL.md > /dev/null && echo "OK"
# All skills are symlinks (no regular directories)
ls -la ~/.pi/agent/skills/
5. Commit
Use the commit skill to commit the new skill to the repo.
6. Reload
Tell the user to run /reload or restart pi so the new skill appears in the system prompt.
Common Mistake
Never create a skill directly in ~/.pi/agent/skills/<name>/ as a regular directory. It won't be tracked in git, won't sync across machines, and will silently diverge from the repo. Every entry in ~/.pi/agent/skills/ must be a symlink.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.