Pi Agent: Package Management
Last updated: 2026-08-31
Packages are the "delivery boxes" for skills and tools — packaged up, one-click install, team sharing.
1. What Are Pi Agent Packages
A Package is a distributable unit of skills, tools, templates, and config:
TEXT
📖 Display only
Package vs Extension vs Skill
├── Skill → Single capability (e.g., code_review)
├── Extension → Plugin (tools + skills + hooks)
└── Package → Distribution carrier (multiple extensions + skills + templates)
2. Package Commands
(1) Search
BASH
pi-agent pkg search code-review
pi-agent pkg search --category devops
pi-agent pkg search --author alice
(2) Install
BASH
pi-agent pkg install code-review-tools
pi-agent pkg install devops-toolkit@1.2.0
pi-agent pkg install git+https://github.com/user/my-pkg.git
(3) Manage
BASH
pi-agent pkg list
pi-agent pkg info code-review-tools
pi-agent pkg update
pi-agent pkg update devops-toolkit
pi-agent pkg remove code-review-tools
3. Creating Packages
(1) Package Structure
TEXT
📖 Display only
my-dev-tools/
├── pkg.yaml
├── tools/
│ ├── git_helper.py
│ └── docker_tool.py
├── skills/
│ ├── code_review.yaml
│ └── deploy.yaml
├── templates/
│ └── commit_msg.yaml
└── tests/
└── test_tools.py
(2) pkg.yaml
YAML
name: my-dev-tools
version: "1.0.0"
description: "Development toolset"
author: "Alice"
license: "MIT"
repository: "https://github.com/alice/my-dev-tools"
min_pi_agent_version: "0.8.0"
dependencies:
- git-tools>=1.0.0
tools:
- tools/git_helper.py
- tools/docker_tool.py
skills:
- skills/code_review.yaml
- skills/deploy.yaml
categories:
- development
- devops
tags:
- git
- docker
- code-review
4. Version Management
(1) Semantic Versioning
TEXT
📖 Display only
Major.Minor.Patch
1.0.0 -> 1.0.1 -> 1.1.0 -> 2.0.0
Major: incompatible API changes
Minor: backward-compatible new features
Patch: backward-compatible bug fixes
(2) Version Constraints
YAML
dependencies:
- git-tools>=1.0.0 # 1.0.0 or higher
- docker-tools~=2.1 # 2.1.x (compatible with 2.1)
- utils>=1.0,<2.0 # 1.x series
5. Publishing Packages
BASH
pi-agent pkg validate my-dev-tools
pi-agent pkg test my-dev-tools
pi-agent pkg build my-dev-tools
pi-agent pkg publish my-dev-tools
pi-agent pkg install my-dev-tools
6. Package Repositories
(1) Official Repo
BASH
pi-agent pkg search --repo official
(2) Third-Party Repos
YAML
package_repos:
- name: official
url: "https://pkg.pi-agent.dev"
- name: company
url: "https://pkg.internal.company.com"
auth: token
FAQ
Q Package vs extension?
A Packages are distribution carriers; extensions are runtime plugins. A package can contain multiple extensions. Packages focus on "distribution and versioning"; extensions on "functionality loading."
Q Dependency conflicts?
A Pi Agent uses a pip-like dependency resolver. If conflicts can't be auto-resolved, it prompts for manual version specification.
Q Safe updates?
A Minor and patch updates are backward-compatible. Major updates need CHANGELOG review.
Summary
- Packages are distributable units of skills, tools, templates
- pkg.yaml defines metadata with dependency declarations
- Semantic versioning; constraint syntax similar to pip
- Official and private repositories supported
- Complete search, install, update, uninstall, publish workflow
Exercises
- Basic (Difficulty: ⭐): Search and install a community package, use its skill.
- Intermediate (Difficulty: ⭐⭐): Create a package with 2 tools and 1 skill, test locally.
- Advanced (Difficulty: ⭐⭐⭐): Set up a private package repo, publish and install internal tool packages.
