pi-nested-skills

A Pi extension that discovers skills recursively and provides convenient aliases for nested skill directories.

中文文档

Features

• Recursively discovers SKILL.md files below one or more configurable skill roots.
• Supports package-style aliases such as /development:code-reviewer and /design:icons.favicon.
• Keeps Pi's native skill loader responsible for frontmatter validation and skill-body expansion; this package does not duplicate read compatibility or skill expansion.
• Extends the native slash-command completion list and preserves built-in Pi command suggestions.
• Provides /skills to list discovered aliases.
• Provides /config:nested-skills to edit the skill roots through the normal TUI input; use reset for the default skills root.
• Contributes discovered skill files through Pi's resources_discover event.
• Uses pi-extensions-i18n for all user-visible messages.

Install

pi install npm:pi-nested-skills

Then run /reload in Pi.

Configure skill roots

Start from config.example.json and write it to:

<pi-agent-dir>/extensions/pi-nested-skills/config.json

<pi-agent-dir> is Pi's configured agent directory, normally ~/.pi/agent. The PI_CODING_AGENT_DIR override is respected by Pi and by this extension.

{
  "skillRoots": [
    "~/shared-skills",
    "skills"
  ]
}

A relative root is resolved relative to the Pi agent directory. Each direct child of a root is treated as a skill package, and every visible descendant containing SKILL.md is discovered. A root containing SKILL.md itself is also accepted as one package.

Use /config:nested-skills to change the roots in the normal TUI input. Enter comma-separated paths, or use reset for the default root. Run /reload after saving.

Aliases and native expansion

For a skill at development/code-reviewer/SKILL.md, the extension offers:

/development:code-reviewer [arguments]
/skill:development.code-reviewer [arguments]

The input hook converts the alias to Pi's native /skill:<frontmatter-name> form. Pi then reads the skill body and resolves relative references using its normal skill mechanism. If a frontmatter name is shared by multiple discovered skills, the name-only native form is not guessed; use an unambiguous package/path alias.

Use /skills to inspect the complete list. Type / to search the merged native and nested-skill completion candidates.

Portability and privacy

The package does not access credentials, make network requests, start processes, or assume a particular home directory. It follows Pi's agent-directory setting and accepts explicit roots for project or team layouts.

Requirements

• Node.js 22 or newer.
• Pi >=0.80.0.

License

MIT — see the repository license.