pi-multi-skill

Load multiple skills at once in pi via the /skills command — with preset bundles, token-efficient load modes, BMAD auto-routing, and Claude Code-style orchestration.

Version 1.3.0 — skill chaining, bundle presets, conflict resolution, parallel dispatch, activation stats, /skills-last, /skills-setup, and bundle attribution in pi-usage.

🚀 Install

⚠️ Use pi install — NOT npm install. Plain npm install only drops files in node_modules. Pi does not scan that folder, so the package is never detected and /skills won't appear. You must register it with pi install so it lands in "packages" in ~/.pi/agent/settings.json.

pi install npm:@zaganjade/pi-multi-skill

Then inside pi:

/reload

Verify it loaded:

pi list          # should show npm:@zaganjade/pi-multi-skill

Type / — /skills should appear in slash autocomplete.

Don't do this (common mistake — package installs but pi ignores it):

npm install -g @zaganjade/pi-multi-skill   # ❌ pi will not detect this

Why?

Pi's built-in /skill:name loads one skill at a time. When you need several skills working together (e.g. bmad-master + analyst + pm, or systematic-debugging + test-driven-development), invoking them one by one is slow and easy to forget.

This extension chains skills in a single command with:

• Preset bundles (@bmad-planning, @debug, …)
• Smart ordering (process → planning → implementation)
• Load modes to control token cost (--meta, --lazy, --full)
• Universal discovery including Claude Code plugin skills and Cursor skills
• BMAD --auto phase routing from workflow status files

Quick start

/skills @debug --meta Fix the failing auth tests
/skills @bmad-planning --meta Buat PRD untuk fitur notifikasi
/skills bmad-master,developer Implement user story US-042
/skills bmad-master /workflow-status
/skills @bmad-planning --auto
/skills @cc-feature --parallel Build API | Write tests | Update docs
/skills-stats                         → activation statistics
/skills-last                          → repeat last activation
/skills-setup                         → bundle install guide
/skills                              → help + list all skills & bundles

Commands

| Command | Description | |---------|-------------| | /skills | Chain skills/bundles — flags, embedded commands, --auto, --parallel | | /skills-stats | Activation statistics (~/.pi/agent/multi-skill-stats.json) | | /skills-last | Repeat last activation (optional --meta / --lazy / --full / --parallel) | | /skills-setup | Bundle readiness on this machine + BMAD/Superpowers install guide |

Features

v1.3.0

| Feature | Description | |---------|-------------| | /skills-last | Replay the previous /skills line; flags can override load mode | | BMAD status inject | <bmad_status> preloaded for /workflow-status, --auto, bmad-master | | Bundle attribution | Sets bundles="@name" on <manually_attached_skills> for pi-usage tracking | | /skills-setup | Reports which preset bundles are usable + how to install missing skills |

Skill chaining

| Feature | Description | |---------|-------------| | Comma-separated skills | /skills skill1,skill2,skill3 [instructions] | | Preset bundles | /skills @bundle-name expands to a curated skill set | | Mixed input | Combine bundles and individual skills: /skills @debug,frontend-design | | Inline instructions | Text after the skill list is passed inside <user_query> | | Legacy formats | /skills:a,b (colon + comma) and /skill:a+b (colon + plus) still work |

Load modes (token efficiency)

| Flag | What gets sent | Best for | |------|----------------|----------| | --meta | Name, description, available commands only | Exploration, planning, large bundles | | --lazy | Short intro + commands + “load references on demand” | Implementation workflows | | --full | Complete SKILL.md body (default) | Rigid skills (TDD, debugging) |

Bundles can set a default mode (e.g. @bmad-planning defaults to --meta).

Smart ordering

Skills are sorted automatically before injection:

1. Process — using-superpowers, brainstorming, systematic-debugging, bmad-master, …
2. Planning — analyst, pm, architect, ux-designer, …
3. Implementation — domain and execution skills

User instructions always take precedence over skill guidance. Skills with conflicting conflicts_with frontmatter are deduplicated automatically (lower-priority skill skipped).

Parallel dispatch (v1.2)

When --parallel is used with pi-subagents installed, the message includes a <parallel_dispatch> block with a ready-to-use JSON template for the subagent tool:

/skills @cc-feature --parallel Build API | Write tests | Update docs

Pipe-separated tasks (|) become independent parallel subagent jobs. Without pi-subagents, a fallback notice prompts sequential execution.

