shortcutxl 0.2.12 → 0.2.13

package/agent-docs/docs/packages.md

@@ -1,209 +1,209 @@
-> Shortcut can help you create Shortcut packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
-
-# Shortcut Packages
-
-Shortcut packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `shortcut` key, or use conventional directories.
-
-## Table of Contents
-
-- [Install and Manage](#install-and-manage)
-- [Package Sources](#package-sources)
-- [Creating a Shortcut Package](#creating-a-shortcut-package)
-- [Package Structure](#package-structure)
-- [Dependencies](#dependencies)
-- [Package Filtering](#package-filtering)
-- [Enable and Disable Resources](#enable-and-disable-resources)
-- [Scope and Deduplication](#scope-and-deduplication)
-
-## Install and Manage
-
-> **Security:** Shortcut packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
-
-```bash
-shortcut install npm:@foo/bar@1.0.0
-shortcut install git:github.com/user/repo@v1
-shortcut install https://github.com/user/repo  # raw URLs work too
-shortcut install /absolute/path/to/package
-shortcut install ./relative/path/to/package
-
-shortcut remove npm:@foo/bar
-shortcut list    # show installed packages from settings
-shortcut update  # update all non-pinned packages
-```
-
-By default, `install` and `remove` write to global settings (`~/.shortcut/agent/settings.json`). Use `-l` to write to project settings (`.shortcut/settings.json`) instead. Project settings can be shared with your team, and Shortcut installs any missing packages automatically on startup.
-
-To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
-
-```bash
-shortcut -e npm:@foo/bar
-shortcut -e git:github.com/user/repo
-```
-
-## Package Sources
-
-Shortcut accepts three source types in settings and `shortcut install`.
-
-### npm
-
-```
-npm:@scope/pkg@1.2.3
-npm:pkg
-```
-
-- Versioned specs are pinned and skipped by `shortcut update`.
-- Global installs use `npm install -g`.
-- Project installs go under `.shortcut/npm/`.
-
-### git
-
-```
-git:github.com/user/repo@v1
-git:git@github.com:user/repo@v1
-https://github.com/user/repo@v1
-ssh://git@github.com/user/repo@v1
-```
-
-- Without `git:` prefix, only protocol URLs are accepted (`https://`, `http://`, `ssh://`, `git://`).
-- With `git:` prefix, shorthand formats are accepted, including `github.com/user/repo` and `git@github.com:user/repo`.
-- HTTPS and SSH URLs are both supported.
-- SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).
-- For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
-- Refs pin the package and skip `shortcut update`.
-- Cloned to `~/.shortcut/agent/git/<host>/<path>` (global) or `.shortcut/git/<host>/<path>` (project).
-- Runs `npm install` after clone or pull if `package.json` exists.
-
-**SSH examples:**
-```bash
-# git@host:path shorthand (requires git: prefix)
-shortcut install git:git@github.com:user/repo
-
-# ssh:// protocol format
-shortcut install ssh://git@github.com/user/repo
-
-# With version ref
-shortcut install git:git@github.com:user/repo@v1.0.0
-```
-
-### Local Paths
-
-```
-/absolute/path/to/package
-./relative/path/to/package
-```
-
-Local paths point to files or directories on disk and are added to settings without copying. Relative paths are resolved against the settings file they appear in. If the path is a file, it loads as a single extension. If it is a directory, Shortcut loads resources using package rules.
-
-## Creating a Shortcut Package
-
-Add a `shortcut` manifest to `package.json` or use conventional directories. Include the `shortcut-package` keyword for discoverability.
-
-```json
-{
-  "name": "my-package",
-  "keywords": ["shortcut-package"],
-  "shortcut": {
-    "extensions": ["./extensions"],
-    "skills": ["./skills"],
-    "prompts": ["./prompts"],
-    "themes": ["./themes"]
-  }
-}
-```
-
-Paths are relative to the package root. Arrays support glob patterns and `!exclusions`.
-
-### Gallery Metadata
-
-Packages tagged with `shortcut-package` are discoverable via npm search. Add `video` or `image` fields to show a preview:
-
-```json
-{
-  "name": "my-package",
-  "keywords": ["shortcut-package"],
-  "shortcut": {
-    "extensions": ["./extensions"],
-    "video": "https://example.com/demo.mp4",
-    "image": "https://example.com/screenshot.png"
-  }
-}
-```
-
-- **video**: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
-- **image**: PNG, JPEG, GIF, or WebP. Displayed as a static preview.
-
-If both are set, video takes precedence.
-
-## Package Structure
-
-### Convention Directories
-
-If no `shortcut` manifest is present, Shortcut auto-discovers resources from these directories:
-
-- `extensions/` loads `.ts` and `.js` files
-- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
-- `prompts/` loads `.md` files
-- `themes/` loads `.json` files
-
-## Dependencies
-
-Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When Shortcut installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
-
-Shortcut bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `shortcutxl`, `@sinclair/typebox`.
-
-Other Shortcut packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Shortcut loads packages with separate module roots, so separate installs do not collide or share modules.
-
-Example:
-
-```json
-{
-  "dependencies": {
-    "shitty-extensions": "^1.0.1"
-  },
-  "bundledDependencies": ["shitty-extensions"],
-  "shortcut": {
-    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
-    "skills": ["skills", "node_modules/shitty-extensions/skills"]
-  }
-}
-```
-
-## Package Filtering
-
-Filter what a package loads using the object form in settings:
-
-```json
-{
-  "packages": [
-    "npm:simple-pkg",
-    {
-      "source": "npm:my-package",
-      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
-      "skills": [],
-      "prompts": ["prompts/review.md"],
-      "themes": ["+themes/legacy.json"]
-    }
-  ]
-}
-```
-
-`+path` and `-path` are exact paths relative to the package root.
-
-- Omit a key to load all of that type.
-- Use `[]` to load none of that type.
-- `!pattern` excludes matches.
-- `+path` force-includes an exact path.
-- `-path` force-excludes an exact path.
-- Filters layer on top of the manifest. They narrow down what is already allowed.
-
-## Enable and Disable Resources
-
-Use `shortcut config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.shortcut/agent`) and project (`.shortcut/`) scopes.
-
-## Scope and Deduplication
-
-Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
-
-- npm: package name
-- git: repository URL without ref
-- local: resolved absolute path
+> Shortcut can help you create Shortcut packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
+
+# Shortcut Packages
+
+Shortcut packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `shortcut` key, or use conventional directories.
+
+## Table of Contents
+
+- [Install and Manage](#install-and-manage)
+- [Package Sources](#package-sources)
+- [Creating a Shortcut Package](#creating-a-shortcut-package)
+- [Package Structure](#package-structure)
+- [Dependencies](#dependencies)
+- [Package Filtering](#package-filtering)
+- [Enable and Disable Resources](#enable-and-disable-resources)
+- [Scope and Deduplication](#scope-and-deduplication)
+
+## Install and Manage
+
+> **Security:** Shortcut packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+
+```bash
+shortcut install npm:@foo/bar@1.0.0
+shortcut install git:github.com/user/repo@v1
+shortcut install https://github.com/user/repo  # raw URLs work too
+shortcut install /absolute/path/to/package
+shortcut install ./relative/path/to/package
+
+shortcut remove npm:@foo/bar
+shortcut list    # show installed packages from settings
+shortcut update  # update all non-pinned packages
+```
+
+By default, `install` and `remove` write to global settings (`~/.shortcut/agent/settings.json`). Use `-l` to write to project settings (`.shortcut/settings.json`) instead. Project settings can be shared with your team, and Shortcut installs any missing packages automatically on startup.
+
+To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
+
+```bash
+shortcut -e npm:@foo/bar
+shortcut -e git:github.com/user/repo
+```
+
+## Package Sources
+
+Shortcut accepts three source types in settings and `shortcut install`.
+
+### npm
+
+```
+npm:@scope/pkg@1.2.3
+npm:pkg
+```
+
+- Versioned specs are pinned and skipped by `shortcut update`.
+- Global installs use `npm install -g`.
+- Project installs go under `.shortcut/npm/`.
+
+### git
+
+```
+git:github.com/user/repo@v1
+git:git@github.com:user/repo@v1
+https://github.com/user/repo@v1
+ssh://git@github.com/user/repo@v1
+```
+
+- Without `git:` prefix, only protocol URLs are accepted (`https://`, `http://`, `ssh://`, `git://`).
+- With `git:` prefix, shorthand formats are accepted, including `github.com/user/repo` and `git@github.com:user/repo`.
+- HTTPS and SSH URLs are both supported.
+- SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).
+- For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
+- Refs pin the package and skip `shortcut update`.
+- Cloned to `~/.shortcut/agent/git/<host>/<path>` (global) or `.shortcut/git/<host>/<path>` (project).
+- Runs `npm install` after clone or pull if `package.json` exists.
+
+**SSH examples:**
+```bash
+# git@host:path shorthand (requires git: prefix)
+shortcut install git:git@github.com:user/repo
+
+# ssh:// protocol format
+shortcut install ssh://git@github.com/user/repo
+
+# With version ref
+shortcut install git:git@github.com:user/repo@v1.0.0
+```
+
+### Local Paths
+
+```
+/absolute/path/to/package
+./relative/path/to/package
+```
+
+Local paths point to files or directories on disk and are added to settings without copying. Relative paths are resolved against the settings file they appear in. If the path is a file, it loads as a single extension. If it is a directory, Shortcut loads resources using package rules.
+
+## Creating a Shortcut Package
+
+Add a `shortcut` manifest to `package.json` or use conventional directories. Include the `shortcut-package` keyword for discoverability.
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["shortcut-package"],
+  "shortcut": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
+}
+```
+
+Paths are relative to the package root. Arrays support glob patterns and `!exclusions`.
+
+### Gallery Metadata
+
+Packages tagged with `shortcut-package` are discoverable via npm search. Add `video` or `image` fields to show a preview:
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["shortcut-package"],
+  "shortcut": {
+    "extensions": ["./extensions"],
+    "video": "https://example.com/demo.mp4",
+    "image": "https://example.com/screenshot.png"
+  }
+}
+```
+
+- **video**: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
+- **image**: PNG, JPEG, GIF, or WebP. Displayed as a static preview.
+
+If both are set, video takes precedence.
+
+## Package Structure
+
+### Convention Directories
+
+If no `shortcut` manifest is present, Shortcut auto-discovers resources from these directories:
+
+- `extensions/` loads `.ts` and `.js` files
+- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
+- `prompts/` loads `.md` files
+- `themes/` loads `.json` files
+
+## Dependencies
+
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When Shortcut installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
+
+Shortcut bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `shortcutxl`, `@sinclair/typebox`.
+
+Other Shortcut packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Shortcut loads packages with separate module roots, so separate installs do not collide or share modules.
+
+Example:
+
+```json
+{
+  "dependencies": {
+    "shitty-extensions": "^1.0.1"
+  },
+  "bundledDependencies": ["shitty-extensions"],
+  "shortcut": {
+    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
+    "skills": ["skills", "node_modules/shitty-extensions/skills"]
+  }
+}
+```
+
+## Package Filtering
+
+Filter what a package loads using the object form in settings:
+
+```json
+{
+  "packages": [
+    "npm:simple-pkg",
+    {
+      "source": "npm:my-package",
+      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
+      "skills": [],
+      "prompts": ["prompts/review.md"],
+      "themes": ["+themes/legacy.json"]
+    }
+  ]
+}
+```
+
+`+path` and `-path` are exact paths relative to the package root.
+
+- Omit a key to load all of that type.
+- Use `[]` to load none of that type.
+- `!pattern` excludes matches.
+- `+path` force-includes an exact path.
+- `-path` force-excludes an exact path.
+- Filters layer on top of the manifest. They narrow down what is already allowed.
+
+## Enable and Disable Resources
+
+Use `shortcut config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.shortcut/agent`) and project (`.shortcut/`) scopes.
+
+## Scope and Deduplication
+
+Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
+
+- npm: package name
+- git: repository URL without ref
+- local: resolved absolute path