docs(coding-agent): remove duplicate packages content from extensions.md

Replace 130 lines of duplicate content with link to packages.md
This commit is contained in:
Mario Zechner 2026-01-26 11:44:56 +01:00
parent 930207130b
commit d726c81faf

View file

@ -127,140 +127,7 @@ Additional paths via `settings.json`:
}
```
Use `pi install`, `pi remove`, `pi list`, and `pi update` to manage packages:
```bash
pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo # raw URLs work too
pi remove npm:@foo/bar
pi list # show installed packages
pi update # update all non-pinned packages
```
**Package filtering:** By default, packages load all resources (extensions, skills, prompts, themes). To selectively load only certain resources:
```json
{
"packages": [
"npm:simple-pkg",
{
"source": "npm:shitty-extensions",
"extensions": ["extensions/oracle.ts", "extensions/memory-mode.ts"],
"skills": ["skills/a-nach-b"],
"themes": [],
"prompts": []
}
]
}
```
- Omit a key to load all of that type from the package
- Use empty array `[]` to load none of that type
- Paths are relative to package root
- Use `!pattern` to exclude (e.g., `"themes": ["!funky.json"]`)
- Glob patterns supported via minimatch (e.g., `"extensions": ["**/*.ts", "!**/deprecated/*"]`)
- **Layered filtering:** User filters apply on top of manifest filters. If a manifest excludes 10 extensions and user adds one more exclusion, all 11 are excluded.
**Package deduplication:** If the same package appears in both global (`~/.pi/agent/settings.json`) and project (`.pi/settings.json`) settings, the project version wins and the global one is ignored. This prevents duplicate resource collisions when you have the same package installed at both scopes. Package identity is determined by:
- **npm packages:** Package name (e.g., `npm:foo` and `npm:foo@1.0.0` are the same identity)
- **git packages:** Repository URL without ref (e.g., `git:github.com/user/repo` and `git:github.com/user/repo@v1` are the same identity)
- **local paths:** Resolved absolute path
**Discovery rules:**
1. **Direct files:** `extensions/*.ts` or `*.js` → loaded directly
2. **Subdirectory with index:** `extensions/myext/index.ts` → loaded as single extension
3. **Subdirectory with package.json:** `extensions/myext/package.json` with `"pi"` field → loads declared paths
```
~/.pi/agent/extensions/
├── simple.ts # Direct file (auto-discovered)
├── my-tool/
│ └── index.ts # Subdirectory with index (auto-discovered)
└── my-extension-pack/
├── package.json # Declares multiple extensions
├── node_modules/ # Dependencies installed here
└── src/
├── safety-gates.ts # First extension
└── custom-tools.ts # Second extension
```
```json
// my-extension-pack/package.json
{
"name": "my-extension-pack",
"dependencies": {
"zod": "^3.0.0"
},
"pi": {
"extensions": ["./src/safety-gates.ts", "./src/custom-tools.ts"],
"skills": ["./skills/"],
"prompts": ["./prompts/"],
"themes": ["./themes/dark.json"]
}
}
```
The pi manifest supports glob patterns and exclusions:
```json
{
"pi": {
"extensions": ["./extensions", "!**/deprecated/*"],
"skills": ["./skills", "!**/experimental/*"],
"themes": ["./themes/*.json"]
}
}
```
**Bundling other pi packages:**
To include resources from another pi package, add it as a dependency with `bundledDependencies` to ensure it's embedded in your published tarball:
```json
{
"name": "my-extension-pack",
"dependencies": {
"other-pi-package": "^1.0.0"
},
"bundledDependencies": [
"other-pi-package"
],
"pi": {
"extensions": [
"./extensions",
"./node_modules/other-pi-package/extensions",
"!**/unwanted-extension.ts"
],
"skills": [
"./skills",
"./node_modules/other-pi-package/skills"
]
}
}
```
`bundledDependencies` embeds the package inside your tarball, preserving the `node_modules/` structure. Without it, npm's hoisting could move the dependency elsewhere, breaking the paths.
**Discoverability:** Add the `pi-package` keyword to your `package.json` so users can find your package on npm:
```json
{
"name": "my-extension-pack",
"keywords": ["pi-package", "pi-extension", "..."],
...
}
```
Search for pi packages: `curl -s "https://registry.npmjs.org/-/v1/search?text=keywords:pi-package"`
The `package.json` approach enables:
- Multiple extensions from one package
- Skills, prompts, and themes declared alongside extensions
- Third-party npm dependencies (resolved via jiti)
- Nested source structure (no depth limit within the package)
- Deployment to and installation from npm
To share extensions via npm or git, see [packages.md](packages.md).
## Available Imports