@spences10/pi-skills

Manage the skills Pi is allowed to discover and use. pi-skills adds profiles, enable/disable rules, GitHub skill search/install, and update flows so teams can curate reusable Agent Skills instead of hand-editing skill directories.

Installation

pi install npm:@spences10/pi-skills

Local development from this monorepo:

pnpm --filter @spences10/pi-skills run build
pi install ./packages/pi-skills
# or for one run only
pi -e ./packages/pi-skills

What it does

Pi already has native skill discovery. This package adds a management layer for Pi skill ecosystems:

• discovers Pi-native skills in $PI_CODING_AGENT_DIR/skills (default: ~/.pi/agent/skills)
• discovers project skills recursively in .agents/**/SKILL.md, .agents/skills/**/SKILL.md, .pi/skills/**/SKILL.md, and root .pi/skills/*.md files
• searches public GitHub SKILL.md files through gh skill search
• previews GitHub-hosted skills through gh skill preview
• installs GitHub-hosted skills through gh skill when GitHub CLI support is available
• checks or applies GitHub skill updates through gh skill update
• provides a task-oriented /skills command with Installed, Available, Add / import, and Advanced sections
• discovers new skills in repositories represented by existing gh skill installs; preview and explicit confirmation are required before installation
• composes the public @spences10/pi-skill-importer API for external plugin import, provenance, sync/rebind, and metadata-owned deletion

Commands

/skills
/skills enable <key|name|pattern>
/skills disable <key|name|pattern>
/skills search <query>
/skills add <owner/repo> <skill[@ref]> [--pin ref|--scope project|--dir path|--force]
/skills update --dry-run
/skills update --all
/skills profile create <name>
/skills profile use <name>
/skills refresh
/skills defaults all-enabled
/skills defaults all-disabled

GitHub search, installs, and updates require GitHub CLI gh v2.90.0 or newer with preview gh skill support. The extension delegates GitHub source tracking, pinning, preview/update metadata, and tree-SHA comparison to gh skill instead of maintaining a parallel cache.

With a UI available, /skills opens four task-oriented sections:

• Installed — search and enable/disable skills, inspect details, or choose a separately confirmed delete
• Available — reconcile installed gh skill inventory with known repository trees, preview newly published skills, and dry-run updates
• Add / import — add from GitHub or review/import/sync/delete compatible external plugin skills
• Advanced — profiles, default policy, manual refresh, and diagnostic browsing

GitHub installation follows preview → explicit confirmation → install → Pi reload; discovery never auto-installs or activates an upstream skill. Importer sync/rebind continues to refuse overwriting local changes, and importer deletion only removes metadata-owned copies. Existing subcommands remain available for headless and scripted use.

Skill enablement

The extension treats profiles as named skill sets. The active profile contains include/exclude rules for skill names, keys, sources, or paths; * wildcards are supported. Legacy top-level enablement is migrated into the default profile on load.

The extension contributes enabled managed skill paths during Pi resource discovery. Project skills are enabled by default when project resources are allowed, and can still be excluded by profile rules.

Profiles can also be selected by context without hardcoding project names in code. Contexts support cwd, github_org, and github_repo predicates; matching any configured predicate activates the profile. Camel-case githubOrg and githubRepo are accepted on load and normalized to snake case. Example:

{
	"contexts": [
		{
			"name": "client-workspace",
			"profile": "client-projects",
			"when": {
				"cwd": "~/repos/client-projects/*",
				"github_org": "client-org",
				"github_repo": ["client-org/app"]
			}
		}
	],
	"profiles": {
		"default": { "include": [], "exclude": [] },
		"client-projects": {
			"extends": ["default"],
			"include": ["client-*", "project:*"],
			"exclude": []
		}
	}
}

In a custom harness such as my-pi, this can be combined with a resource filter to enforce disabled skills. In vanilla pi, Pi's own default skill discovery can still load skills from default locations, so use pi config or settings filters when you need hard disable semantics.

Using from a custom harness

import skills, { create_skills_manager } from '@spences10/pi-skills';

// pass `skills` as an ExtensionFactory to your Pi runtime
const manager = create_skills_manager();

my-pi imports this package directly and uses create_skills_manager() to enforce its built-in skill toggle behavior.

Development

Package scripts build transitive workspace dependencies first, then run local tools through Vite+ with vp exec.

pnpm --filter @spences10/pi-skills run check
pnpm --filter @spences10/pi-skills run test
pnpm --filter @spences10/pi-skills run build

License

MIT