pi-skillful

pi-skillful

Make Pi skills easier to invoke, curate, and control without editing their source files.

pi-skillful provides four focused upgrades:

• Progressive skill loading: discover .agents/skills/ from every ancestor directory (like AGENTS.md), not just within the git repo boundary.
• Inline skill invocation: invoke one or more skills anywhere in a prompt with /skill:name.
• Skill prompt visibility: choose which skills are hidden from the model's automatic skill-discovery prompt while keeping them explicitly invokable.
• Session skill toggles: assign up to nine skills to number slots and toggle model visibility while writing a prompt.

[!WARNING] Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.

Features

Progressive skill loading

Pi discovers .agents/skills/ directories in ancestor folders, but stops at the git repo root — skills above the repo boundary are invisible. pi-skillful removes that boundary by walking the full ancestor chain to the filesystem root, mirroring how AGENTS.md context files work.

No configuration needed. When a git repo is detected, pi-skillful automatically contributes .agents/skills/ directories from parent directories above the repo root (excluding ~/.agents/skills/, which Pi already loads globally). In projects without a git repo, Pi already walks to the filesystem root and this feature has no effect.

Skill name collisions follow Pi's first-wins rule: skills discovered closer to the working directory take precedence over skills with the same name found higher up.

Inline skill invocation

Vanilla Pi expands /skill:name only when it appears at the beginning of the prompt. pi-skillful expands known skill markers anywhere in the prompt, including multiple skills:

Use /skill:code-security and /skill:semgrep to review this change.

The extension replaces each known marker with that skill's SKILL.md content before Pi's built-in skill/template expansion runs.

Skill prompt visibility

Hide skills from the <available_skills> section of the system prompt without editing each skill's disable-model-invocation frontmatter.

Hidden skills:

• appear in the startup [Skills] list in the theme's error color, while visible skills appear dimmed;
• are not advertised to the model for automatic skill selection;
• remain loaded by Pi;
• remain available for explicit invocation with /skill:name, including inline invocation.

Skills bundled in Pi packages are never affected by skillful; only global and project skills can be hidden or toggled.

Configuration is stored under the skillful key in Pi settings:

{
  "skillful": {
    "hiddenSkills": ["pdf", "xlsx"]
  }
}

Supported scopes:

• Global: ~/.pi/agent/settings.json
• Project: .pi/settings.json

Project visibility and toggle slots inherit global settings until changed in the Project tab. When either is changed, Pi Skillful writes a full project override containing both hiddenSkills and toggleSlots. If the project state is changed back to match global, those project override keys are removed so the project inherits global again.

Open the menu with:

/skillful

The menu lists configurable skills alphabetically. Toggle a skill off or on in the active scope. Use the Global/Project tabs to choose which settings file to edit. In the Project tab, inherited on/off values are shown normally; project overrides are highlighted. Press 1 through 9 on a selected skill to assign or clear that scope's session toggle slot. Visibility and toggle slots are independent.

Project settings are read and the Project tab is available only when Pi trusts the current project. In an untrusted project, pi-skillful ignores .pi/settings.json and exposes only global settings.

When the project settings file contains only skillful settings and the project override is removed, .pi/settings.json is deleted instead of leaving an empty settings file behind.

Session skill toggles

Assign skills to up to nine prompt-editor slots with JSON settings:

{
  "skillful": {
    "hiddenSkills": ["pdf", "xlsx"],
    "toggleSlots": {
      "1": "typescript",
      "2": "code-review",
      "3": "git"
    },
    "toggleModifier": "alt"
  }
}

Configured slots appear on the prompt editor's top border as N skill-name. Project toggleSlots, when defined as part of a project override, replace global toggleSlots; otherwise global slots are used and shown in the Project tab. Long names are truncated per slot when needed so all configured slot numbers remain visible. Active slots use the theme accent color; inactive slots use the muted color. Press alt+1 through alt+9 by default to toggle a slot for the current session only. Only the configured modifier and assigned slot numbers are consumed while the prompt editor has focus; no modifier-number keys are reserved when no slots are configured.

toggleModifier defaults to "alt". Supported values are "alt", "ctrl", "ctrl+shift", "alt+shift", "ctrl+alt", and "ctrl+alt+shift". Change it if your terminal reserves alt+number shortcuts. An explicitly configured project value takes precedence over the global value, including explicit "alt". Unsupported explicit values fall back to "alt" in that scope.

On app startup, non-hidden skills are active and hidden skills are inactive. Within a running Pi process, /new preserves the current toggle state for the new session. Resuming, forking, cloning, reloading, or restarting Pi resets toggle state from settings. Inline /skill:name invocation remains explicit and works even when that skill is inactive. Skills bundled in Pi packages are never modified by these toggles.

Installation

Install from npm:

pi install npm:pi-skillful

Install project-locally with Pi's -l flag:

pi install -l npm:pi-skillful

During local development from this monorepo:

pi install /path/to/pi-mono/packages/pi-skillful

For a one-off test run without installing:

pi -e /path/to/pi-mono/packages/pi-skillful

Usage

• Start Pi in a project with this package installed.
• Run /skillful.
• Select the Global or Project tab.
• Toggle skills on/off.
• Send a prompt normally, or explicitly invoke hidden skills with /skill:name anywhere in the prompt.

Example:

Please analyze this using /skill:code-security, then summarize the risk.

Development

This package is source-distributed. Pi loads the TypeScript extensions directly via its extension loader.

Requirements:

• Node.js >= 20.6.0
• npm for local development commands

Common commands:

npm install
npm run check
npm test
npm run pack:dry-run

Contributing

Contributions are welcome. See CONTRIBUTING.md for development workflow and pull request guidelines.

Security

Please report security issues privately. See SECURITY.md.

License

MIT. See LICENSE.