pi-agent-skills

A Pi extension that fills skill gaps, ported from opencode-agent-skills-md v2.0.1. It provides path-safe skill reads, confined script execution with risk approval, and cross-harness discovery across .claude, .codex, and .opencode user and project scopes, plus ~/.config/opencode/skills.

Tools

• get_available_skills — list skills advertised from supported non-native roots. Optional query ranks by task text, and optional integer limit (1–100) bounds results. For example, get_available_skills({ query: "review a TypeScript change", limit: 5 }) returns matching summaries, skill-directory path, exact skillFile, static usage guidance, and pagination (totalMatched, returned, truncated). Blank queries preserve discovery order; unmatched queries return no suggestions. Ranking is deterministic and metadata-only: exact name first, then name tokens, trigger, and description, with codepoint name ordering for ties.
• read_skill_file — read a file within a skill; after selecting one, load it with read_skill_file({ skill: "review-helper", file: "SKILL.md" }) before applying it. file may be relative to the skill directory (notes.md, ./SKILL.md) or absolute, such as the skillFile returned by get_available_skills, as long as its real path stays inside the skill. Paths that escape the skill return Denied: the requested path escapes the skill directory., distinct from File not found in the skill directory. When the file is the skill's SKILL.md and the skill has registered scripts, the content is followed by a Registered scripts (run them directly with run_skill_script; no need to read their source first): list. Scripts that run through their shebang interpreter rather than directly are listed with (via <interpreter>), for example - scripts/create-temp-file.sh (via /usr/bin/env bash). Tool guidance helps the agent adopt this discover-then-load flow but cannot guarantee skill selection or override user scope.
• run_skill_script — run scripts in the skill registry allowlist; script is the registered relative path (scripts/run.sh, ./scripts/run.sh) or its absolute path. Unregistered names are denied with the list of registered scripts, for example Script 'run.sh' is not registered for skill 'demo'. Registered scripts: scripts/run.sh. That error masks control characters in the requested script and skill names and lists at most 20 registered scripts, then …and N more. Risk-scanned scripts require ctx.ui approval and fail closed when UI is unavailable, and timeout kills the child process. Prompt guidance tells the agent to run a registered helper directly when the loaded skill instructions call for it, without reading its source first, because this scan and approval already guard execution.

The tool store is the union of extension roots and Pi-native roots, so native skills can also be read and run. Only non-native roots are advertised in the injected <available-skills> system-prompt block and returned by get_available_skills.

Advisory skill suggestions

For each turn, the extension injects a single available-skills system-prompt section: up to three deterministic advisory suggestions (discovery order, never prompt-ranked) followed by the full catalog. Suggestions are candidates to consider, never automatic selections; use get_available_skills({ query }) for task-ranked results. The section content is byte-stable across renders — it never depends on the current prompt — so mid-run system-prompt re-renders (model switches through bridges such as pi-claude-bridge, resumed sessions) stay identical to the original capture. The host wraps the section in its own <available-skills> tags; the extension never emits them itself. Skills with disable-model-invocation frontmatter are excluded from the automatic catalog, suggestions, and get_available_skills, but remain resolvable with read_skill_file.

Install

pi install ./pi-agent-skills
pi install npm:pi-agent-skills # after publishing

For a one-shot load without installing:

pi -e ./dist/extension.js

Use /reload in Pi to reload the extension after changes.

pi-skills CLI

The package ships a pi-skills bin for the install lifecycle; run it with npx pi-skills without a global install.

PI_SKILLS_AGENT_DIR overrides the agent directory for sandboxing and testing. PI_SKILLS_DEBUG enables extension debug logging (see Configuration).

Staleness compares only the numeric semver core; prerelease suffixes are stripped. For example, installed 0.2.0-beta.1 compares equal to 0.2.0.

All mutations delegate to the pi CLI (pi install, pi remove, and pi update); pi-skills never writes settings.json itself.

Configuration

• PI_SKILLS_ROOTS — colon-separated custom roots replacing the default roots.
• PI_SKILLS_SCRIPT_TIMEOUT_MS — script timeout in milliseconds (default: 30000).
• PI_SKILLS_DEBUG — enable one-line debug logs for root discovery, tool registration, activation completion, and available-skills block rendering (1, true, yes, or on).

PI_SKILLS_ROOTS override roots are discovered, reachable through the tools, and advertised in get_available_skills and the injected prompt block. Pi-native roots remain tool-reachable but are never re-advertised.

Security

A file enters the script registry allowlist when it starts with a shebang (#!) or is an executable ELF or Mach-O binary. Shebang scripts without the executable bit run through their absolute shebang interpreter and its optional single argument, as the kernel would (for example #!/usr/bin/env node runs /usr/bin/env node <script> <args>); a relative or empty interpreter keeps them out of the registry. The executable bit is not treated as a security boundary — the extension launches registered files itself — so a non-executable file that starts with #! and an absolute interpreter is runnable through that interpreter, subject to the same risk scan and approval prompt; the (via …) listing makes that visible. Executable text files without a shebang, such as reference markdown marked +x, are not scripts. The risk scanner heuristically checks four categories: network egress, writes outside the skill, privilege escalation, and shell environment mutation. This is a best-effort approval prompt, not a sandbox or security boundary; scripts still run locally with the user's privileges after approval. Detection patterns intentionally diverge from upstream opencode-agent-skills-md v2.0.1. Risk approval is fail-closed when UI is unavailable or approval is denied. Arguments are passed through spawn argument arrays with single-escape handling; no shell is used to construct the command. Advertised skill fields are sanitized before prompt injection.

Development

Requires Node.js >=22.19.0 and pnpm. Available scripts:

pnpm test
pnpm typecheck
pnpm lint
pnpm build

prepublishOnly runs pnpm build before publishing. Package metadata targets dist/extension.js and includes the build output, this README, and the license. The package is MIT-licensed. Unreviewed follow-ups are documented in odd/tasks/pi-agent-skills-extension.md.