Skill conflict resolution (v1.2)

Skills can declare conflicts_with in frontmatter. After smart ordering, conflicting skills are skipped with an info notification:

Skipped test-driven-development (conflicts with systematic-debugging)

Per-skill token budget (v1.2)

Skills can set token_budget: meta|lazy|full in frontmatter. When a bundle uses --lazy, individual skills can still override to --full (e.g. rigid TDD/debug skills).

Activation stats (v1.2)

Every /skills activation is recorded to ~/.pi/agent/multi-skill-stats.json. View with:

/skills-stats

Tracks load modes, top bundles, skills-per-activation buckets, and recent history.

Command passthrough

Embed a slash command after the skill list — it is wrapped in <embedded_command> and the agent runs that workflow after loading the skill:

/skills bmad-master /workflow-status
/skills developer /dev-story STORY-042
/skills analyst /product-brief

After typing the skill name and a space, autocomplete suggests commands from the skill's Available Commands section (e.g. /workflow-status, /dev-story).

Note: BMAD commands like /workflow-status are skill workflows executed by the agent — not separate Pi slash commands. You will see a notification (Loading bmad-master → /workflow-status) and the agent turn starts with the skill + embedded command injected.

BMAD --auto

Reads docs/bmm-workflow-status.yaml (and bmad/config.yaml for project level) and loads skills for the current phase:

| Detected phase | Skills loaded | |----------------|---------------| | Analysis | bmad-master, analyst | | Planning | bmad-master, analyst, pm | | Solutioning | bmad-master, architect, ux-designer | | Implementation | bmad-master, developer, scrum-master |

/skills --auto
/skills @bmad-planning --auto

Universal skill discovery

Skills are found from all of these sources (merged, deduplicated by name):

| Source | Path / mechanism | |--------|------------------| | Pi registered skills | pi.getCommands() (source: "skill") | | Pi defaults | ~/.pi/agent/skills, .pi/skills | | Settings skill paths | "skills" array in ~/.pi/agent/settings.json | | Claude Code plugins | ~/.claude/plugins/cache/**/skills/ (Superpowers, etc.) | | Cursor skills | ~/.cursor/skills-cursor/ |

This means bundles like @debug and @cc-feature work even when Superpowers skills live in the Claude plugin cache rather than ~/.claude/skills.

Pi-native skill display

Pi collapses user messages only when the entire message matches its native skill envelope:

<skill name="skill-a, skill-b" location="pi-multi-skill">
  <manually_attached_skills count="2" bundles="@debug">
    …priority rules…
    <skill name="skill-a" location="/path/to/SKILL.md">…</skill-block>
    <skill name="skill-b" location="/path/to/SKILL.md">…</skill-block>
    <user_query>Your instructions here</user_query>
  </manually_attached_skills>
</skill>

Your instructions here

• 1 skill, no extras → single native block → [skill] skill-name
• 2+ skills (or bundles/instructions) → outer native block hides all inner content → [skill] a, b, c (Ctrl+O to expand)
• The user's free-text instructions are appended AFTER </skill> as Pi's userMessage tail, so they render as a normal visible message below the collapsed header: [skill] a, b (ctrl+o to expand) + your instructions.
• Inner <manually_attached_skills bundles="…"> is preserved for pi-usage bundle attribution

Why inner blocks close with </skill-block> and instructions live outside the envelope? Two constraints shaped this. First, Pi's display parser matches the outer envelope with a non-greedy regex and cannot tell a nested </skill> apart from the envelope's own closing tag — with nested </skill>, any trailing section caused the parser to split at the last inner </skill> and leak <user_query>…, </manually_attached_skills>, and the outer </skill> into the rendered user message as raw tags. Inner blocks therefore open with <skill name="…"> (kept so pi-usage still attributes each skill via /<skill\s+name="([^"]+)"/g) but close with the non-colliding </skill-block>, which neither parser's regex can match. Second, so the user's typed instructions stay visible (not hidden inside the collapsed block) while the skill content collapses, instructions are placed after </skill>\n\n as plain text — exactly Pi's native userMessage tail. Covered by node --test test/parse-leak.test.mjs.

Session hints

After each user turn, the extension may suggest a relevant bundle (non-blocking info notification):

| Keywords detected | Suggested bundle | |-------------------|------------------| | failing tests, bug, error | @debug | | PRD, tech spec | @bmad-planning | | architecture, API design | @bmad-solutioning | | implement, user story | @bmad-build | | new feature, build component | @cc-feature |

Skill registry

On every session_start, rebuilds ~/.pi/agent/skill-index.json with metadata (name, type, module, commands, location) for all discovered skills.

Deduplication

When combining skills that share content (e.g. multiple skills with <SUBAGENT-STOP> or Superpowers skill-check rules), duplicate sections are stripped automatically.

pi-usage integration

Works with pi-usage:

• Every skill in a multi-skill activation appears separately in Skills
• Preset bundles (@debug, @bmad-planning, …) appear in Bundles when bundles="@name" is set on the wrapper
• Tool and plugin breakdowns unchanged — independent characteristics like Claude Code

Preset bundles

Built-in bundles are optional presets — they require BMAD and/or Superpowers skills to be installed separately. Run /skills-setup to check what's available on your machine.

Expand with @name:

| Bundle | Skills | Default mode | Requires | |--------|--------|--------------|----------| | @bmad-planning | bmad-master, analyst, pm | --meta | BMAD Method | | @bmad-solutioning | bmad-master, architect, ux-designer | --meta | BMAD Method | | @bmad-build | bmad-master, developer, scrum-master | --lazy | BMAD Method | | @cc-feature | using-superpowers, brainstorming, … | --lazy | Superpowers | | @debug | systematic-debugging, test-driven-development | --full | Superpowers |

Autocomplete shows coverage per bundle, e.g. (2/3) or (0/3 — install required).

Without BMAD or Superpowers

You can still use pi-multi-skill:

/skills frontend-design,motion-design Build landing page
/skills-setup                    → check bundle status + install guide

Create your own bundles with only skills you have:

{
  "bundles": {
    "my-stack": {
      "description": "Skills I actually installed",
      "skills": ["frontend-design", "create-rule"],
      "default_mode": "meta"
    }
  }
}

Save as ~/.pi/agent/skill-bundles.json then use /skills @my-stack.

Custom bundles

Create ~/.pi/agent/skill-bundles.json, .pi/skill-bundles.json, or the YAML equivalents (skill-bundles.yaml / .pi/skill-bundles.yaml):

{
  "bundles": {
    "my-team-planning": {
      "description": "Custom team planning workflow",
      "skills": ["bmad-master", "analyst", "pm"],
      "order": "process-first",
      "default_mode": "meta"
    }
  }
}

YAML format (same fields):

bundles:
  my-team-planning:
    description: Custom team planning workflow
    skills:
      - bmad-master
      - analyst
      - pm
    order: process-first
    default_mode: meta

| Field | Values | Description | |-------|--------|-------------| | description | string | Shown in /skills help and autocomplete | | skills | string[] | Skill names to load when bundle is expanded | | order | process-first · explicit · alpha | Sort order (default: process-first) | | default_mode | meta · lazy · full | Applied when no --meta/--lazy/--full flag is passed |

See skill-bundles.example.json and skill-bundles.example.yaml.

Custom bundles merge with built-in presets; same name overrides the preset.

Flags reference

| Flag | Description | |------|-------------| | --meta | Minimal content — name, description, commands | | --lazy | Summary + on-demand reference loading | | --full | Full SKILL.md body (default) | | --auto | BMAD phase detection from workflow status | | --parallel | Parallel subagent dispatch — pipe-separated tasks: Task A \| Task B | | /skills-stats | Show activation statistics (modes, bundles, recent history) | | /skills-last | Repeat last /skills activation | | /skills-setup | Bundle prerequisites and install guide |

Install

Use pi install, not plain npm install. Pi registers packages in settings.json under "packages" and loads extensions from the pi.extensions manifest.

pi install npm:@zaganjade/pi-multi-skill
/reload

Quick test without persisting to settings:

pi -e npm:@zaganjade/pi-multi-skill

From GitHub (monorepo):

pi install git:github.com/ZaganJade/pi-extension

Local development:

pi install ./multi-skill
/reload

Verify:

pi list
# should show: npm:@zaganjade/pi-multi-skill

Troubleshooting

| Symptom | Fix | |---------|-----| | /skills not in autocomplete | Run pi install npm:@zaganjade/pi-multi-skill, then /reload | | No skills found for: … | Ensure skill exists in a discovery path (see table above). Superpowers skills are found via Claude plugin cache automatically. | | Bundle skill missing | Run /skills with no args — check skill appears in list. Add custom path to "skills" in settings if needed. | | Installed with npm install -g but pi ignores it | Use pi install npm:@zaganjade/pi-multi-skill instead | | Added npm:... to "extensions" in settings | Wrong key for npm packages — use "packages", or run pi install | | Command shows as /skills:2 | Two copies loaded (local + npm). Remove duplicate from extensions or packages | | Extension listed but disabled | Run pi config and enable the extension resource | | --auto loads wrong skills | Ensure docs/bmm-workflow-status.yaml exists and reflects current phase |

How it works

flowchart LR
  CMD["/skills @bundle --meta /cmd"]
  DISC["discover.ts"]
  PARSE["parse-args.ts + bundles.ts"]
  ORDER["metadata.ts sort"]
  BUILD["build.ts"]
  SEND["sendUserMessage()"]

  CMD --> PARSE --> DISC --> ORDER --> BUILD --> SEND

1. Parse — extract skill names, flags, embedded command, instructions
2. Expand — resolve @bundle → skill name list; --auto → BMAD phase skills
3. Discover — merge skills from pi, settings paths, Claude plugins, Cursor
4. Order — sort by process → planning → implementation priority
5. Build — render each skill in the chosen load mode; deduplicate shared sections
6. Send — inject <manually_attached_skills> wrapper via pi.sendUserMessage()

Module layout

| File | Purpose | |------|---------| | src/index.ts | /skills, /skills-stats, /skills-last, /skills-setup; events; orchestration | | src/discover.ts | Universal skill discovery (pi + Claude plugins + Cursor) | | src/bundles.ts | Built-in presets + user JSON/YAML bundle config | | src/bundle-status.ts | Bundle readiness assessment + setup report | | src/metadata.ts | Frontmatter parsing (via pi), priority sorting | | src/build.ts | Message builder — load modes, deduplication, parallel dispatch, bundles= attr | | src/conflicts.ts | conflicts_with resolution | | src/subagents.ts | pi-subagents detection + <parallel_dispatch> template | | src/stats.ts | Activation tracking → multi-skill-stats.json | | src/yaml-bundles.ts | Minimal YAML parser for bundle config | | src/bmad-auto.ts | BMAD --auto phase routing | | src/bmad-status.ts | BMAD workflow status block for status/auto/master | | src/completions.ts | Slash autocomplete for skills, bundles, embedded commands | | src/parse-args.ts | Flag parsing, embedded command extraction | | src/registry.ts | ~/.pi/agent/skill-index.json persistence | | src/suggestions.ts | Context-aware bundle hints on turn_end | | src/types.ts | Shared TypeScript types | | skill-bundles.example.json | Example custom bundle config (JSON) | | skill-bundles.example.yaml | Example custom bundle config (YAML) |

Changelog

v1.3.0

• /skills-last — repeat last activation (optional --meta/--lazy/--full/--parallel override)
• BMAD status pre-inject — <bmad_status> block for /workflow-status, --auto, and bmad-master
• Bundle attribution in pi-usage — bundles="@name" on <manually_attached_skills>

v1.2.0

• Skill conflict resolution via conflicts_with frontmatter
• Per-skill token_budget override in frontmatter
• Structured <parallel_dispatch> block with JSON template for pi-subagents
• Pipe-separated parallel tasks: --parallel Task A | Task B
• Activation stats (/skills-stats, multi-skill-stats.json)
• YAML bundle config (skill-bundles.yaml)
• Richer skill index (pairsWith, conflictsWith, tokenBudget)

v1.1.0

• Preset bundles (@bmad-planning, @debug, @cc-feature, …)
• Load modes: --meta, --lazy, --full
• Smart skill ordering (Superpowers priority)
• BMAD --auto phase routing
• Command passthrough (/skills bmad-master /workflow-status)
• Universal discovery (Claude plugin cache + Cursor skills)
• <manually_attached_skills> message wrapper
• Session bundle suggestions on turn_end
• Skill registry (skill-index.json)
• Content deduplication across combined skills
• Multi-skill attribution in pi-usage

v1.0.x

• Comma-separated /skills a,b,c [instructions]
• Autocomplete with descriptions
• Legacy /skills: and /skill:+ formats