skills-retrieval

A Pi package that discovers skills, uses Scribery for semantic retrieval and reranking, and activates selected skills through Pi's native skill pipeline.

It exposes exactly two model-facing tools:

• search_skills searches eligible skill packages without revealing the full catalog;

• load_skill activates a selected SKILL.md, or returns explicitly requested reference files from that skill.

When load_skill is called without files, it delegates to Pi's native /skill:name pipeline. The skill is therefore injected as a user-role skill message and displayed with Pi's normal collapsible skill widget. Requests for specific nested files, such as references/details.md, remain ordinary tool results.

Scribery is a private implementation detail. The package starts a read-only Scribery MCP subprocess with only list_documentation_sources and search_documentation enabled. Scribery's tools are never exposed to the model, and this project does not provide a public MCP server or executable.

Source policy

Every skill selected for retrieval must remain hidden from Pi's native model catalog:

---
name: example-skill
description: Specialized guidance for an example workflow.
disable-model-invocation: true
---

The source list of the configured Scribery documentation is the retrieval allowlist. A skill is eligible only when its directory has been added as a Scribery source, its SKILL.md is present in the active index, and it sets disable-model-invocation: true. Skills absent from that index remain available only through Pi's manual skill invocation.

Related MCP server: pid-mcp

Automatic manifest

The in-memory skill manifest is built when Pi loads the extension and refreshed internally before every search or load. There is no manifest-management tool.

Discovery is recursive below the configured Pi skills root. Each directory containing SKILL.md becomes one skill package; nested files such as references/*.md, scripts, and assets belong to that package. File hashes are cached by size and filesystem timestamps during the extension lifetime. A package hash and whole-manifest hash change whenever relevant files change.

Scribery's active indexed-file inventory supplies each result's original absolute location. Skills Retrieval uses that location to map a hit in a nested reference back to the owning SKILL.md. Duplicate filenames therefore do not make skill selection ambiguous.

Prepare Scribery

In scribery-tui:

1. Create documentation named pi-skills.

2. Choose Configure sources → Add directory.

3. Select one skill directory that should be retrievable, such as ~/.pi/agent/skills/example-skill.

4. Give it a unique mount path, normally the skill name.

5. Repeat for each skill you want in retrieval.

6. Ensure the parent ~/.pi/agent/skills directory is not also configured as a source, which would index every skill and duplicate selected files.

7. Choose Index documentation.

Use the same ordinary Index documentation action after skill files or the source list changes. Scribery discovers additions, modifications, and deletions while reusing unchanged chunks and embeddings.

Install in Pi

cd /Users/donais/Documents/Projects/skills-retrieval
npm install
npm run check
pi install /Users/donais/Documents/Projects/skills-retrieval

The Pi extension is generated at dist/skill-retrieval/index.js. Configure it through environment variables before starting Pi. For example:

export SKILLS_RETRIEVAL_SCRIBERY_COMMAND=/Users/donais/Documents/Projects/scribery/packages/scribery/dist/mcp.js
export SKILLS_RETRIEVAL_DOCUMENTATION=pi-skills
export SKILLS_RETRIEVAL_SCRIBERY_PROFILE=omlx-qwen3
export SKILLS_RETRIEVAL_SCRIBERY_API_KEY=omlx
pi

Available settings are:

• SKILLS_RETRIEVAL_SKILLS_ROOT — defaults to $PI_CODING_AGENT_DIR/skills or ~/.pi/agent/skills;

• SKILLS_RETRIEVAL_DOCUMENTATION — defaults to pi-skills;

• SKILLS_RETRIEVAL_SCRIBERY_COMMAND — defaults to scribery-mcp;

• SKILLS_RETRIEVAL_SCRIBERY_PROFILE;

• SKILLS_RETRIEVAL_SCRIBERY_BASE_URL;

• SKILLS_RETRIEVAL_SCRIBERY_API_KEY;

• SKILLS_RETRIEVAL_SCRIBERY_RERANK_MODEL;

• SKILLS_RETRIEVAL_SCRIBERY_RERANK_INSTRUCTION.

Use either a Scribery profile or explicit base-URL/reranking settings, not both.

Pi skill discovery must remain enabled. Individually indexed skills must still set disable-model-invocation: true; this hides their descriptions from Pi's model catalog without preventing the extension from invoking /skill:name.

Security boundary

• Filesystem and Scribery operations are read-only. Native skill activation adds a user message to the current Pi session.

• There is no list_skills, indexing, synchronization, or manifest tool.

• Search is hard-scoped to indexed files owned by skill packages whose SKILL.md is indexed.

• Skills omitted from the Scribery source list are neither searchable nor loadable through retrieval.

• load_skill accepts only manifest-listed, skill-relative paths and rejects traversal, binary files, oversized files, and oversized combined responses.

• The model cannot select documentation identifiers, provider settings, reranking settings, arbitrary source identifiers, or Scribery tools.

• The selected skill is validated through retrieval policy before Pi expands it.