pi-skill-tool0.1.0

pi-skill-tool

A pi extension that registers a skill tool, so models load skills the way Claude Code skills expect: by calling a tool, not by reading SKILL.md with read.

{ "skill": "grilling", "args": "the current plan" }

Why

Skills written for Claude Code say things like:

Call the Skill tool twice, for "grilling" and "domain-modeling".

pi has no such tool. When a model hits that instruction it either reads SKILL.md directly with read (works, but skips the skill wrapper and bundled-file hints) or gives up on the skill. This extension provides the missing tool, with the same parameter shape (skill, args) Claude Code uses, so those skills work unmodified.

Install

pi install npm:pi-skill-tool

Or try it for one invocation without touching settings:

pi -e npm:pi-skill-tool

Restart pi (or run /reload) after installing; remove it with pi remove npm:pi-skill-tool.

If your npm configuration points at a registry mirror that has not synced the release yet, install with a one-shot registry override:

npm_config_registry=https://registry.npmjs.org pi install npm:pi-skill-tool

Usage

The model calls it on its own when a task matches a skill in <available_skills> or when loaded instructions mention the Skill tool. You can also ask directly:

Use the skill tool to load grilling

Explicit forms that all resolve:

• { "skill": "grilling" }
• { "skill": "/skill:grilling" }
• { "skill": "Grilling" }
• { "skill": "tdd", "args": "build ticket 12" }

The result mirrors pi's built-in /skill:name expansion:

<skill name="grilling" location="/home/you/.agents/skills/grilling/SKILL.md">
References are relative to /home/you/.agents/skills/grilling.

<body of SKILL.md, frontmatter removed>
</skill>

Bundled files (relative to /home/you/.agents/skills/grilling):
- references/example.md

args is appended after the block, exactly like /skill:name args. Unknown names produce a failed result that lists the available skills and suggests a close match, so the model can recover in one turn.

Behavior notes

• No private discovery. The registry comes from pi's own resolution: systemPromptOptions.skills on the before_agent_start event, falling back to parsing the <available_skills> prompt section. settings.resources.skills, package skills, project skills, and extension-discovered paths therefore behave exactly as pi does.
• Guidance, not enforcement. Two promptGuidelines rules tell the model to load skills with this tool instead of reading SKILL.md. Direct file reads still work, and nothing intercepts read or bash.
• Skills hidden from model selection are loadable by name. Skills with disable-model-invocation: true (for example grill-with-docs) never appear in <available_skills>, but wrapper skills depend on loading them after the user invokes /skill:name explicitly. The tool therefore accepts them by exact name.
• Always the full body. Repeated calls return the full instructions again; no "already loaded" state is kept. Bodies above 256 KiB are truncated with a pointer to the file.
• Read-only. The tool only reads SKILL.md and lists the skill directory (two levels deep, skipping dotfiles, node_modules, and .git).

Development

npm install
npm run check     # tsc --noEmit + node --test

Layout:

Path	Purpose
src/index.ts	Extension factory: registry cache + tool registration
src/registry.ts	Skill type, event/XML extraction, lookup, suggestions
src/skill-content.ts	Frontmatter stripping, file reading, bundled-file listing, result formatting
src/tool.ts	Tool schema, execute, renderers
test/	Unit tests plus a wiring test that drives the real factory through a stub ExtensionAPI

To try local edits for a single run without installing them, point -e at the package directory. That is a temporary dev-only override and is never written to settings:

pi -e . --mode json -p 'Call the skill tool for "grilling" and quote its first sentence.'

Look for a tool execution event for skill in the JSONL stream, and no read of SKILL.md.

Releases

prepublishOnly runs the full check, and publishConfig.registry targets https://registry.npmjs.org even when your npm client uses a mirror.

npm version patch      # or minor/major
npm publish
pi update --extensions

The package is installed unpinned, so pi update --extensions tracks the latest published release. npm login --registry=https://registry.npmjs.org is required once per machine.

Limitations

• Only skills pi already discovered are reachable; skills outside pi's skill locations are not.
• There is no slash command. pi already provides /skill:<name>.
• The tool is not a permission boundary: read and bash can still open any file.