diff --git a/plugins/kyberforge/.apm/skills/apm-install/README.md b/plugins/kyberforge/.apm/skills/apm-install/README.md index 5cacb8f..995a182 100644 --- a/plugins/kyberforge/.apm/skills/apm-install/README.md +++ b/plugins/kyberforge/.apm/skills/apm-install/README.md @@ -4,7 +4,7 @@ Installs and configures the `apm` (Agent Package Manager) CLI and the agent runt ## What it does -Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to). +Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to). ## Usage diff --git a/plugins/kyberforge/.apm/skills/apm-install/SKILL.md b/plugins/kyberforge/.apm/skills/apm-install/SKILL.md index abb520a..9b249ea 100644 --- a/plugins/kyberforge/.apm/skills/apm-install/SKILL.md +++ b/plugins/kyberforge/.apm/skills/apm-install/SKILL.md @@ -1,13 +1,9 @@ --- name: apm-install description: > - Use when the user wants to install the apm (Agent Package Manager) CLI - itself, pin or upgrade its version, set up an air-gapped/enterprise mirror - install, or install and manage an agent runtime that apm drives (Copilot - CLI, Codex, Gemini, generic llm) — "install apm", "set up apm", "pin apm to - a version", "apm runtime setup", "which runtime will apm run pick". Do not - use for authoring apm.yml, scaffolding a package/marketplace, compiling, - packing, publishing, or running apm audit — use apm-workflow for those. + Use when installing, pinning, or upgrading the apm (Agent Package Manager) + CLI itself, or installing and managing an agent runtime apm drives. Not + authoring, publishing, or auditing apm packages -> `apm-workflow`. metadata: category: apm source_keys: @@ -16,13 +12,12 @@ metadata: ## Gotchas -- apm does not execute agents itself — it only installs and manages the runtimes that do. "Install apm" and "install a runtime apm manages" are two separate steps; don't conflate them or skip the second when the user actually wants a working agent CLI, not just the package manager. -- The air-gapped/enterprise mirror path needs `GITHUB_URL` and `VERSION` set together against a downloaded `install.sh` — it does not work through the piped one-liner form. -- `pip install apm-cli` requires Python 3.10+; the quick-install script has no such prerequisite. Prefer the quick-install script unless the environment is pip-first. -- On a Debian/externally-managed Python environment (PEP 668), `pip install apm-cli` fails immediately with `error: externally-managed-environment`. Fall back to `pipx install apm-cli` — same PyPI package, but pipx creates an isolated venv and correctly exposes the `apm` binary on `PATH`. -- Installing the Copilot CLI runtime through `apm runtime setup copilot` requires Node.js v22+ and npm v10+ already present — apm does not install Node/npm for you. +- apm never executes an agent itself — it only installs and manages the runtimes that do. Installing apm alone leaves the user with a package manager and no working agent CLI, so Step 2 is required whenever the user actually wants one; skip it only when they explicitly want the package manager alone. +- `apm runtime setup copilot` needs Node.js v22+ and npm v10+ already on `PATH`; apm will not install them for you. -## Install apm +## Step 1 — Install the apm CLI + +If `apm --version` already answers and the user is not pinning or upgrading, skip to Step 2. Default: @@ -31,16 +26,17 @@ curl -sSL https://aka.ms/apm-unix | sh ``` Escape hatches — combine as needed: -- Pin a version: append `@vX.Y.Z` to the piped script's arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`. -- Custom install directory: set `APM_INSTALL_DIR` on the piped script's command, e.g. `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`. -- Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`. -- pip (Python 3.10+ environments): `pip install apm-cli`. -- pipx (externally-managed/PEP 668 environments where plain `pip install` fails, e.g. Debian): `pipx install apm-cli`. -- Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`. + +- **Pin a version** — append `@vX.Y.Z` to the piped script's arguments: `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`. +- **Custom install directory** — set `APM_INSTALL_DIR` on the piped script's command: `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`. +- **Air-gapped mirror / GitHub Enterprise** — an air-gapped host cannot reach `aka.ms` at all, so get `install.sh` onto the box and run it from disk instead of piping. Point it at the mirror with `APM_RELEASE_BASE_URL` and pin `VERSION`: `APM_RELEASE_BASE_URL=https://mirror.corp/apm VERSION=v1.2.3 sh install.sh`; add `APM_RELEASE_METADATA_URL` instead if you leave `VERSION` unset. `GITHUB_URL` is the GitHub Enterprise host, not a release mirror. All four are ordinary environment variables that also work through the pipe — running from disk is a network constraint, not a script one. +- **pip** — `pip install apm-cli` requires Python 3.10+. Not on an externally-managed (PEP 668) Python such as Debian or Ubuntu, where it hard-fails with `error: externally-managed-environment`; use pipx below. The quick-install script has no Python prerequisite, so prefer it unless the environment is pip-first. +- **pipx** — `pipx install apm-cli` on those PEP 668 environments. Same PyPI package, but pipx builds an isolated venv and exposes `apm` on `PATH`. +- **Manual** — download the platform archive from the GitHub releases page, extract, and place the binary on `PATH`. Verify with `apm --version`. -## Install or manage an agent runtime +## Step 2 — Install or manage an agent runtime Default: diff --git a/plugins/kyberforge/skills/apm-install/README.md b/plugins/kyberforge/skills/apm-install/README.md index 5cacb8f..995a182 100644 --- a/plugins/kyberforge/skills/apm-install/README.md +++ b/plugins/kyberforge/skills/apm-install/README.md @@ -4,7 +4,7 @@ Installs and configures the `apm` (Agent Package Manager) CLI and the agent runt ## What it does -Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to). +Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to). ## Usage diff --git a/plugins/kyberforge/skills/apm-install/SKILL.md b/plugins/kyberforge/skills/apm-install/SKILL.md index abb520a..9b249ea 100644 --- a/plugins/kyberforge/skills/apm-install/SKILL.md +++ b/plugins/kyberforge/skills/apm-install/SKILL.md @@ -1,13 +1,9 @@ --- name: apm-install description: > - Use when the user wants to install the apm (Agent Package Manager) CLI - itself, pin or upgrade its version, set up an air-gapped/enterprise mirror - install, or install and manage an agent runtime that apm drives (Copilot - CLI, Codex, Gemini, generic llm) — "install apm", "set up apm", "pin apm to - a version", "apm runtime setup", "which runtime will apm run pick". Do not - use for authoring apm.yml, scaffolding a package/marketplace, compiling, - packing, publishing, or running apm audit — use apm-workflow for those. + Use when installing, pinning, or upgrading the apm (Agent Package Manager) + CLI itself, or installing and managing an agent runtime apm drives. Not + authoring, publishing, or auditing apm packages -> `apm-workflow`. metadata: category: apm source_keys: @@ -16,13 +12,12 @@ metadata: ## Gotchas -- apm does not execute agents itself — it only installs and manages the runtimes that do. "Install apm" and "install a runtime apm manages" are two separate steps; don't conflate them or skip the second when the user actually wants a working agent CLI, not just the package manager. -- The air-gapped/enterprise mirror path needs `GITHUB_URL` and `VERSION` set together against a downloaded `install.sh` — it does not work through the piped one-liner form. -- `pip install apm-cli` requires Python 3.10+; the quick-install script has no such prerequisite. Prefer the quick-install script unless the environment is pip-first. -- On a Debian/externally-managed Python environment (PEP 668), `pip install apm-cli` fails immediately with `error: externally-managed-environment`. Fall back to `pipx install apm-cli` — same PyPI package, but pipx creates an isolated venv and correctly exposes the `apm` binary on `PATH`. -- Installing the Copilot CLI runtime through `apm runtime setup copilot` requires Node.js v22+ and npm v10+ already present — apm does not install Node/npm for you. +- apm never executes an agent itself — it only installs and manages the runtimes that do. Installing apm alone leaves the user with a package manager and no working agent CLI, so Step 2 is required whenever the user actually wants one; skip it only when they explicitly want the package manager alone. +- `apm runtime setup copilot` needs Node.js v22+ and npm v10+ already on `PATH`; apm will not install them for you. -## Install apm +## Step 1 — Install the apm CLI + +If `apm --version` already answers and the user is not pinning or upgrading, skip to Step 2. Default: @@ -31,16 +26,17 @@ curl -sSL https://aka.ms/apm-unix | sh ``` Escape hatches — combine as needed: -- Pin a version: append `@vX.Y.Z` to the piped script's arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`. -- Custom install directory: set `APM_INSTALL_DIR` on the piped script's command, e.g. `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`. -- Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`. -- pip (Python 3.10+ environments): `pip install apm-cli`. -- pipx (externally-managed/PEP 668 environments where plain `pip install` fails, e.g. Debian): `pipx install apm-cli`. -- Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`. + +- **Pin a version** — append `@vX.Y.Z` to the piped script's arguments: `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`. +- **Custom install directory** — set `APM_INSTALL_DIR` on the piped script's command: `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`. +- **Air-gapped mirror / GitHub Enterprise** — an air-gapped host cannot reach `aka.ms` at all, so get `install.sh` onto the box and run it from disk instead of piping. Point it at the mirror with `APM_RELEASE_BASE_URL` and pin `VERSION`: `APM_RELEASE_BASE_URL=https://mirror.corp/apm VERSION=v1.2.3 sh install.sh`; add `APM_RELEASE_METADATA_URL` instead if you leave `VERSION` unset. `GITHUB_URL` is the GitHub Enterprise host, not a release mirror. All four are ordinary environment variables that also work through the pipe — running from disk is a network constraint, not a script one. +- **pip** — `pip install apm-cli` requires Python 3.10+. Not on an externally-managed (PEP 668) Python such as Debian or Ubuntu, where it hard-fails with `error: externally-managed-environment`; use pipx below. The quick-install script has no Python prerequisite, so prefer it unless the environment is pip-first. +- **pipx** — `pipx install apm-cli` on those PEP 668 environments. Same PyPI package, but pipx builds an isolated venv and exposes `apm` on `PATH`. +- **Manual** — download the platform archive from the GitHub releases page, extract, and place the binary on `PATH`. Verify with `apm --version`. -## Install or manage an agent runtime +## Step 2 — Install or manage an agent runtime Default: