pi-skill-paths

Canonical SKILL.md path correction and bash skill-access guard for Pi.

pi-skill-paths intercepts read and bash tool calls to:

• Bash guard — block bash-based read/search of SKILL.md only (not skill directories)
• Read autocorrect — silently normalize skill directory paths, resolve relative .pi/skills/ paths, substitute canonical absolute paths

Works with Pi / pi-web environments where extensions can intercept read and bash tool calls.

Why

Agents sometimes try to read skill files using bash (cat ~/.pi/agent/skills/.../SKILL.md), which:

• Bypasses Pi's skill system and rendering
• Produces raw markdown without proper context
• Can break with path resolution quirks

This extension prevents that and auto-corrects paths so the agent uses read the right way.

Features

• Bash guard — blocks cat/sed/head on SKILL.md and find/grep/rg searching for SKILL.md; does NOT block scripts, assets, or directory listing
• Read autocorrect — normalizes skill directory paths, resolves relative .pi/skills/ paths, substitutes canonical absolute paths
• Zero config — works out of the box, no settings needed
• No npm deps — only node:fs/promises and node:path

Install

Install from npm:

pi install npm:@haemmid/pi-skill-paths

Install from git:

pi install git:github.com/haemmid/pi-skill-paths

Or install from a local checkout:

pi install /path/to/pi-skill-paths

Behavior

Bash guard (blocking)

Command	Result
cat ~/.pi/agent/skills/ask-chatgpt/SKILL.md	BLOCK
cat ~/.agents/skills/humanizer/SKILL.md	BLOCK
sed -n '1,50p' .pi/skills/foo/SKILL.md	BLOCK
head ~/.agents/skills/visual-test/SKILL.md	BLOCK
cat ~/.pi/agent/skills/ask-chatgpt/SKILL.md	BLOCK
cat ~/.agents/skills/humanizer/SKILL.md	BLOCK
sed -n '1,80p' .pi/skills/foo/SKILL.md	BLOCK
head ~/.agents/skills/visual-test/SKILL.md	BLOCK
find /home/haemmid -name SKILL.md	BLOCK
find ~ -name SKILL.md	BLOCK
find .pi/skills/foo -name SKILL.md	BLOCK
grep -R SKILL.md ~/.agents	BLOCK
grep -R SKILL.md .pi/skills/foo	BLOCK
rg SKILL.md .pi/skills	BLOCK
cat package.json	PASSES
cat my-SKILL.md-notes.txt	PASSES
bash .pi/skills/foo/scripts/run.sh	PASSES
node ~/.pi/agent/skills/foo/scripts/build.js	PASSES
python .pi/skills/foo/tool.py	PASSES
ls .pi/skills/foo/	PASSES
find .pi/skills/foo/scripts -type f	PASSES
grep -R TODO .pi/skills/foo/scripts	PASSES
find . -name "*.ts"	PASSES
find .	PASSES
grep -R foo .	PASSES

Read autocorrect (silent)

Before	After
read .agents/skills/ask-chatgpt	read /home/haemmid/.pi/agent/skills/ask-chatgpt/SKILL.md
read .pi/skills/chatgpt-plan-review	read /abs/project/.pi/skills/chatgpt-plan-review/SKILL.md
read ~/.agents/skills/context7-mcp	read /home/haemmid/.agents/skills/context7-mcp/SKILL.md
read ~/.agents/skills/context7-mcp/SKILL.md	read /home/haemmid/.agents/skills/context7-mcp/SKILL.md (canonical)
read ../.pi/skills/foo/SKILL.md	No change (traversal)

Conflict policy

• Project-level skills override global skills
• Duplicate global skills → console.warn, first wins

Not the same as pi-skill-guard

pi-skill-paths works before tool execution — it intercepts read and bash calls, corrects skill paths, and blocks bash-based skill access. It does not handle tool-not-found recovery, inject skills, or add custom tools.

License

MIT