@howaboua/pi-better-skills-tool

Progressive skill discovery for Pi, Code Mode and Notebook Mode. The skills tool lists the active catalog by category, reads one or more skills, or reads selected references without loading an entire package into context.

Install

pi install npm:@howaboua/pi-better-skills-tool

Requires Pi 1.0.0 or newer. Install @howaboua/pi-codex-conversion 3.0.52 or newer too for Code Mode and Notebook Mode. The extension remains a normal Pi tool when Codex conversion is absent.

Start Pi normally

Start Pi without --no-skills. Better Skills hides catalog advertising from the system prompt while preserving Pi's native /skill:<name> commands. The model discovers and reads the loaded catalog on demand through skills.

Remove --no-skills from an existing wrapper or alias. An additional catalog-clearing before_agent_start hook is no longer needed.

Use

Normal Pi uses one structured command parameter. Code Mode and Notebook Mode use the compact string surface:

await tools.skills("list")
await tools.skills("list code session")
await tools.skills("read code-review")
await tools.skills("read communication codebase-hygiene")
await tools.skills("read codebase-hygiene testing js-ts")
await tools.skills("read communication conversation writing; read codebase-hygiene testing")

Pi's loaded skill catalog is authoritative during normal use. When Pi has no loaded skills, including --no-skills sessions, the tool falls back to the standard global skills/ directory under Pi's agent directory and $PWD/.pi/skills/. A same-named session skill overrides the global skill. Skill reads include absolute package paths for later reference, script, or asset access.

After the initial skill, an exact skill name adds that full skill package. Reference shorthand resolves within the most recently selected skill first, then across the visible catalog. A unique reference can come from another skill. An ambiguous global reference requires a skill-qualified name such as communication/references/conversation or an absolute source path. A read with only references still returns only the requested Markdown and source paths, without repeating the initial package inventory.

Separate independent read or list commands with ;. Each group resolves references in its own skill scope. Invalid groups fail the whole call.

Results stay within 48 KiB of UTF-8 text. Larger results include an Incomplete marker and an exact continuation command ending in --offset <byte>. Run that command to retrieve the next part. Continuations are stateless and re-read the catalog, so restart the original command if skill files change between calls. Normalized commands, excluding the offset suffix, are limited to 4 KiB to keep continuation instructions within the result budget.

Remove or disable any legacy codex-conversion-custom-tools/skills.toml after installing this extension. Keeping both definitions gives Code Mode two tools named skills, which it rejects.