pi-skill-autocomplete

Mid-prompt skill completion and explicit skill loading for Pi. The extension uses Pi's registered skill list, adds a : picker, and inserts [[skill:name]] references. At submission, the complete bodies of referenced registered skills are appended to the user message. This is experimental software in the 0.x series: inspect the source and test it in your own setup before relying on it.

Install

After the package is published, install it in Pi:

pi install npm:@soulwaxx/pi-skill-autocomplete

Reload Pi after installation. Requires Pi 1.4.0 and Node.js >=22.19.0. CI is configured for Linux and macOS with Node 22 and 24. The initial 0.1.0 release has already been published; these source-repository changes do not publish another version.

Use

In a prompt, type : at a token boundary, then search by skill name or description. For example, in the middle of a draft:

Review this change using :code-review and summarize risks.

Choose a result with Tab to insert a visible reference:

Review this change using [[skill:code-review]] and summarize risks.

You can also type or paste [[skill:name]] directly. A valid reference explicitly requests that registered skill even if Pi hides it from model invocation. Repeated references load a skill once, in the order of first appearance.

The extension reads skill files only when a TUI or RPC user input is submitted—not while typing. It preserves authored prompt text and appends the full trimmed instruction bodies as user-message content, with each skill's source directory for locating supporting files. The appendix uses a versioned, length-framed plaintext format with a SHA-256 digest for corruption detection; this is not authentication. The digest and framing let the public user-Markdown transformer compact a recognized, complete appendix in TUI rendering to Skills loaded: name, ..., while persisted messages and provider input retain the full instructions. There is no token reduction or display toggle. Damaged or unrecognized frames remain raw; copying a complete valid generated frame can compact, so this is presentation behavior, not a security boundary. The transformer handles only user messages and does not alter assistant rendering; RPC and HTML output retain full text. Native /skill: can be combined with inline references, and a fresh runtime over stored messages can recognize the self-contained frame. Marker-like text inside a skill body remains part of the opaque, length-framed payload rather than being treated as the appendix boundary. The appended context explicitly tells the model that these skills are already loaded and not to reread their SKILL.md files unless asked to reload them. This is model guidance, not a tool restriction: a model can still choose to reread a file, which Pi displays as a separate [skill] read card. Supporting files are not loaded automatically; the skill can refer to them for on-demand use. Pi's own editor trimming and native command handling remain native. The extension does not elevate skill text into the system prompt or recursively activate references found inside skill bodies.

References are recognized in ordinary Markdown prose. An odd number of backslashes directly before [[skill:name]] escapes it; an even number does not. Inline code is excluded only when an exact-length matching backtick run closes its span; an unmatched inline opener remains literal. Fences allow up to three leading spaces and require at least three backticks or tildes. A closing fence uses the same character with at least the opening run length and only trailing whitespace; an unclosed fence remains literal through end of input. Backtick fence info strings cannot contain backticks. Indented Markdown code is not guaranteed to be excluded.

Only names in Pi's registered skill list can be loaded; arbitrary paths are not accepted. Invalid, unknown, missing, unreadable, malformed, or too-large active references reject the entire submission: no partial prompt is sent, Pi is notified, and the original text is offered for recovery. On TUI rejection, separately supplied startup initialImages are not restored alongside the recovered text; the warning explains that retrying with the original image requires relaunching Pi with that image. The extension does not silently reattach images to later prompts. RPC clients must honor UI notification/editor-text events and retain their own attachments; those clients own the attachment presentation and retention behavior.

The total of unique referenced instruction bodies may be at most 128 KiB (131,072 UTF-8 bytes) after Pi frontmatter removal and trimming. Repeated skills count once. Frontmatter, authored prompt text, and appended labels/source-directory wrappers do not count. This is a byte limit, not a token or context-fit limit, and does not guarantee that a model will obey the instructions. Native prompt-template invocations containing active authored skill references are rejected; template-only invocations remain native. References generated by a template or a loaded skill are not activated.

The extension leaves Print/JSON and extension-generated input unchanged. Native built-in and extension commands that Pi consumes before normal user-input processing keep their native behavior. A leading native /skill: command can be combined with references. The extension preserves / command and @ file completion; it does not promise how Pi's UI folds or renders multiple appended skill blocks.

Migration

Previously, choosing a completion inserted natural-language text such as use the \name` skill(or moved an explicit-only skill into a leading/skill:command). That text did not guarantee that the selected skill body reached the model, and multiple leading native skill commands did not provide a reliable multi-skill loading mechanism. Completions now insert[[skill:name]]. Existing natural-language text does not trigger loading; replace it with an explicit reference or select a completion. Pi's native direct /skill:name` command remains Pi-native.

Development and checks

Use Node.js >=22.19.0:

npm ci --ignore-scripts
npm run check
npm run test:feasibility
npm run test:artifact
npm run bench
npm ci --prefix .github/release-tools --ignore-scripts
npm run release:check
npm run test:release
npm audit --audit-level=high
npm audit --prefix .github/release-tools --audit-level=high

For GitHub Actions workflow syntax validation, install the actionlint version selected in .github/workflows/test.yml and verify its archive SHA-256 against the matching upstream release's checksum manifest, then run:

actionlint .github/workflows/*.yml

npm run check runs the test suite, TypeScript check, and Biome lint. Tests run in disposable homes, Pi profiles, and working directories with a small environment-variable allowlist; they use fake providers and make no paid model calls. npm run test:artifact packs and unpacks the runtime allowlist, then checks the package using the packed extension. npm run bench reports local completion and submission timings. Release verification and recovery tests use fakes; no command above publishes a package or creates a release.

CI tests Linux/macOS on Node 22 and 24. PR metadata edits run only the title check. Renovate maintains dependencies and pinned CI tools through reviewed PRs. Releases reuse verified PR evidence, test the actual versioned package, and publish through npm OIDC with provenance; there is no npm-token fallback.

See the assessment for baseline findings, benchmark details, and limitations, and release operations for the maintainer-only release and recovery procedures. These documents are in the source repository; the packed npm artifact includes the README, not the docs/ directory.