Skip to content
agents.cli

Package the harness and hand it to a teammate

Everything you’ve built for stash so far - the damage-control extension, the /stash command and re-extract tool, the task gate, the onboarding Skill, the triage-fetch template - lives as files scattered across .pi/extensions/, .pi/skills/, .pi/prompts/. That’s fine as long as it’s just you working the codebase. It stops being fine the moment a teammate clones stash and asks how to get the same setup: right now the honest answer is “copy these six files from these three directories,” which is the kind of instruction that gets followed once and then quietly drifts.

A Pi package is the fix: the distribution unit that bundles Extensions, Skills, Prompt Templates, and Themes together and ships them as one installable thing, over infrastructure that already exists - npm or git. There’s no bespoke Pi registry to stand up; a package is just an npm package (or a git repo) that happens to carry a pi key in its package.json.

Installing one

Section titled “Installing one”
Terminal window
pi install npm:@foo/[email protected]
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo
pi install ./relative/path/to/package
pi install /absolute/path/to/package

Companion commands round out the lifecycle: pi remove, pi list, pi update (with --all, --extensions, --self flags for narrowing what gets refreshed). None of this is stash-specific machinery - it’s the same install surface for anything in the ecosystem, which is exactly why packaging your own stash harness this way means a teammate’s onboarding step becomes one command instead of a conversation.

The manifest: a pi key in package.json

Section titled “The manifest: a pi key in package.json”

Turning your .pi/ directory into a package that others can install is a matter of publishing it with a manifest pointing at the right folders:

package.json
{
  "name": "@you/stash-harness",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

The pi key is opt-in - its paths (which support globs and exclusions) tell Pi exactly where to find each resource type inside the package. If you skip the pi key entirely, Pi falls back to convention-based auto-discovery: an extensions/ directory for .ts/.js files, a skills/ directory for folders containing a SKILL.md, a prompts/ directory for .md files, a themes/ directory for .json files. For a package built around one coherent purpose - like a stash harness - the convention layout is usually enough; you’d reach for the explicit pi key mainly to be precise about paths or to exclude something from a directory that also holds unrelated files.

keywords: ["pi-package"] is the one line that matters if you ever want this discoverable beyond your own team - it makes the package findable through npm’s pi-package keyword search. You don’t need it for a private team package installed straight from git; it only matters if you’re publishing for strangers to find.

Once it’s published (or just pushed to a git remote your teammate can reach), the whole stash harness installs in one line:

Terminal window
pi install git:github.com/your-org/stash-harness

And because packages support per-resource filtering, a teammate who wants your Skill and templates but not your particular damage-control rules can install the package and disable just the extensions piece - the pieces don’t have to be all-or-nothing once they’re bundled.

Here’s how that bundling maps across tools that ship a similar idea - pick a tool to see what travels together and what ships on its own:

  • in the pluginSkillLands in the plugin’s skills/ directory.
  • in the pluginSubagentagents/<name>.md inside the plugin.
  • in the pluginHookShips in the bundle and registers on install.
  • in the pluginMCP serverServer config ships in the bundle.
  • in the pluginSlash commandNamespaced on install: /team-stack:pre-merge.
how it ships
/plugin marketplace add our-org/team-plugins
/plugin install team-stack@team-plugins
  • distScopes: user by default, --scope project commits the install to .claude/settings.json, and managed scope lets an org enforce it. The official claude-plugins-official marketplace is preinstalled.
  • noteInstalled plugins are copied into ~/.claude/plugins/cache/ - a plugin can’t reference files outside its own directory.

What’s actually out there

Section titled “What’s actually out there”

Pi has no bespoke registry. Discover packages through npm’s pi-package keyword search and the Pi community on Discord, then inspect source before installing. A few worth knowing about for landscape, not as an endorsement to install any of them blindly: a web-access bundle that adds search/fetch/GitHub-clone tools, a subagent task-delegation package, an MCP bridge (the community route into MCP support you saw referenced back when you built your first extension - still not core Pi, still a package like any other), and a cross-tool context/MCP plugin that also targets Claude Code and Gemini CLI. The shape of that list is itself informative: on Pi, “add MCP support” and “add subagent delegation” are both just pi install away, not built-in features you’re missing.

The same caution, one more time

Section titled “The same caution, one more time”

The docs put this plainly, and it applies to a package exactly as much as it applied to a single Skill a lesson ago: a Pi package runs with full system access, and its extensions execute arbitrary code. Installing someone’s pi-package is installing their code onto your machine with the same reach Pi itself has - no sandboxing layer specific to packages. Review before you install, especially anything pulled straight from a git URL rather than a name-checked npm publish. The convenience of pi install git:github.com/whoever/whatever is real; so is the fact that it will run whatever’s in that repo.

You’ve now got a stash harness that isn’t just yours anymore - it’s one pi install away for anyone on the project. But everything you’ve built up through this module still assumes one agent doing one thing at a time. stash has a job that doesn’t fit that shape: hundreds of saved URLs need re-extracting against the fixed adapter you shipped in the onboarding Skill, and that’s too much for a single context window to chew through, and too repetitive to babysit turn by turn. Next: build subagents from first principles.