pi-skill-profiles

A Pi extension for choosing a skill profile for the current task. Profiles do not change shared project files or create skill symlinks.

Why profiles?

Separate skill storage from activation. Keep skills in versioned repository locations, then use profiles to expose only those needed for the current session. Start Pi with --no-skills to prevent automatically discovered skills from becoming implicit shared configuration.

Whether working alone or on a team, skill needs vary by person, task, and modality. Profiles make activation session-specific, allowing project and global skills to be selected without making all discovered skills implicit defaults.

Install

Install this directory as a Pi package during development:

pi install /absolute/path/to/pi-skill-profiles

To install the published package:

pi install npm:pi-skill-profiles

Configure profiles

Global profiles live in ~/.pi/agent/skill-profiles.json. Trusted projects can extend profiles by name in <project-root>/.pi/skill-profiles.json.

Keep project profile configuration local by adding .pi/skill-profiles.json to .gitignore. Check it in only when the team intentionally wants shared profile definitions.

{
  "default": ["skills/task-preflight", "~/.agents/skills/implementation-shape"],
  "cloudflare": ["skills/task-preflight", "/absolute/path/to/cloudflare", "/absolute/path/to/wrangler/SKILL.md"]
}

The combined configuration must include default. Its entries load with every selection.

When you select another profile, entries load in this order:

1. Project selected profile
2. Global selected profile
3. Project default profile
4. Global default profile

Selecting default loads only the project and global default entries.

Skills with the same frontmatter name are deduplicated. The first one wins. This lets a project extend a global profile or replace specific global skills without copying the full profile.

Global relative paths start at ~/.pi/agent/. Project relative paths start at the project root. Absolute paths and paths starting with ~/ also work. Each entry must point to a SKILL.md file or a directory that contains one.

All entries in the selected profile are checked before it loads. If any entry is missing or invalid, the profile exposes no skills. This includes entries that a higher-priority skill would replace.

Start Pi with profile isolation

Use --no-skills to stop Pi from discovering skills outside the selected profile:

pi --no-skills
pi --no-skills --skill-profile cloudflare

You can add an alias for profiled sessions:

alias pi-profile='pi --no-skills'

The alias should add only --no-skills. Profile definitions stay in the JSON files.

Without --no-skills, Pi also loads normally discovered skills, so the profile is not isolated.

Switch profiles

Pi selects a profile in this order:

1. --skill-profile <name>
2. The saved selection for the current session branch
3. default

/skill-profile
/skill-profile cloudflare

The first command opens a selector. A successful switch is saved to the current session branch and reloads Pi resources. The footer shows the active profile, effective skill count, and approximate catalog size, for example skills:cloudflare [9 skills · ~1.2k tok]. The bracketed catalog details are dimmed. The catalog estimate covers the skill names and descriptions Pi loads at startup, not the full instructions loaded when a skill is used.

A profile set with --skill-profile is fixed for that Pi process. To switch profiles, restart without the flag.

Trust and profile state

Pi reads project profiles only for trusted projects. An untrusted project cannot extend, replace, or invalidate global profiles.

The extension saves the selection as a skill-profile-state custom session entry. Reloading, resuming, forking, cloning, or switching sessions restores the profile from the active session branch. Each session branch keeps its own selection.

The extension never writes profile files or changes .pi/skills, .agents/skills, or symlinks.

Development

npm install
npm run typecheck
npm test

License

MIT.